#2567 - [GH-ISSUE #1616] MD034 - Bare URL used > advice gives code that fails npm/docusaurus md to html conversion/build - starred/markdownlint

kerem commented

2026-03-07 20:08:57 +03:00

Owner

Originally created by @TuxVinyards on GitHub (May 27, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1616

The advice given in doc/md034.md throws build errors with npm when using it:

To fix this, add angle brackets around the URL or email address:

For more info, visit <https://www.example.com/> or email <user@example.com>.

I have found that the following pattern in the Docusaurus templates works better instead:

For more info, visit [https://www.example.com/](https://www.example.com/) or email [user@example.com](user@example.com).

As in https://www.example.com/

Or https://github.com/facebook/docusaurus/blob/main/website/docs/deployment.mdx?plain=1 at line 44

Not sure how much this is a npm thing or how much it is Docusaurus.

Obviously it doesn't happen with GitHub readme files but maybe other .md convertors are affected too?

Originally created by @TuxVinyards on GitHub (May 27, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1616 The advice given in [doc/md034.md](doc/md034.md) throws build errors with `npm` when using it: > To fix this, add angle brackets around the URL or email address: ```markdown For more info, visit <https://www.example.com/> or email <user@example.com>. ``` I have found that the following pattern in the Docusaurus templates works better instead: ```markdown For more info, visit [https://www.example.com/](https://www.example.com/) or email [user@example.com](user@example.com). ``` As in [https://www.example.com/](https://www.example.com/) Or [https://github.com/facebook/docusaurus/blob/main/website/docs/deployment.mdx?plain=1](https://github.com/facebook/docusaurus/blob/main/website/docs/deployment.mdx?plain=1) at line 44 Not sure how much this is a `npm` thing or how much it is Docusaurus. Obviously it doesn't happen with GitHub readme files but maybe other .md convertors are affected too?

kerem

2026-03-07 20:08:57 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:08:58 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 27, 2025):

These are both valid syntax for Markdown links, so I do not understand what you mean by "throws build errors with npm". Please explain that and give an example of what you think the problem is.

If you want to enforce a particular style for links and images (like above), you can use MD054 to do so: https://github.com/DavidAnson/markdownlint/blob/main/doc/md054.md

@DavidAnson commented on GitHub (May 27, 2025): These are both valid syntax for Markdown links, so I do not understand what you mean by "throws build errors with npm". Please explain that and give an example of what you think the problem is. If you want to enforce a particular style for links and images (like above), you can use MD054 to do so: https://github.com/DavidAnson/markdownlint/blob/main/doc/md054.md

kerem commented

2026-03-07 20:08:58 +03:00

Author

Owner

@TuxVinyards commented on GitHub (May 28, 2025):

Thanks for looking at this.

This issue is really a heads up to say that maybe the guidance in MD034 needs expanding or clarifying as it doesn't work in all cases. But it's your project, so your call ....

What's happening is GitHub allows both raw links and angle bracketed links in their markdown editor. At some stage while working on the .md files I must have pasted in some raw links. Later when I opened the files using VScode your linter pointed me to MD034 where I told:

To fix this, add angle brackets around the URL or email address

So this is what I did.

But I have now started looking at creating some github pages. I thought Docusaurus looked like an easy option but found myself getting errors:

<w> [webpack.cache.PackFileCacheStrategy] Skipped not serializable cache item 'Compilation/modules|/media/xxx/Files/GITHUB/test/docusaurus.testsite/my-website/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[8].use[0]!/media/xxx/Files/GITHUB/test/docusaurus.testsite/my-website/docs/intro.md': No serializer registered for VFileMessage
<w> while serializing webpack/lib/cache/PackFileCacheStrategy.PackContentItems -> webpack/lib/NormalModule -> webpack/lib/ModuleBuildError -> Error -> VFileMessage

[ERROR] Client bundle compiled with errors therefore further build is impossible.
Error: MDX compilation failed for file "/media/xxx/Files/GITHUB/test/docusaurus.testsite/my-website/docs/intro.md"
Cause: Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)
Details:
{
  "column": 8,
  "message": "Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)",
  "line": 9,
  "name": "9:8",
  "place": {
    "_bufferIndex": 7,
    "_index": 13,
    "line": 9,
    "column": 8,
    "offset": 109
  },
  "reason": "Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)",
  "ruleId": "unexpected-character",
  "source": "micromark-extension-mdx-jsx",
  "url": "https://github.com/micromark/micromark-extension-mdx-jsx#unexpected-character-at-expected-expect"
}

The advice, at the end of several of the lines, is:

(note: to create a link in MDX, use `[text](url)`)

and for me that solves the problem.

I just wanted to give you some feedback to say that To fix this, add angle brackets doesn't always fix things ....

I also did some further looking and ended up trying AI assist:

This conversation was generated with Duck.ai (https://duck.ai) using OpenAI's GPT-4o mini Model. 
====================

User prompt 1 of 3:
is it best to use angle or square brackets for markdown links to websites

Assist:
It is best to use square brackets for the link text followed by parentheses for the URL in Markdown links. For example, the correct format is [Link text](https://website.com).

But then there is this:

User prompt 2 of 3 - 28/5/2025, 12:08:54:
Are there cases where using angle brackets are better

GPT-4o mini:
Yes, there are cases where using angle brackets can be beneficial in Markdown:

1. **Plain URLs**: If you want to display a URL without any link text, you can use angle brackets. For example: `<https://example.com>` will render as a clickable link.

In turn countered by this:

User prompt 3 of 3 - 28/5/2025, 12:14:08:
Are there potential problems if I normally use square brackets, as in [https://example.com](https://example.com)

GPT-4o mini:
Using square brackets in the format `[https://example.com](https://example.com)` is perfectly valid in Markdown and will work correctly to create a hyperlink. However, there are a few potential issues to consider:

bla bla bla

In summary, while using square brackets with the URL as the link text is technically correct, it's often better to use descriptive text for improved clarity and accessibility.

So, use square brackets with a descriptor then, as in MD059 maybe?

@TuxVinyards commented on GitHub (May 28, 2025): Thanks for looking at this. This issue is really a heads up to say that maybe the guidance in MD034 needs expanding or clarifying as it doesn't work in all cases. But it's your project, so your call .... What's happening is GitHub allows both raw links and angle bracketed links in their markdown editor. At some stage while working on the .md files I must have pasted in some raw links. Later when I opened the files using VScode your linter pointed me to MD034 where I told: > To fix this, add angle brackets around the URL or email address So this is what I did. But I have now started looking at creating some github pages. I thought Docusaurus looked like an easy option but found myself getting errors: ``` <w> [webpack.cache.PackFileCacheStrategy] Skipped not serializable cache item 'Compilation/modules|/media/xxx/Files/GITHUB/test/docusaurus.testsite/my-website/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[8].use[0]!/media/xxx/Files/GITHUB/test/docusaurus.testsite/my-website/docs/intro.md': No serializer registered for VFileMessage <w> while serializing webpack/lib/cache/PackFileCacheStrategy.PackContentItems -> webpack/lib/NormalModule -> webpack/lib/ModuleBuildError -> Error -> VFileMessage [ERROR] Client bundle compiled with errors therefore further build is impossible. Error: MDX compilation failed for file "/media/xxx/Files/GITHUB/test/docusaurus.testsite/my-website/docs/intro.md" Cause: Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`) Details: { "column": 8, "message": "Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)", "line": 9, "name": "9:8", "place": { "_bufferIndex": 7, "_index": 13, "line": 9, "column": 8, "offset": 109 }, "reason": "Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)", "ruleId": "unexpected-character", "source": "micromark-extension-mdx-jsx", "url": "https://github.com/micromark/micromark-extension-mdx-jsx#unexpected-character-at-expected-expect" } ``` The advice, at the end of several of the lines, is: ``` (note: to create a link in MDX, use `[text](url)`) ``` and for me that solves the problem. I just wanted to give you some feedback to say that `To fix this, add angle brackets ` doesn't _always_ fix things .... I also did some further looking and ended up trying AI assist: ``` This conversation was generated with Duck.ai (https://duck.ai) using OpenAI's GPT-4o mini Model. ==================== User prompt 1 of 3: is it best to use angle or square brackets for markdown links to websites Assist: It is best to use square brackets for the link text followed by parentheses for the URL in Markdown links. For example, the correct format is [Link text](https://website.com). ```` But then there is this: ``` User prompt 2 of 3 - 28/5/2025, 12:08:54: Are there cases where using angle brackets are better GPT-4o mini: Yes, there are cases where using angle brackets can be beneficial in Markdown: 1. **Plain URLs**: If you want to display a URL without any link text, you can use angle brackets. For example: `<https://example.com>` will render as a clickable link. ``` In turn countered by this: ``` User prompt 3 of 3 - 28/5/2025, 12:14:08: Are there potential problems if I normally use square brackets, as in [https://example.com](https://example.com) GPT-4o mini: Using square brackets in the format `[https://example.com](https://example.com)` is perfectly valid in Markdown and will work correctly to create a hyperlink. However, there are a few potential issues to consider: bla bla bla In summary, while using square brackets with the URL as the link text is technically correct, it's often better to use descriptive text for improved clarity and accessibility. ``` So, use [square brackets with a descriptor](doc/md059.md) then, as in MD059 maybe?

kerem commented

2026-03-07 20:08:58 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 28, 2025):

This project is a linter for Markdown as defined by the CommonMark specification (including some common GitHub Flavored Markdown patterns). In your case, it looks like Docusaurus and/or MDX decided to break compatibility with CommonMark and not allow some valid syntax. In such cases, I recommend disabling the relevant lint rules or configuring them to accommodate the custom behavior. The advice given by MD034 is (still) a best practice for Markdown in my opinion.

@DavidAnson commented on GitHub (May 28, 2025): This project is a linter for Markdown as defined by the CommonMark specification (including some common GitHub Flavored Markdown patterns). In your case, it looks like Docusaurus and/or MDX decided to break compatibility with CommonMark and not allow some valid syntax. In such cases, I recommend disabling the relevant lint rules or configuring them to accommodate the custom behavior. The advice given by MD034 is (still) a best practice for Markdown in my opinion.

kerem commented

2026-03-07 20:08:58 +03:00

Author

Owner

@TuxVinyards commented on GitHub (May 29, 2025):

Much thanks for helping clear things up. The data-overload veil of confusion is starting to lift:

It seems that Docusaurus is indeed parsing plain .md files as .mdx unless you specify otherwise in the config. Also that their CommonMark parser does have wrinkles to iron out still. I will obviously have to embrace mdx or find a different system ....

MDX will generally parse CommonMark but autolinks are an exception. This is because .mdx files can contain JSX which is enclosed in angled brackets: https://github.com/micromark/mdx-state-machine#72-deviations-from-markdown

However, I do note that CommonMark itself is still a work in progress even at BabelMark3:

Looking at the current spec for autolinks it's clear that they are not a universal panacea and that they still have quite a few limitations themselves.

One of the links that I had had was this: https://en.wikipedia.org/wiki/Wayland_(protocol) but if we see https://spec.commonmark.org/0.31.2/#example-603 it would have in fact failed if angled brackets were used.

Putting a deep link to the specs #autolinks section, to one that is always the current version could be tricky (?) but a bit more on autolink limitations might be something to consider. I have used markdown for years on Wikipedia. I didn't know that the spec was so complicated.

This issue is probably good to close, I guess.

@TuxVinyards commented on GitHub (May 29, 2025): Much thanks for helping clear things up. The data-overload veil of confusion is starting to lift: It seems that Docusaurus is indeed parsing plain `.md` files as `.mdx` unless you specify otherwise in the config. Also that [their CommonMark parser](https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark) does have wrinkles to iron out still. I will obviously have to embrace mdx or find a different system .... [MDX](https://mdxjs.com/docs/what-is-mdx/#markdown) will generally parse CommonMark but autolinks are an exception. This is because `.mdx` files can contain JSX which is enclosed in angled brackets: [https://github.com/micromark/mdx-state-machine#72-deviations-from-markdown](https://github.com/micromark/mdx-state-machine#72-deviations-from-markdown) However, I do note that CommonMark itself is still a work in progress even at BabelMark3: Looking at the [current spec for autolinks](https://spec.commonmark.org/0.31.2/#autolinks) it's clear that they are not a universal panacea and that they still have quite a few limitations themselves. One of the links that I had had was this: [https://en.wikipedia.org/wiki/Wayland_(protocol)](https://en.wikipedia.org/wiki/Wayland_$protocol$) but if we see [https://spec.commonmark.org/0.31.2/#example-603](https://spec.commonmark.org/0.31.2/#example-603) it would have in fact failed if angled brackets were used. ![Image](https://github.com/user-attachments/assets/256a02bd-53a7-4433-a14d-383dceb594f3) Putting a deep link to the specs `#autolinks` section, to one that is always the current version could be tricky (?) but a bit more on autolink limitations might be something to consider. I have used markdown for years on Wikipedia. I didn't know that the spec was so complicated. This issue is probably good to close, I guess.

kerem commented

2026-03-07 20:08:58 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 29, 2025):

OK, thanks, I'll close this.

FYI, your example above can be expressed using angle brackets and it does not need backlash escaping: https://dlaa.me/markdownlint/#%25m%23%20Issue%201616%0A%0A%3Chttps%3A%2F%2Fen.m.wikipedia.org%2Fwiki%2FWayland_(protocol)%3E%0A

@DavidAnson commented on GitHub (May 29, 2025): OK, thanks, I'll close this. FYI, your example above can be expressed using angle brackets and it does not need backlash escaping: https://dlaa.me/markdownlint/#%25m%23%20Issue%201616%0A%0A%3Chttps%3A%2F%2Fen.m.wikipedia.org%2Fwiki%2FWayland_(protocol)%3E%0A

Rows
Columns

[GH-ISSUE #1616] MD034 - Bare URL used > advice gives code that fails npm/docusaurus md to html conversion/build #2567