Repository navigation
docs: move the docs site from MkDocs Material to Astro Starlight - #362
Merged
Merged
Conversation
Pages move from docs/docs/ to docs/src/content/docs/ and images from docs/docs/resources/ to docs/public/resources/, unchanged. The repo README points at the new image paths because Obsidian's plugin browser renders it.
Each page gets title and slug frontmatter. Leading H1s move into title. Relative .md links and resources/ image paths become site-absolute, and em-dashes become plain dashes. No other content changes.
docs/ becomes a standalone npm package (own package-lock.json) that builds with Astro Starlight into docs/dist. Every URL the MkDocs site served stays the same, and /sitemap.xml redirects to /sitemap-index.xml. - A build-time check fails when a page has no slug: frontmatter, so URLs such as /QuickAdd/ cannot silently change case. - starlight-links-validator fails the build on a broken internal link or anchor. - starlight-llms-txt writes llms.txt files, and every page is also served as raw markdown at <page-url>.md. - docs:build installs and builds the docs package; wrangler.jsonc and docs:deploy publish docs/dist.
The Documentation workflow sets up Node from .nvmrc with the docs lockfile as the npm cache key, and also runs when package.json or .nvmrc change. Dependabot tracks the docs npm package instead of pip. The release workflow no longer installs Python or the deleted requirements file.
The schema rejects a page without slug: at load time, in builds and in astro dev, so the custom config-time file scan goes. Also drops the twitter:card entry Starlight already emits, types the raw-markdown endpoint props, and removes a .gitignore line the root node_modules rule covers.
# Conflicts: # package.json
Deploying podnotes with
|
| Latest commit: |
6bcf749
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://7625be88.podnotes.pages.dev |
| Branch Preview URL: | https://docs-starlight.podnotes.pages.dev |
# Conflicts: # .github/dependabot.yml # .github/workflows/documentation.yml
starlight-llms-txt pulls braces through micromatch, and every braces release is affected by GHSA-vfj7-8cjw-p6xm (high, no patch), which fails the required Dependency Review check. Two small endpoints now write /llms.txt (every page in sidebar order, linked as raw markdown) and /llms-full.txt from the same page markdown as /<page>.md. The sidebar moves to src/site.mjs so the config and the endpoints share one page order.
…rser Starlight's code highlighter (@expressive-code/core) pins postcss-nested 6, whose postcss-selector-parser 6.1.4 is affected by GHSA-rj75-hqrm-r3gf (moderate; fixed in 7.1.6). postcss-nested 7 only drops Node 12-16 and depends on the 7.x parser. The built site is byte-identical with and without the override, and npm audit in docs/ reports no vulnerabilities. Drop the override once expressive-code moves to postcss-nested 7.
llms.txt and llms-full.txt list pages from the sidebar, so a page left out of it would silently drop out of both while still serving its raw .md. The site title also moves into src/site.mjs next to the description and sidebar.
Starlight drops a hyphen differently from MkDocs on two headings, and moving four H1s into frontmatter removed their ids, so six old section links landed at the page top. Empty <div id> anchors restore them, and the raw markdown endpoints strip the anchors. scripts/legacy-fragments.mjs checks every heading id from master's MkDocs build (legacy-fragments.json, 73 ids) against each new build and fails the docs build when one has no target.
# Conflicts: # package.json
Empty <div id> anchors at the top of a page became its first block, so the first paragraph took Starlight's 16px block gap and the page shifted down. Old page-title ids now come from a legacyTitleId frontmatter field that a PageTitle override wraps around the title, and old section ids are empty spans inside their headings. Both land exactly where the new ids do and add no space.
# Conflicts: # AGENTS.md # package.json
The Pages project builds with docs/ as its root directory, so it never read the repo-root wrangler.jsonc, and npm run docs:build resolved to docs/package.json. wrangler.jsonc moves into docs/ with dist as the output directory, and docs/package.json aliases docs:build to build, so the current dashboard command builds the Starlight site.
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
1 participant
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.
Why
MkDocs Material reaches end of life on 2026-11-05. This PR moves podnotes.obsidian.guide to Astro Starlight and keeps the pages' content and URLs the same. The layout follows QuickAdd's Starlight docs.
What changed
docs/is now a standalone npm package (Astro 7, Starlight 0.42) with its own lockfile. Pages live indocs/src/content/docs/, and images indocs/public/resources/keep their old/resources/*URLs.llms.txt, raw markdown at<page>.md, and OG tags.starlight-links-validatorfails the build on a broken internal link or anchor, and the content schema fails it when a page lacksslug:..nvmrc.llms.txtandllms-full.txtinstead ofstarlight-llms-txt, whosebracesdependency has an unpatched high advisory that fails Dependency Review. An npm override moves Starlight'spostcss-nestedto 7 for the patched selector parser (GHSA-rj75-hqrm-r3gf). The built site is byte-identical with and without the override.Scope
/or&, and four H1s that moved into frontmatter), so empty spans inside the two headings and alegacyTitleIdfrontmatter field (rendered by aPageTitleoverride) keep them. Old links land exactly where the new ids do, and the aliases add no space.docs/scripts/legacy-fragments.mjschecks all 73 ids from master's MkDocs build after every docs build.Blast Radius
Cloudflare Pages builds this repo with
docs/as its root directory. Its build command is nowpip install -r docs/requirements.txt; npm run docs:build: pip fails harmlessly oncedocs/requirements.txtis gone, andnpm run docs:buildresolves todocs/package.json, where it aliasesbuild.docs/wrangler.jsoncsets the output todist. The PR preview deploy is green. After merge, the dashboard command can drop tonpm run docs:buildornpm run build.The release workflow changes only by dropping its Python inputs, because
docs/requirements.txtno longer exists. The root README's image paths follow the moved files, and its docs links now point at podnotes.obsidian.guide instead of a stale GitHub Pages copy.Verification
npm run lint,format:check,typecheck,build,test(1153 tests) anddocs:buildpass on Node 22.23.2.docs:buildfails on a broken link or anchor, a page withoutslug:, a page missing from the sidebar, and a removed legacy anchor (each tested)./import_export/#settings-templatesand/commands/#capture-last-10-seconds-capture-last-20-secondsscroll to their sections, and the aliases add no layout shift (0px, measured on all six pages at desktop and phone width).