Enhancing Your Documentation

Well-structured documentation is the backbone of any project, but engaging documentation often requires more than well-organized text. Enhancements like images, videos, tables, and internal links can significantly improve the readability and effectiveness of your documents. This tutorial explores how to leverage these elements in Markdown to enrich your Divio style documentation.

Incorporating Images and Videos

Images

To add images to your Markdown files, use the following syntax:

![Alt text](URL-to-image "Optional title")

• Alt text is a brief description of the image, enhancing accessibility.
• URL-to-image is the path to your image file. This can be a relative path within your project or an absolute path to an external source.
• Optional title appears as a tooltip when the mouse hovers over the image.

Videos

While Markdown doesn't natively support embedding videos, you can link to a video hosted on an external platform like YouTube or Vimeo. We have added support in the website to automatically convert YouTube and Vimeo links to embedded videos.

For example, simply adding this link to your document will render as an embedded video on the documentation website.

https://vimeo.com/758112565

Using Tables and Lists for Clarity

Tables

Tables organize information neatly and are great for comparison, parameters, or structured data. Create tables using pipes (|) and hyphens (-):

| Header 1 | Header 2 |
|----------|----------|
| Row 1    | Data     |
| Row 2    | Data     |

Lists

Lists help break down information into manageable, easy-to-scan parts. Use bullet points for unordered lists and numbers for ordered lists:

- Unordered list item 1
- Unordered list item 2

1. Ordered list item 1
2. Ordered list item 2

Creating Links Between Documentation Pages

Internal links keep your documentation interconnected, making it easier for readers to navigate related topics. To link to another document in your project, use relative paths:

[Link text](relative-path-to-file.md)

This approach helps readers smoothly transition between related documents, improving the overall coherence and usability of your documentation. If you are using Obsidian, you should be able to drag the file from the left navigation menu into your document, and it will create the correct relative link for you. Note that you will want to ensure that you have the correct Files and Links settings enabled as described in this tutorial: Working with Obsidian.

Conclusion

By integrating images, videos, tables, lists, and links into your Markdown documents, you can create more engaging, informative, and accessible documentation. These enhancements not only make your documentation more visually appealing but also improve its navigational structure, making it easier for users to find the information they need.

In our next tutorial, we will delve into advanced Markdown features in VS Code, exploring how extensions and tools can further streamline your documentation workflow and enhance productivity.