Build Pages

@zeropress/build-pages builds a static ZeroPress site from a Markdown source directory.

Use it when your repository looks like a documentation site: Markdown pages, public files, optional config, and a deployable static output directory.

GitHub Action

- name: Build ZeroPress Pages
  uses: zeropress-app/zeropress-build-pages@v0
  with:
    source: ./docs
    destination: ./_site

The action builds static files only. Uploading or deploying _site remains the job of GitHub Pages, Cloudflare Pages, Netlify, Vercel, or another host.

CLI

Use npx for one-off local builds:

npx @zeropress/build-pages --source ./docs --destination ./_site

Use a package script when the project already has a Node.js toolchain:

{
  "scripts": {
    "build": "zeropress-build-pages --source ./docs --destination ./_site"
  },
  "devDependencies": {
    "@zeropress/build-pages": "0.6.1"
  }
}

Source Directory

The source directory is both the Markdown discovery root and public passthrough root.

my-site/
  docs/
    index.md
    guide.md
    assets/
      logo.png
    .zeropress/
      config.json
  _site/

Repository root source is not supported. Use a dedicated folder such as docs/ or documents/.

Config

Build Pages reads optional config from:

<source>/.zeropress/config.json

Minimal config:

{
  "$schema": "https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json",
  "version": "0.1",
  "site": {
    "title": "My Docs",
    "description": "Project documentation",
    "url": "https://example.com"
  },
  "front_page": {
    "type": "markdown"
  }
}

See Build Pages Config for the full guide and Build Pages Config Reference for the schema-oriented view.

Public Files

Files in the source directory are staged as public files unless ignored. Generated ZeroPress output wins over copied public files.

Common public files:

• favicon.ico
• favicon.svg
• favicon.png
• apple-touch-icon.png
• robots.txt
• sitemap.xsl
• images, PDFs, JS, CSS, JSON, and original Markdown files

Use copy-markdown-source: false in the GitHub Action or --no-copy-markdown-source in the CLI when original Markdown should not be copied to output.

Themes

Build Pages uses the bundled docs theme by default.

Use a custom theme with theme-path:

with:
  source: ./docs
  destination: ./_site
  theme-path: ./my-docs-theme/theme

Create a starter theme with:

npx @zeropress/create-theme --name my-docs-theme --template docs

Diagnostics

Build Pages writes working files to .zeropress/ in the current working directory:

• build-pages-config.json
• preview-data.json
• build-report.json
• public-assets/

These are diagnostics and intermediate build inputs, not the final deploy output.