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 content design
Title
- Each permanent node provides an informative and distinct tile that is easy to reference and identify, title is written with capitalised initial letters.
Linking
- Use in text links to reference to other relevant nodes.
- A link can be in the form of supplementary link (enclosed within brackets as supportive information), or implicit link (embedded text link).
Footer area
- 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 denoted by keywords that identify a node.
- Tags are in order of their significance level, formatted using snake_case to separate words, such asKnowledge_domainSub_knowledge_domainkeyword1keyword2.
- If a node is related to a specific unit or course, specify the unit or course code in the tags.
- Reference
- Reference links for websites are placed in the footer area.
Formatting guidelines
Use proper formatting options for different purposes in wiki content.
| 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 |
| num. | Numbered lists for logical orders; if a number item has descriptive text or nested numbers, bold the item title |
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.
- When using folded callout, use a short description as title.
- When using unfolded callout, use the default title.
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
INFRASTRUCTUREwiki_design_specwiki_design_principlecommunity_code_of_conduct