TOP007 - Use markdown links

Tags: links, html

Aliases: use-markdown-links

Fixable via script: Replaces anchor tags with markdown links unless excepted (see below).

The rule is triggered when an anchor tag with an href attribute is used for a link outside of a code block (whether fenced or inline).

These links should be written as markdown links instead of anchors.

<!-- instead of an anchor -->
<a href="https://www.theodinproject.com/">The Odin Project</a>

<!-- use a markdown link -->
[The Odin Project](https://www.theodinproject.com/)

The knowledge-check-link class is not longer required for knowledge check links.

<!-- knowledge check items -->
- <a class="knowledge-check-link" href="#link-here">Text</a>

<!-- can be safely rewritten as markdown links without the class -->
- [Text](#link-here)

Exceptions

• Any anchors inside code blocks.
• Any anchors used for a codepen embed, as these do not require changing to markdown links.

Rationale

markdownlint is unable to lint HTML anchors with the same link-based rules as with markdown links. Therefore, anchors that would error with the TOP001 (Descriptive link text) rule would not error as an anchor. Converting to a markdown link will allow such rules to be used on it.

Other linting rules also cannot be used on most anchors' text, due to the way markdown parsers tokenize HTML elements when no blank lines are included (related to TOP005 (Blanks around multiline HTML tags)). _ emphasis markers (which should be *) will not trigger errors.

Anchors will also not automatically include target="_blank" or rel="noopener noreferrer" unless they are manually included. Markdown links are automatically converted by the web app to anchors with both of those attributes.

Anchors that are not used for this purpose (e.g. for Codepen embeds, as code inside code blocks etc.) do not require action.