papyrus

Back

Deploy Papyrus

Static hosting, build settings, metadata URLs, and base-path notes for a Papyrus site.

Papyrus builds to static Astro output, so a consuming site can publish the generated dist directory to any static host.

Local preview

Use the local development server while editing content, routes, and theme configuration. For a production-shaped preview, build first and serve the generated output.

pnpm install
pnpm dev
pnpm build
pnpm preview
console

For a LAN-safe static preview of the built package demo, use the package Makefile:

make serve
sh

The default LAN preview URL is http://192.168.1.102:4326/.

Docker preview

The Dockerfile is for repeatable local static preview of the package demo. It does not deploy anything.

make docker-build
make docker-run
sh

Open http://localhost:4327/, then stop the container:

make docker-stop
sh

Static hosting

The deployment artifact is the Astro dist directory. Cloudflare Pages, Netlify, Vercel static output, GitHub Pages, and any static file server can host it as long as the configured site URL matches the final domain.

  • Set the production site URL before generating sitemap, robots, RSS, social metadata, and AI indexes.
  • Keep secret token lookup and host-specific deploy wrappers outside the reusable theme package.
  • Check /robots.txt, /sitemap-index.xml, /rss.xml, /search/, /posts/, and /collections/ after publishing.

Build settings

Most static hosts need only the package manager, build command, output directory, and production URL. Keep the URL in one environment variable so generated metadata agrees across sitemap, robots, RSS, social previews, search, and AI files.

package manager: pnpm
build command: SITE_URL="https://example.test" pnpm build
output directory: dist
text

If the consuming site uses pnpm, keep minimumReleaseAge in pnpm-workspace.yaml so production builds do not pick up packages published only minutes ago.

Cloudflare Pages

The package repository pins Wrangler as a dev dependency, so no global Wrangler install is required for the demo deploy target.

One-time setup:

  • create or confirm the Cloudflare Pages project
  • create a token with Cloudflare Pages write access
  • store the token outside this repo

Repeatable deploy command:

CLOUDFLARE_API_TOKEN="$TOKEN" make deploy-demo
sh

The target is repeatable because it updates the same Pages project:

make deploy-demo PAGES_PROJECT=papyrus
sh

Do not put personal token lookup helpers in this package. Consuming machines can wrap the command locally.

Subdirectory deploys

When the site is published under a base path, route links go through Papyrus base-path helpers or Astro route helpers instead of hardcoded root-relative strings. Asset URLs use the same base-aware helper used by the layout. Configure the Astro base option in the consuming site, then keep internal links on helpers such as withBase() or getRelativeLocaleUrl().

After deploy

Open the published URL and confirm the generated routes load. At minimum, check that /robots.txt, /sitemap-index.xml, /rss.xml, /search/, /posts/, and /collections/docs/ match the configured site URL.