Anchor links for header with link are broken on pub.dev #1339

Activity

1. lrhn commented on Nov 3, 2023

   

   lrhn

   on Nov 3, 2023

   Last edited by lrhn

   Member

   More actions

   TL;DR: Seems like a bug in the const HeaderWithIdSyntax() extension. It doesn't convert the content to text before creating the ID, so the resulting ID contains text that doesn't appear visibly in the header. And it differs from what GitHub does.

   The source code for the link to the header, in packages/fpdart/README.md, is

     - [Task](#task)

   In CommonMark syntax, that's an external link to #task, which means clicking it work like navigating to <currentUrl>#task.

   GitHub flavored markdown (GFM) makes it work as a link to the internal header with test "task", which it gives a name/id of "task".
   (Or something to that effect, using scripting.)

   The target is

   ### [Task](/packages/fpdart/lib/src/task.dart)

   So, this sounds like a bug in the GFM-web extension of package:markdown, which generates the wrong ID.
   The ID should be based on the ASCII text content of the header, not the source. Links should be removed.
   (Image links are apparently entirely removed, which can cause the link to contain a -- sequence.)

   The generated link of #taskpackagefpdartlibsrctaskdart has taken all the words of the header source, but shouldn't have included the words inside the (...).

   Example of what GFM does:

   # TOC
   
   * Goto [simple header](#a-simple-header)
   * Goto [text header](#a-link-text-header)
   * Goto [text and image header](#a-link-text--header)
   * Goto [silly header](#a-link---with-1--multiple%CC%81-spaces_and-2--int%C3%A9rnal-punctuation-and-3--html--face-header)
   
   ### A simple header
   
   Simple, not?
   
   ### A [Link text](http://example.com) header
   
   Text, not?
   
   ### A [Link text](http://example.com) ![with image](http://example.com/favicon.gif) header
   
   More text?
   
   ###  &#x41; link - __with__ (1)  multiple&#x0301;-**spaces**_and (2)  _int&eacute;rnal_-p/u/nc+tua!tion <sup>*and*</sup><a name="xx"/> ($3)  <span color="red">html 😝 face</span> header   
   
   Silly, yes!

   So, algorithm seems to be, something like, for a header line #+ (.*), extract an ID from the (.*) as:

   • Remove leading and trailing whitespace.
   • Parse as inline markdown, as normal
     • This expands HTML entities.
   • Convert that inline content to plain text by removing all formatting.
     • A matched _italic_ or __bold__ becomes just italic and bold.
     • <sup>foo</sup> or <span color="red">foo</span> becomes just foo.
     • All links removed, leaving only their link text.
     • All image links ![title text](link) removed entirely (leaves no text).
   • Remove all remaining non-Unicode-letter-digit-underscore-or-space characters (no emoji "☃"!)
   • Convert all spaces to - and all letters to lower-case
   • Encode all non-ASCII characters as UTF8, %-escape the bytes.

   That's not a universal rule, it's GitHub specific, but that's what we should assume for the README.md of a pub package, especially if it has a Github repo, but probably in general.
   (For example, Gerrit seems to use a different algorithm, whose description is also silent on internal markdown.
   Some strategies remove accents from letters, GitHub does not.)

   👍React with 👍1Reacted by Sam Rawlins
2. lrhn

   transferred this issue fromdart-lang/sdkon Nov 3, 2023
3. lrhn

   added

   type-bugIncorrect behavior (everything from a crash to more subtle misbehavior)Incorrect behavior (everything from a crash to more subtle misbehavior)

   on Nov 3, 2023
4. lrhn

   assigned

   kevmoo

   and

   jonasfj

   on Nov 5, 2023
5. kevmoo commented on Nov 5, 2023

   

   kevmoo

   on Nov 5, 2023

   Member

   More actions

   @srawlins ?

   👍React with 👍1Reacted by Sam Rawlins
6. kevmoo

   removed their assignment

   on Nov 5, 2023
7. srawlins

   added

   P2A bug or feature request we're likely to work onA bug or feature request we're likely to work on

   on Nov 5, 2023
8. jonasfj

   removed their assignment

   on Nov 27, 2023
9. mosuem

   transferred this issue fromdart-archive/markdownon Dec 11, 2024
10. mosuem

    added

    package:markdown

    on Dec 11, 2024
11. hkarmoush

    added a commit that references this issue on Sep 25, 2026

    [markdown] Generate header anchor ids from inline-parsed text

    ...

    This issue will close once commit d2143b0 is merged into the 'main' branch.

    d2143b0
12. hkarmoush

    added 5 commits that reference this issue on Oct 26, 2026

    [markdown] Generate header anchor ids from inline-parsed text

    ...

    This issue will close once commit 9abccff is merged into the 'main' branch.

    9abccff

    [markdown] Generate header anchor ids from inline-parsed text

    ...

    This issue will close once commit 6a8e35f is merged into the 'main' branch.

    6a8e35f

    [markdown] Generate header anchor ids from inline-parsed text

    ...

    This issue will close once commit 8ce38bf is merged into the 'main' branch.

    8ce38bf

    [markdown] Generate header anchor ids from inline-parsed text

    ...

    This issue will close once commit ed32851 is merged into the 'main' branch.

    ed32851

    [markdown] Generate header anchor ids from inline-parsed text

    ...

    This issue will close once commit dccca02 is merged into the 'main' branch.

    dccca02