Skip to content
  • Directorymy-lib/
    • package.json "workspaces": ["packages/*", "website"]
    • package-lock.json one lockfile for everything
    • Directorypackages/
      • Directorycore/
        • Directorydocs/
          • …
        • Directorysrc/
          • …
        • package.json
      • Directoryreact/
        • Directorydocs/
          • …
    • Directoryexamples/
      • …
    • Directorywebsite/ the site, a workspace member
      • …
website/astro.config.mjs
projectSite({
name: 'My Lib',
tagline: 'Parsing for every framework.',
url: 'https://my-lib.dev',
repo: 'https://github.com/me/my-lib',
versionFrom: '../packages/core/package.json',
externalDocs: [
{ dir: '../packages/core/docs', route: 'core', label: 'Core', order: ['getting-started.md'] },
{ dir: '../packages/react/docs', route: 'react', label: 'React' },
],
mirrors: [
// Examples import the built package from ../packages/core/src, so mirror both under one prefix.
{ from: '../', to: 'x', include: ['examples', 'packages/core/src'], exclude: ['*.test.*'] },
],
}),
  • Each package’s docs/README.md is its group’s overview: /docs/core/, /docs/react/. Groups follow the order of externalDocs.
  • Links between mounts are rewritten too: packages/react/docs/hooks.md can link ../../core/docs/api.md#parse and it becomes /docs/core/api/#parse.
  • A link to ../src/parse.ts from a mounted page goes to the file on GitHub, at repoBranch.
  • Edit links open the right file in the right package.

Add website to the root workspaces, install from the root (npm install), and run the site with npm run dev -w website. In CI, npm ci must run at the root (where the lockfile is) and the build in website/:

.github/workflows/site.yml
jobs:
site:
uses: pavelpascari/astro-project-site/.github/workflows/deploy.yml@v0.1.0-beta.6
with:
working-directory: website
install-directory: .
permissions: { contents: read, pull-requests: write }
secrets:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

wrangler must be a devDependency of website (or the root) so the lockfile pins it; the deploy job will not download one.

One website/docs-gen.config.mjs can fill blocks in every package’s docs:

website/docs-gen.config.mjs
export default {
files: ['../packages/core/docs', '../packages/react/docs', 'src/content/docs'],
generators: { exports: async ({ args, root }) => { /* … read path.resolve(root, args.from) … */ } },
};

Paths in args resolve against root, the folder of the config. See Docs generation.

This site is itself an example: it lives in site/ of a workspace repo, mounts ../starters/default/example/docs and runs a generator over the package in ../packages/astro-project-site.

astro-project-site

A whole site for your open-source project, from one Astro integration.

© 2026 astro-project-site · v0.1.0-beta.6 · MIT licence. This site is built with itself.