Skip to Content
DocumentationCode StandardsMarkdownLinks and Images

Links and Images

Links and images are essential parts of Markdown that enhance documentation by providing additional context and visual interest. Links can direct readers to resources, while images can illustrate concepts or provide visual examples. This document outlines how to effectively use links and images in Markdown, including syntax, common practices, and tips for the best usage.

Table of Contents

  • Enhancing Context: Links allow you to reference additional resources, providing readers with further information without cluttering the main document. Images can illustrate points, making information more digestible and engaging.

  • Improving Navigation: Links can improve user experience by linking to related topics, external websites, or internal sections within the same document.

  • Visual Appeal: Well-placed images break up text, adding visual interest that can attract readers’ attention.

Links in Markdown can be created using descriptive text that points to a URL. There are two primary types of links: inline and reference links.

[Link Text](URL)

Example:

[Circle](https://www.circle.com)

Creating Images

Images in Markdown are similar to links but include an exclamation mark (!) before the syntax.

Syntax for Displaying Images:

![Alt Text](URL)

Example:

![Circle Logo](https://www.circle.com/logo.png)

Image Formatting Options

Markdown allows for some basic control over image size and alignment through HTML tags in combination with Markdown, though this may depend on the Markdown processor you are using.

Example Using HTML for Sizing:

<img src="https://www.circle.com/logo.png" alt="Circle Logo" width="300"/>

This approach can provide more control over the size if the Markdown renderer supports HTML.

You can create a clickable image by combining both link and image syntax.

Example:

[![Circle Logo](https://www.circle.com/logo.png)](https://www.circle.com)

In this case, clicking the image will take the user to the specified URL.

Best Practices

  • Descriptive Text for Links: Use clear and descriptive link text that indicates the destination. Avoid vague terms like “click here” to promote better accessibility.

  • Alt Text for Images: Always include meaningful alt text for images. This enhances accessibility for screen readers and provides context in case the image does not load.

  • Check Links Regularly: Ensure that links are functional and lead to the correct destination. Broken links can lead to a frustrating user experience.

  • Use Relative Links When Applicable: For internal documentation, use relative links instead of absolute links if possible. This approach aids consistency when moving folders or repositories.

Conclusion

Using links and images effectively in Markdown can significantly enhance your documentation by providing clarity, context, and visual engagement. By following the guidelines and best practices outlined in this document, you can create rich, informative content that is both user-friendly and accessible.

Last updated on
HeadingsLists