Skip to content

Guidelines for Wiki Authors

Language and Styling

  • Use british english
  • Capitalize important WissKI terms and link them to the respective glossary entry; e.g. Pathbuilder
  • Use bold or italics sparingly.

Markdown and File Structure

  • Use the markdown header for defining title and tags:

     ---
 title: Some Title
 tags:
     - Tag1
     - Tag2
 ---

  • Use relative links to other documentation pages:

    [Pathbuilder](../../glossary/pathbuilder.md)

    Absolute links will show up as errors in the logs, which makes it difficult to find links that are actually broken. Use the full filename including extension when linking to another file, even though it may be annoying. You can look into the logs with docker compose logs -f, they will tell you where there may be broken links and how to fix them.

  • Use short snake_case filenames Use the title header to set descriptive titles. These will also show up in the navigation sidebar.

  • Use a line break after a full stop. This makes the Markdown files way more readable.
  • To use the tags to generate lists refer to the mkdocs tag documentation.

  • Feel free to use mkdocs admonitions Examples:

    Note

    This is a note!

    A collapsible tip with title!

    👻 Peekaboo!

    For more admonition types refer ro the supported types.

  • You can also use emojis. Some examples:

    • :ghost: → 👻
    • :cat: → 🐱

    Here is a quick reference sheet for markdown emojis. For a more technical list of available emojis refer to the twemoji database.

Glossary

  • Always link potentially unknown terms to the Glossary. If there's no entry yet, create a new one.
  • Create new glossary pages by using the Glossary-Entry.md template.
  • Put all glossary entries into the top-level Glossary directory. Do not use sub-directories.
  • A glossary entry should typically be a 10s-1min read and only cover the very basics. Ideally link to additional resources that provide more information like e.g. guides or external resources.

Spellchecker

The documentation also uses the cspell spellchecker that is used for spellchecking in the codebase. However there is a separate docs.txt dictionary. In case you have unknown words in your texts add them there, or just include the regular spellchecker annotation:

<!-- spellchecker:words YOUR_UNKNOWN_WORD ANOTHER_WORD -->

If you use this annotation, please put it at the bottom of the file. The markdown header has to be the first thing in the file, hence adding at the top is not possible.