Managing Links

This guide explains how to enhance your Markdown documentation by linking to additional resources, both within your project and on external sites. By following these steps, you'll provide readers with a more engaging and comprehensive exploration of your content.

Prerequisites

• Basic knowledge of Markdown syntax.
• Access to your Markdown documentation files.

Goal

To effectively link to internal and external resources in Markdown documentation, enriching the reader's experience and understanding.

Link Within Your Documentation

Link to Another Document

1. Identify the Target Document: Find the document you wish to link to, noting its relative path.

2. Create the Link: Use Markdown syntax for linking. Example:

   [Setting Up Your Environment](../setup-environment)

Note: The path should begin with ../ and should not include the .md file extension. This is due to a current limitation in the build engine. It will be updated to be more intuitive in a future update.

Link to a Specific Section

1. Find the Section Title: Select the section within a document you wish to link to.

2. Format the Anchor: Modify the section title to create an anchor (lowercase, replace spaces with hyphens, prefix with #).

3. Insert the Link: Example:

   [configuring your setup](#configuring-your-setup)

Link to External Resources

1. Select the External Resource: Identify a relevant and reliable external source.

2. Use the Full URL: Employ Markdown syntax, including the full URL:

   [Markdown Guide](https://www.markdownguide.org)

Link to Draw IO Diagram

To easily include a link to view a drawio diagram file, simply add a normal markdown link to the diagram file. The website will detect that this is a link to a diagram and update the link to use the viewer.diagrams.net tool.

[Link Test](relative/path/to/file.darawio)

Embedding a Draw IO Diagram

The following HTML snippet can be used to directly embed the diagram into the page instead of opening in a new tab.

<iframe src="https://viewer.diagrams.net/?lightbox=1&nav=1&url={{metadata.rootUrl}}/[Relative Link to File.drawio]" width="100%" height="500px"></iframe>

Including the {{metadata.rootUrl}} is necessary to allow the viewer tool to correctly link to the diagram file.

Additional Information

To ensure the effectiveness and reliability of your links, follow these best practices:

• Use Descriptive Text: Link text should be informative and relevant.
• Verify Links: Verify links are active and up-to-date while reviewing the document.
• Prefer Relative Links for Internal Documents: Enhances documentation robustness.

For more information about Markdown link syntax, check out the Markdown Cheatsheet.

Conclusion

By integrating additional resources into your Markdown documentation, you significantly enhance its value and effectiveness. Following the outlined steps and best practices, you'll create a richer, more interconnected experience for your readers.