Skip to content
QGIS SDK

Documentation site

archont561.github.io/qgis-sdk is apps/docs, an Astro Starlight site. Its reference pages are generated from apps/docs/guides/, never edited directly, and the site cites what ships (releases, registries, versions), never how the work was tracked:

  • apps/docs/scripts/generate.ts renders doc-12, doc-13 and this guide into src/content/docs/{python,typescript,contributing/workspace}/ - one page per ## section, the preamble as the directory’s index, sub-headings moved up one level, the migration notes filed under <guide>/migration/ newest first; this guide is contributor material and sits outside the consumer reference. Same-guide and cross-guide anchors become site routes; a link to a decision record lands on its row of the design-decisions page, which the same script renders from backlog/decisions/ and the one-line summaries in scripts/decision-summaries.ts; a link to a task, a milestone, a plan or the agent rules is dropped (its text stays) and reported, so those records never surface on the site. Each page’s “Edit page” opens its source in apps/docs/guides/, and its lastUpdated is the guide’s last commit. A section whose heading says (in progress) or (unreleased) is published with a Draft badge and opens with a caution, so notes on a line still being cut never read as finished guidance. The generated directories are ignored by git. A link whose anchor no guide has is reported by the generator and fails the link check.
  • The same script copies packages/qgis-sdk-ui/storybook-static to public/storybook/ when it exists, so the site serves the Storybook at /storybook/; docs-build builds it first.
  • src/content/docs/start/ (installation, first plugin, concepts) and the landing page are the hand-written part, kept short and pointing into the generated pages. site.ts holds the URL, base and repository; the versions on the landing page are read from the workspace manifests when the Astro config loads.
  • After Astro builds, scripts/redirects.ts writes static compatibility pages for the former workspace and migration URLs from scripts/lib/redirects.ts. They preserve query strings and fragments when JavaScript is available and offer a refresh and a link without it. They are outside Starlight content, the sitemap and the llms pages. The build checks destination pages, sitemap and Markdown twins and refuses collisions; add an explicit mapping when moving a public page.
  • scripts/check-links.ts walks dist/ and resolves every internal href, src and fragment against the built files, with no network. bun test in apps/docs covers the renderer and the checker; bun run coverage holds them to the workspace’s 90%.
  • starlight-llms-markdown emits /llms.txt, /llms-full.txt and a .md twin of every page; site and base give Starlight’s bundled sitemap and canonical URLs; public/robots.txt names the sitemap.
  • .github/workflows/docs.yml builds and link-checks the site on pull requests that touch it, the guides or the UI package, and deploys it from main with actions/deploy-pages. Astro runs under Bun (bun --bun astro) so the build needs no Node beyond the Pixi bun environment; Starlight’s <Tabs> component is avoided because it parses its own output through a native binding Bun’s isolated node_modules cannot resolve from a chunk.