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 <[email protected]>
Chat with me at <xmpp:[email protected]>
❌ Incorrect¶
For more information, see https://example.com.
Email us at [email protected]
Chat with me at xmpp:[email protected]
🔧 Fixed¶
For more information, see <https://example.com>.
Email us at <[email protected]>
Chat with me at <xmpp:[email protected]>
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:
[email protected] - XMPP URIs:
xmpp:[email protected]orxmpp:[email protected]/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.
GitHub Agentic Workflows¶
Under the gh-aw flavor, MD034 skips complete, recognized gh-aw control lines.
For example, it leaves a URL inside {{#runtime-import https://example.com/shared.md}}
unchanged because inserting angle brackets would corrupt the template syntax.
URLs in workflow body prose are still reported and fixed normally. See the
GitHub Agentic Workflows flavor for the exact directive set.
Learn more¶
- CommonMark autolinks - Technical specification for URL formatting
- GFM autolinks extension - GFM extended autolinks specification
- Markdown Guide - Links - Best practices for links