Skip to content
  1. Create the site. init copies the starter (a complete site that builds) into a new folder and names it after the folder, or after --name:

    Terminal window
    npx astro-project-site@beta init my-lib-site --name "My Lib"
    Created "My Lib" in /home/you/my-lib-site (29 files).
    Next:
    cd my-lib-site
    npm install
    npm run dev # http://localhost:4321

    It never overwrites an existing file unless you pass --force.

  2. Run it.

    Terminal window
    cd my-lib-site
    npm install
    npm run dev

    Open http://localhost:4321: a landing page, /docs/, /gallery/, and /apps/hello/ (a static app served by a mirror).

  3. Make it yours. Everything about the site is one call in astro.config.mjs:

    astro.config.mjs
    // @ts-check
    import { defineConfig } from 'astro/config';
    import projectSite from 'astro-project-site';
    export default defineConfig({
    integrations: [
    projectSite({
    name: 'My Lib',
    tagline: 'Parses things, quickly.',
    url: 'https://my-lib.dev',
    repo: 'https://github.com/me/my-lib',
    install: 'npm i my-lib',
    externalDocs: [{ dir: './example/docs', route: 'reference', label: 'Reference' }],
    mirrors: [{ from: './example/apps', to: 'apps' }],
    }),
    ],
    });

    A typo fails with the field’s name before Astro starts (unknown option "taglin"). The dev server restarts by itself when the config changes. All options: Options.

  4. Write a docs page. Add src/content/docs/docs/usage.md:

    src/content/docs/docs/usage.md
    ---
    title: Usage
    description: How to call it.
    sidebar:
    order: 1
    ---
    Call `parse()` with a string.

    It is served at /docs/usage/. Restart the dev server after adding or removing a page: the sidebar is built at startup. Edits to existing pages reload live.

  5. Build.

    Terminal window
    npm run build

    This runs astro check, astro build (which fails on a broken link in any docs page) and project-site docs:check. The result is static files in dist/. npm run preview serves them.

Path What it is
astro.config.mjs The site: projectSite({ … })
src/content.config.ts projectSiteCollections(): docs, gallery and i18n collections
src/content/docs/docs/ Your docs pages (.md / .mdx), under /docs/
src/content/gallery/ One YAML/JSON/MD file per gallery item
example/docs/, example/apps/ Stand-ins for your project’s markdown docs and static apps. Point externalDocs and mirrors at the real ones, then delete example/
docs-gen.config.mjs Generated blocks in markdown
wrangler.jsonc, public/_headers Cloudflare Workers deploy
.github/workflows/site.yml Only with init --ci: checks, a preview per PR, production on v* tags (Deploying)

package.json scripts: dev, build, preview, check, docs:gen, docs:check, deploy (build + wrangler deploy), deploy:preview, cf:dev (the built site on Cloudflare’s local runtime).

Next: most libraries already have a repo with a docs/ folder. Add the site to it.

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.