Skip to content

Tips on writing docs

Linking to another dev-docs file

Use the markdown file name instead of providing a path.

Makes links more resilient when folders/files are moved.

[link text](my-markdown-file.md)

[link text](my-markdown-file.md#header)

Tables

  • Paste a Bookstack table into Zettlr or in a GitHub comment
    • it will generate the Markdown for the table

Images

Pasting images

Make sure to upload images to the ./images directory

Image paths

Ensure that paths to images are relative

  • so that they can be found by both GitHub and MKDocs
    • we need view images in GitHub for code review
    • Example ✅ : images/file_name.png
    • Bad example ❌ : /assets/path_to_image.png

Changing the image size

Markdown understands HTML. 🧠 You can use the img tag.

<img src="../image/file_name.png" alt="alt_text" height="300px" />

MKDocs way of adding a height or width

You can apply a height or width on the image

![image alt text](https://example.com/an_image.img){: style="height:150px;width:150px"}

This will be resized in MKDocs but not in GitHub during code review.


Last update: 2022-11-04