Maintain the documentation website

The website lives in website/ and uses Astro Starlight. Source pages are Markdown/MDX in src/content/docs/. Starlight supplies navigation, page outlines, code copying, theme switching and a local Pagefind search index. No application server or external search account is required.

Local workflow

Use Node.js 22.12 or newer (CI uses Node 24) and the committed npm lockfile:

cd website
npm ci
npm run dev

Open the URL printed by Astro. Build and validate before publishing:

npm run check
npm run build
npm run test:examples

The build checks local rendered links, anchors and assets. Example validation runs marked GQL snippets against a fresh in-memory CLI session and checks parser-only examples with the parser crate. Graph examples share the documented quickstart fixture; standalone examples create their own setup.

Writing a page

Give each user-visible feature a descriptive title, short description, a realistic example and an explicit execution boundary. Use gql test fences for executable examples, gql test=standalone for programs that create their own graph, and gql parse for grammar-only examples. These fence annotations are validation metadata, not user-facing language syntax.

Internal URLs start with / and resolve from the site root. Every reference page should be reachable from the sidebar and search. Preserve links from former docs/*.md entry points when moving content.

Framework and hosting choice

DuckDB’s website build guide uses Jekyll and documents GitHub Pages-style static hosting. Arrow’s developer documentation uses Sphinx and Doxygen; its separate main website publishes an asf-site branch through ASF infrastructure.

Both separate concise project entry points from navigable reference documentation. GraphFusion follows that organization with Starlight: Markdown authoring and integrated navigation/search suit the current Rust repository without introducing a Python API-documentation or custom Jekyll theme stack. Rust API docs remain generated by cargo doc.

The production site at https://graphfusion.github.io/ is published by GraphFusion/graphfusion.github.io. Its GitHub Pages workflow reads the documentation source from this repository, checks main for website changes daily at 09:00 Asia/Shanghai (01:00 UTC), and supports manual publication. Scheduled runs skip rebuilding an unchanged site. No cross-repository credentials are needed.

The workflow in this repository checks the documentation and publishes redirects at the former /GraphFusion/ address. Redirects preserve page paths, query strings and fragments. Documentation source and review stay here; the publishing repository contains only its deployment workflow.