Most projects already have a repository with code and a docs/ folder written for GitHub. The site goes in a
folder next to them and reads those files where they are; nothing moves.
Directorymy-lib/
Directory.github/workflows/
- site.yml optional CI (init --ci), calls the reusable workflow
Directorydocs/ your markdown, unchanged
- README.md
- api.md
Directoryguides/
- …
Directorysrc/ your library
- …
Directorydemos/ plain HTML/JS demos
- playground/index.html
- package.json your library’s
Directorywebsite/ the site
- astro.config.mjs
- package.json
- package-lock.json
- src/content/docs/docs/index.mdx
- wrangler.jsonc
-
Create the site in
website/.Terminal window cd my-libnpx astro-project-site@beta init website --name "My Lib"cd website && npm install -
Mount
../docsand serve../demos. Inwebsite/astro.config.mjsreplace theexample/paths:website/astro.config.mjs projectSite({name: 'My Lib',tagline: 'Parses things, quickly.',url: 'https://my-lib.dev',repo: 'https://github.com/me/my-lib',versionFrom: '../package.json', // the header shows your library's versionexternalDocs: [{ dir: '../docs', route: 'reference', label: 'Reference', order: ['getting-started.md', 'api.md'], exclude: ['plans/**'] },],mirrors: [// /lib/src/… and /lib/demos/… keep their relative layout, so a demo's `import '../src/x.js'` works.{ from: '../', to: 'lib', include: ['src', 'demos'], exclude: ['*.test.js'] },],nav: [{ label: 'Docs', href: '/docs/' },{ label: 'Playground', href: '/lib/demos/playground/' },],}),../docs/README.mdbecomes/docs/reference/,../docs/api.mdbecomes/docs/reference/api/. Relative.mdlinks between them are rewritten; a link to../src/parse.jsgoes to the file on GitHub.- “Edit this page” on those pages opens
docs/api.mdin your repo, and on local pageswebsite/src/content/docs/…: the integration finds the git root and works out the folder. - The mirror never copies the
website/folder into itself, nor dotfiles ornode_modules.
Then remove the starter’s stand-ins: delete
website/example/, drop'example/docs'fromfilesinwebsite/docs-gen.config.mjs, and rewritesrc/content/docs/docs/index.mdxandsrc/content/gallery/hello.yaml, which link to/apps/…(the links validator reports the links; the live examples on that page would load nothing). -
Optional: CI. Without it, deploy from your machine with
npm run deploy(Deploying). If you created the site with--ci, move the workflow to the repo root; GitHub only reads workflows from the root.github/:Terminal window mkdir -p .github/workflows && git mv website/.github/workflows/site.yml .github/workflows/site.ymland tell the reusable workflow where the site is:
.github/workflows/site.yml on: [pull_request, push, workflow_dispatch]jobs:site:uses: pavelpascari/astro-project-site/.github/workflows/deploy.yml@v0.1.0-beta.6with: { working-directory: website }permissions: { contents: read, pull-requests: write }secrets:CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}If the site is an npm workspace member of the root
package.jsoninstead (one lockfile at the root), addinstall-directory: .. -
Build it.
npm run buildinwebsite/. The build log lists the mirror (/lib/ ← ../: N files, …). The links validator now checks every link in yourdocs/folder; fix what it reports (see Troubleshooting).
Next: deploying (one-time Cloudflare setup), and if the site must live in its own repository instead, Separate site repo.