# 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

```yaml
- 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:

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

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

```json
{
  "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.

```txt
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:

```txt
<source>/.zeropress/config.json
```

Minimal config:

```json
{
  "$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](/build-pages-config/) for the full guide and [Build Pages Config Reference](/reference/build-pages-config/) 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`:

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

Create a starter theme with:

```bash
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.