MD034 - URLs should be formatted as links¶
Aliases: no-bare-urls
What this rule does¶
Ensures URLs are properly formatted with angle brackets or as clickable links, not pasted as plain text.
Why this matters¶
- Clickability: Not all Markdown renderers make plain URLs clickable
- Consistency: Mixed URL formats look unprofessional
- Control: Proper link formatting lets you customize the display text
Examples¶
✅ Correct¶
For more information, see <https://example.com>.
Visit [our website](https://example.com) for details.
Email us at <contact@example.com>
Chat with me at <xmpp:user@example.com>
❌ Incorrect¶
For more information, see https://example.com.
Email us at contact@example.com
Chat with me at xmpp:user@example.com
🔧 Fixed¶
For more information, see <https://example.com>.
Email us at <contact@example.com>
Chat with me at <xmpp:user@example.com>
Configuration¶
This rule has no configuration options.
Automatic fixes¶
Outside the mdg flavor, this rule automatically wraps plain URLs, email
addresses, and XMPP URIs in angle brackets (< and >). Under mdg, it
reports without fixing; see below.
GFM extended autolinks¶
This rule supports GFM (GitHub Flavored Markdown) extended autolinks, including:
- HTTP/HTTPS URLs:
https://example.com - FTP URLs:
ftp://files.example.com - Email addresses:
user@example.com - XMPP URIs:
xmpp:user@example.comorxmpp:user@example.com/resource - WWW URLs without protocol:
www.example.com
Markdown with Gherkin¶
Under the mdg flavor, MD034 reports bare URLs and email addresses but does not
offer a fix. <https://example.com> is Gherkin placeholder syntax rather than
an autolink: inside a Scenario Outline it is substituted from the Examples
column of that name, so the standard angle-bracket fix could change the parsed
scenario.
The safe response depends on context. An explicit Markdown link may be suitable for prose, but changing a step to Markdown link syntax also changes its step text. Format the link manually when that change is intended, or disable MD034 for content where a bare URL or email address is the required spelling.
See Markdown with Gherkin Flavor for the full flavor specification.
Learn more¶
- CommonMark autolinks - Technical specification for URL formatting
- GFM autolinks extension - GFM extended autolinks specification
- Markdown Guide - Links - Best practices for links