Design specifications outline detailed guidelines that enforce the design principles within our wiki.
Node classification
- Create or identify a higher level category for your node (often the domain root node, which shares the same name as its corresponding directory in the wiki file system)
- Make sure your node is associate with the appropriate category.
- Establish connection with the domain, you should link your node to the domain root node or any sub-node within the domain.
Media and attachments
All media, including pictures, are stored under the “Attachments” directory, place your media in the appropriate subdirectory, create new subdirectory if it does not already exist.
Node structure
Title
- Each permanent node provides an informative and distinct tile that is easy to reference and identify. Node title is written in title case, which is Capitalised Initial Letters.
Headers
- Use headers and sub-headers to organise content. Write headers with the First letter capitalised.
Linking
- Use in text links to reference to other relevant nodes.
- Links can take the form of:
- Supplementary links: Enclosed in brackets as supporting information.
- Implicit links: Embedded directly in the text.
Footer area
The footer area contains below information in order.
- Back to parent page
- When organising nodes in hierarchical approach, nodes should include a “Back to parent page: <parent_node>” that points the current node to the super node in the domain hierarchy.
- A node may have multiple parents span in different domains, choose the one that reflects the best belonging.
- Tags
- Tags are keywords that categorise a node.
- Tags are formatted using Snake_Case to separate words, such as Knowledge_Domain Sub_Knowledge_Domain Keyword1 Keyword2.
- If a node is related to a specific unit or course, specify the unit or course code in the tags.
- Reference
- Reference links to any external resources.
Formatting guidelines
| Markup | Use Case |
|---|---|
| Bold | Keyword or phase |
| Italic | Jargon or specialised term |
| underline | Key sentence |
| *text | Supporting information |
| - | Bullet points for concise guidelines; if a bullet point item has descriptive text or sub points, bold the item title; don’t end items with periods |
| num. | Numbered lists for logical orders; if a number item has descriptive text or nested numbers, bold the item title; don’t end items with periods |
code | Warp code snippet around with “ |
| ``` | Warp code statement or block around with backticks ``` |
``` {1-3, 4} | Place numeric range in the {} next to the starting backticks to highlight lines of code. This feature has to work with the Syntax Highlighting plugin |
Callouts
You can insert callouts to your contents, click for more about Obsidian Callouts.
Note, Same topic reference
Abstract, Summary
Info, Cross topic reference
Tip, Hint, Important
Success, Check, Done
Question, Help, FAQ
Warning, Caution, Attention
Failure, Fail, Missing
Danger, Error
Bug
Example
Quote, Cite
Back to parent page: Contributor Manual