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.
Docs only: a git source
Section titled “Docs only: a git source”When the site needs only the library’s markdown, let the build download it:
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).
Docs and demos: a second checkout
Section titled “Docs and demos: a second checkout”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 siteprojectSite({ 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'] }],}),In CI: source-repo
Section titled “In CI: source-repo”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:
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 tokenTo 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.
Limits of a second checkout
Section titled “Limits of a second checkout”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.