Skip to content

Sometimes the site cannot live in the library’s repo (different maintainers, a repo you do not control). There are two ways to read the library from the site’s repo.

When the site needs only the library’s markdown, let the build download it:

my-lib-site/astro.config.mjs
projectSite({
name: 'My Lib',
tagline: 'Parses things, quickly.',
url: 'https://my-lib.dev',
repo: 'https://github.com/me/my-lib-site',
externalDocs: [
{ git: { repo: 'https://github.com/me/my-lib', ref: 'v2.1.0', path: 'docs' }, route: 'reference', label: 'Reference' },
],
}),

No second clone, locally or in CI. Links from those docs to the library’s source files go to the library’s repo at v2.1.0, and “Edit page” to its default branch. Bump ref when the library releases. See Mount another repository for branches, caching and private repos (in CI, a private library is read with a second checkout, below).

mirrors (static demos, apps) need the files on disk. Keep two clones side by side and point the site at the other one:

~/code/
my-lib/ the library (docs/, src/, demos/)
my-lib-site/ the site
my-lib-site/astro.config.mjs
projectSite({
name: 'My Lib',
tagline: 'Parses things, quickly.',
url: 'https://my-lib.dev',
repo: 'https://github.com/me/my-lib-site',
externalDocs: [{ dir: '../my-lib/docs', route: 'reference', label: 'Reference' }],
mirrors: [{ from: '../my-lib', to: 'lib', include: ['src', 'demos'] }],
}),

The reusable workflow checks this repo out into a folder named after it and, with source-repo, the other one beside it under its name, which is the same layout as on your machine:

my-lib-site/.github/workflows/site.yml
jobs:
site:
uses: pavelpascari/astro-project-site/.github/workflows/deploy.yml@v0.1.0-beta.6
with:
source-repo: me/my-lib # → ../my-lib
source-ref: main # branch, tag or SHA
permissions: { contents: read, pull-requests: write }
secrets:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
# SOURCE_REPO_TOKEN: ${{ secrets.SOURCE_REPO_TOKEN }} # only for a private source repo: a read-only token

To rebuild the site when the library changes, trigger this workflow from the library’s repo (for example workflow_dispatch via the GitHub API) or on a schedule.

Edit links and GitHub links are computed from the git repository the site is in. For a dir mount outside it:

  • its pages get no “edit this page” link;
  • relative links to non-markdown files (../src/parse.js) are left as written. The links validator reports them as relative links and fails the build.

Mount the docs with a git source instead (and keep the checkout for mirrors): its links and edit links point at the library’s repo. Links between the mounted .md files are rewritten either way.

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.