Skip to content

fix: resolve internal links by target instead of link text - #76

Merged
kdheepak merged 1 commit into
kdheepak:mainfrom
geodimm:fix/internal-link-targets
Sep 12, 2026
Merged

kdheepak merged 1 commit into
kdheepak:mainfrom
geodimm:fix/internal-link-targets

Conversation

@geodimm

@geodimm geodimm commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor

Writer.Inline.Link built the help reference for a [text](#anchor) link by slugifying the link's text, ignoring the target entirely. A link only resolved when its text happened to spell the target heading, so any other wording produced a |reference| matching no tag, and :help on it failed with E149.

The failure was silent: pandoc exited 0, :helptags exited 0, and the README rendered correctly on GitHub.

Writer.Pandoc now walks the document before rendering and maps each heading's identifier to the tag that heading will emit, including the parent prefix added under --dedup-subheadings. Links resolve against that map, so the reference follows the target.

Link text that adds something is kept ahead of the tag, matching how external links already render as text <target>:

See [Options](#options) and [the options below](#options).

See |project-options| and the options below |project-options|.

Text that merely repeats the heading is dropped, since the tag already spells it out, and the comparison ignores case and markup so Options is treated as a repeat.

Headings below level 2 are rendered without a tag, so links to them cannot resolve. Those now render as plain text with a warning on stderr rather than emitting a reference that cannot be followed.

Verified against two published plugin READMEs: output is byte-identical for one whose link text already matched its headings, and the other's eleven dangling references drop to zero.

Fixes #75

`Writer.Inline.Link` built the help reference for a `[text](#anchor)` link
by slugifying the link's text, ignoring the target entirely. A link only
resolved when its text happened to spell the target heading, so any other
wording produced a `|reference|` matching no tag, and `:help` on it failed
with E149.

The failure was silent: pandoc exited 0, `:helptags` exited 0, and the
README rendered correctly on GitHub.

`Writer.Pandoc` now walks the document before rendering and maps each
heading's identifier to the tag that heading will emit, including the
parent prefix added under `--dedup-subheadings`. Links resolve against
that map, so the reference follows the target.

Link text that adds something is kept ahead of the tag, matching how
external links already render as `text <target>`:

    See [Options](#options) and [the options below](#options).

    See |project-options| and the options below |project-options|.

Text that merely repeats the heading is dropped, since the tag already
spells it out, and the comparison ignores case and markup so
[`Options`](#options) is treated as a repeat.

Headings below level 2 are rendered without a tag, so links to them cannot
resolve. Those now render as plain text with a warning on stderr rather
than emitting a reference that cannot be followed.

Verified against two published plugin READMEs: output is byte-identical
for one whose link text already matched its headings, and the other's
eleven dangling references drop to zero.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@kdheepak
kdheepak merged commit 8cf007e into kdheepak:main Sep 12, 2026
3 checks passed
@kdheepak

Copy link
Copy Markdown
Owner

Thanks for the PR with tests!

@geodimm

geodimm commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor Author

Thank you for the quick turnaround. Are there any plans to create a new tag and/or release or should I switch to main? I am asking because I'd like to use the Nix package but it's quite old: https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/pa/panvimdoc/package.nix

@geodimm
geodimm deleted the fix/internal-link-targets branch September 12, 2026 23:19
@kdheepak

Copy link
Copy Markdown
Owner

Thanks for the ping, I made a new release! https://github.com/kdheepak/panvimdoc/releases/tag/v5.0.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Internal links use the link text instead of the target, producing dangling help references

2 participants