Conversation
Rendered Markdown headings had no id attributes, so in-document links like [Install](#install) and README tables of contents went nowhere. Register marked-gfm-heading-id on the README pipeline to emit GitHub-compatible slugs, and add scroll-mt so scrolled-to headings clear the sticky header. Markdown pipelines now build their Marked instance via a createMarked() factory instead of mutating the global singleton: READMEs get heading ids while docs keep highlight-only rendering, deterministically rather than depending on module load order. Also rename the install widget's id to install-command so a "## Install" README heading cannot shadow it. Closes zig-toolbelt#3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #3 — rendered READMEs now emit GitHub-compatible heading
idslugs (viamarked-gfm-heading-id), so in-document Markdown links like[Install](#install)and README tables of contents update the URL hash and scroll to the target section. SvelteKit's router already scrolls to elements matching a#hashon internal navigation, and SSR output makes deep links work on initial load — no client-side JS was needed.marked-gfm-heading-id@^4.1.4(peer rangemarked >=13 <19, we usemarked@18) produces identical slugs to GitHub, includingfoo/foo-1dedup, and resets its slugger per document via apreprocesshook.prose-headings:scroll-mt-20keeps scrolled-to headings clear of the stickyh-14header.rewriteRelativeUrlsexempts#links andDOMPurifyconfig allowsid.Refactoring along the way
marked.use(markedHighlight(...))side effect with acreateMarked()factory (src/lib/server/marked.ts). READMEs usecreateMarked(gfmHeadingId()); docs usecreateMarked(). Docs highlighting previously depended on module evaluation order — now deterministic. Globalmarkedis no longer mutated anywhere (guarded by a regression test).rewriteRelativeUrls+README_SANITIZE_OPTIONSinto DB-freereadme-html.tsso the pipeline is unit-testable without the DB import graph.id="install"→id="install-command"so a## InstallREADME heading can't be shadowed by it (no references to#installexisted).Known limitations (documented in tests)
SANITIZE_DOMstrips DOM-clobbering ids — a## Constructorheading loses itsid. GitHub solves this with auser-content-prefix, which would require rewriting#hrefs too; out of scope here.package_content.readmeHTML keeps old markup until refetch (TTL, default 24h). To roll out immediately:UPDATE package_content SET last_sync = NULL;— next view serves stale content once, then refreshes in the background.package-lock.jsonalso normalized stalepeer: trueflags and synced the lockfile version to1.1.0(npm side effect, harmless).Test plan
npm run check— 0 errors / 0 warningsnpx vitest run --project server— 47/47 pass (10 new tests: slug generation, dedup, punctuation/non-ASCII, per-doc reset,#href survival through sanitize+rewrite, code-highlight coexistence, global-instance purity)npm run build— succeeds#…, page scrolls below header); load/packages/{owner}/{repo}#…directly → auto-scrolls