MD034 - Bare URL Used
Severity: Warning
Category: Links
Auto-fix: ✓ Available
Rule Description
This rule flags bare URLs that should be enclosed in angle brackets or converted to proper markdown links. Bare URLs may not be clickable in all markdown renderers.
Why This Rule Exists
Proper URL formatting is important because:
- Ensures URLs are clickable in all markdown renderers
- Improves document accessibility
- Provides consistent link formatting
- Allows for descriptive link text
Examples
❌ Incorrect (violates rule)
Visit https://example.com for more information.
Check out http://github.com/user/repo
Documentation at www.example.org
✅ Correct
Visit <https://example.com> for more information.
Check out [this repository](http://github.com/user/repo)
Documentation at [example.org](https://www.example.org)
<!-- URLs in code blocks are ignored -->
git clone https://github.com/user/repo.git
Configuration
This rule has no configuration options.
Automatic Fix
This rule supports automatic fixing with --fix. The fix will:
- Wrap bare URLs in angle brackets (
<URL>) - Preserve surrounding text and formatting
- Skip URLs in code blocks and inline code
- Handle both HTTP and HTTPS URLs
Apply Fix
# Fix bare URLs
mdbook-lint lint --fix docs/
# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/
Manual Enhancement
After auto-fix, consider manually converting to descriptive links:
<!-- After auto-fix -->
Visit <https://example.com> for more information.
<!-- Better: manually add descriptive text -->
Visit [our website](https://example.com) for more information.
When to Disable
Consider disabling this rule if:
- Your markdown renderer automatically links bare URLs
- You're documenting URLs that shouldn't be clickable
- Your content includes many URLs in plain text format
Disable in Config
# .mdbook-lint.toml
disabled_rules = ["MD034"]
Disable Inline
<!-- mdbook-lint-disable MD034 -->
Plain URL: https://example.com
<!-- mdbook-lint-enable MD034 -->