-
Create the site.
initcopies 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-sitenpm installnpm run dev # http://localhost:4321It never overwrites an existing file unless you pass
--force. -
Run it.
Terminal window cd my-lib-sitenpm installnpm run devOpen
http://localhost:4321: a landing page,/docs/,/gallery/, and/apps/hello/(a static app served by a mirror). -
Make it yours. Everything about the site is one call in
astro.config.mjs:astro.config.mjs // @ts-checkimport { 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. -
Write a docs page. Add
src/content/docs/docs/usage.md:src/content/docs/docs/usage.md ---title: Usagedescription: 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. -
Build.
Terminal window npm run buildThis runs
astro check,astro build(which fails on a broken link in any docs page) andproject-site docs:check. The result is static files indist/.npm run previewserves them.
What you got
Section titled “What you got”| 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.