Skip to content

📖✨:hand markdown-it the anchor and footnote plugins - #1792

Open
DerekNonGeneric wants to merge 1 commit into
livefrom
feat/wire-up-markdown-plugins
Open

📖✨:hand markdown-it the anchor and footnote plugins#1792
DerekNonGeneric wants to merge 1 commit into
livefrom
feat/wire-up-markdown-plugins

Conversation

@DerekNonGeneric

Copy link
Copy Markdown
Member

markdown-it-anchor and markdown-it-footnote have both sat in devDependencies without ever reaching the markdown library — eleventy.config.mjs never touched it. So the syntax they exist to support has been rendered by whatever markdown-it does in their absence.

Footnotes were not merely absent, they were wrong

[^2] with a matching [^2]: definition is also perfectly good link reference syntax, so markdown-it happily rendered it as one. The published security page currently emits:

automated dependency management.<a href="https://www.mend.io/…">^2</a>

— the marker printed into the sentence as link text, rather than a superscript pointing at a footnotes section. After:

automated dependency management.<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup><hr class="footnotes-sep"><section class="footnotes"><ol class="footnotes-list">

Headings had no ids

Which leaves any in-page link with nothing to find. Nothing published depends on one yet — but agent-forwarding.md links to #when-show-signature-says-no-signature twice and sets toc: true, so it would have shipped broken. It is draft: true, so this is latent rather than live. Verified the target now resolves in a drafts build.

Verification

  • headings now carry ids (<h2 id="issue-tracker">, <h3 id="resolving-open-issues">, …)
  • all ids are unique across all 27 pages — checked, since duplicates would be both a validity error and a navigation bug
  • the W3C validator stays clean across all 27 pages, which matters because 🏗️🔧:validate every built page, not just the home page #1786 widened it to the whole site and this adds new markup
  • nps build, nps test, nps format.all all pass

Deliberately not included

You asked me to look at what else could be wired up rather than deleted. Two findings, neither belonging in this PR:

The retext prose-linting pipeline has never run. Not the two unused plugins — the whole thing. remark-lint rules fire correctly, but nothing in naturalLanguage does: retext-repeated-words does not flag has has, retext-simplify does not flag utilize. The plugins are passed as module namespace objects rather than functions, so the bridge never attaches — silently, with no error. Forcing it surfaces the real failure:

TypeError: attacher.call is not a function
    at apply.remarkRetext (…/remark-retext/lib/index.js:88:35)

Unwrapping .default across the pipeline makes it work — and then reports 3,215 messages on existing content:

rule messages
retext-spell 3034
retext-readability 78
retext-simplify 46
retext-repeated-words 22
retext-equality 22
retext-profanities 5
retext-passive 3

That is its own project, and worth deciding on first: retext-spell accounts for 94% of it while duplicating cspell, which already runs and passes. Likely it should go and the rest be turned on.

The remaining unwired packages are genuinely inert here, so no deletions in this PR: remark-github, remark-html, remark-heading-id, remark-hint, and remark-directive all transform or render markdown, but remark is only ever run as a linter (remark -f) whose output is discarded — wiring them would change nothing visible. remark-lint-code-block-style and remark-lint-definition-spacing are already applied via remark-preset-lint-markdown-style-guide@^4.0.0, so declaring them directly is redundant rather than useful. markdown-it-abbr, -sub, -sup, and -task-lists have no content using their syntax (the docs write <abbr> by hand).

Part of #254.

List of any relevant issue numbers: #254

Both have sat in dependencies without ever reaching the markdown
library — eleventy.config.mjs never touched it — so the syntax they
exist to support has been rendered by whatever markdown-it does in
their absence.

For footnotes that is not nothing, it is wrong. A reference like
`[^2]` with a matching `[^2]:` definition is perfectly good link
reference syntax, so the security page has been rendering

  automated dependency management.<a href="https://www.mend.io/…">^2</a>

printing the marker into the sentence as link text instead of a
superscript pointing at a footnotes section.

Headings had no ids at all, which leaves in-page links with nothing to
find. Nothing published relies on one yet, but the agent forwarding
draft links to `#when-show-signature-says-no-signature` twice and asks
for `toc: true`, so it would have shipped broken.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@netlify

netlify Bot commented Aug 10, 2026

Copy link
Copy Markdown

Deploy Preview for gh-pages-openinf ready!

Name Link
🔨 Latest commit 00a007e
🔍 Latest deploy log https://app.netlify.com/projects/gh-pages-openinf/deploys/6a7964aed649ba0008f39acf
😎 Deploy Preview https://deploy-preview-1792--gh-pages-openinf.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

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.

1 participant