Skip to content

Markdown and MKDocs tips

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](

[link text](


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


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]({: style="height:150px;width:150px"}

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

Last update: 2023-04-24