ZeroPress Build Pages Config

ZeroPress Build Pages config is the site-local configuration format used by @zeropress/build-pages GitHub Pages style Markdown workflows.

It is not the same thing as preview-data or a theme manifest. The config file is read before @zeropress/build runs, then converted into preview-data v0.5.

This page is a public mirror for the active schema and the options used by this docs site. The @zeropress/build-pages package README and schemas are the canonical source of truth for CLI and GitHub Action behavior.

File Location

Place the config file inside the configured public root:

my-site/
  documents/
    .zeropress/
      config.json
      head-end.html
      body-end.html
    index.md
    docs/
      index.md

For @zeropress/build-pages, the source root is controlled by the GitHub Action source input, CLI --source, or ZEROPRESS_PUBLIC_DIR. The GitHub Action defaults to ./docs; CLI usage requires an explicit --source or ZEROPRESS_PUBLIC_DIR.

zeropress.dev uses:

ZEROPRESS_PUBLIC_DIR=documents

The .zeropress/ directory is for Build Pages-only source files. It is not copied to the final output as public passthrough content.

Schema

Use the versioned schema while editing config:

{
  "$schema": "../schemas/zeropress-build-pages.config.v0.1.schema.json",
  "version": "0.1"
}

Schema URLs:

The version string belongs to the build-pages config format. It does not change the internal preview-data version emitted by Build Pages.

Minimal Config

{
  "$schema": "../schemas/zeropress-build-pages.config.v0.1.schema.json",
  "version": "0.1",
  "site": {
    "title": "My Docs",
    "description": "Documentation for my project.",
    "url": "https://example.com",
    "footer": {
      "copyright_text": "Copyright 2026 Example Corp.",
      "attribution": {
        "enabled": true
      }
    }
  },
  "front_page": {
    "type": "markdown"
  }
}

With this config, Build Pages reads index.md, emits it as the front page, and disables the post index because this workflow is Markdown-docs oriented.

Site Metadata

site provides user-facing site metadata:

{
  "site": {
    "title": "My Docs",
    "description": "Documentation for my project.",
    "url": "https://example.com"
  }
}

Common fields:

title
description
url
footer

Renderer-only preview-data fields such as locale, date/time formats, permalink policy, comments policy, and posts-per-page are not accepted in Build Pages config. Build Pages supplies those internal defaults while generating preview-data.

site.footer provides theme-facing footer text and attribution display policy:

{
  "site": {
    "footer": {
      "copyright_text": "Copyright 2026 Example Corp.",
      "attribution": {
        "enabled": false
      }
    }
  }
}

The bundled docs theme renders copyright_text when present. If it is omitted, the theme falls back to site.title. ZeroPress does not add a copyright symbol automatically.

The bundled docs theme shows Published with ZeroPress. by default. Set site.footer.attribution.enabled to false to hide it.

The generated preview-data always sets:

{
  "post_index": {
    "enabled": false
  }
}

That keeps the workflow focused on Markdown pages rather than blog post lists.

Front Page

front_page decides what owns /.

{
  "front_page": {
    "type": "theme_index"
  }
}

theme_index uses theme/index.html.

{
  "front_page": {
    "type": "markdown"
  }
}

markdown uses index.md by default. You may override the file:

{
  "front_page": {
    "type": "markdown",
    "file": "home.md"
  }
}

{
  "front_page": {
    "type": "html"
  }
}

html uses .zeropress/index.html by default. HTML front page files must stay inside .zeropress/.

By default, HTML front page content is rendered through the ZeroPress page layout:

{
  "front_page": {
    "type": "html",
    "file": ".zeropress/campaign.html",
    "layout": true
  }
}

For a full standalone document, disable the ZeroPress layout:

{
  "front_page": {
    "type": "html",
    "file": ".zeropress/campaign.html",
    "layout": false
  }
}

Standalone HTML is trusted raw HTML and is written directly to /index.html.

Menus

menus are copied into generated preview-data.

{
  "menus": {
    "primary": {
      "name": "Primary Menu",
      "items": [
        { "title": "Home", "url": "/" },
        { "title": "Docs", "url": "/docs/" }
      ]
    }
  }
}

Menu items support:

title
url
type
target
children

Custom HTML

Use custom_html when the site needs trusted HTML injected before </head> or </body> without editing the theme.

{
  "custom_html": {
    "head_end": {
      "file": ".zeropress/head-end.html"
    },
    "body_end": {
      "file": ".zeropress/body-end.html"
    }
  }
}

Build Pages reads those files and emits internal preview-data:

{
  "custom_html": {
    "head_end": {
      "content": "<meta name=\"generator\" content=\"ZeroPress\">"
    },
    "body_end": {
      "content": "<script defer src=\"/vendor/app.js\"></script>"
    }
  }
}

The HTML is trusted raw input. ZeroPress does not sanitize it.

CSS, JavaScript, fonts, images, and third-party packages should remain normal public passthrough files. Load them from custom_html with tags such as:

<link rel="stylesheet" href="/vendor/app.css">
<script defer src="/vendor/app.js"></script>

Generated Files

Build Pages writes:

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

build-pages-config.json records the resolved user-facing Build Pages config for the current run.

preview-data.json is the internal generated build input passed to the ZeroPress renderer.

build-report.json records discovered Markdown counts, skipped Markdown files, front page resolution, and custom HTML slots. It is useful when testing larger documentation corpora. public-assets/ is a temporary staged public root used before @zeropress/build writes generated output.

Environment Variables

Common environment variables:

Name	Default	Purpose
`ZEROPRESS_PUBLIC_DIR`	none	Source root for Markdown discovery and public passthrough
`ZEROPRESS_THEME_DIR`	bundled `docs` theme	Custom theme directory
`ZEROPRESS_OUT_DIR`	`_site`	Output directory used by local scripts
`ZEROPRESS_SITE_URL`	config `site.url`	Canonical URL override
`ZEROPRESS_SKIP_UNTITLED_MARKDOWN`	`false`	Skip Markdown without an H1 instead of failing Build Pages
`ZEROPRESS_BUILD_PAGES_CONFIG`	`<source>/.zeropress/config.json`	Config path override

zeropress.dev additionally supports PRETTIER_FORMAT=false as a site-local formatting option after Build Pages completes.

Failure Policy

Build Pages fails when:

config.json is malformed JSON.
front_page.file points outside the public root.
front_page.type: "html" points outside .zeropress/.
A referenced .zeropress/*.html file is missing or empty.
Markdown selected as a page has no top-level heading, unless ZEROPRESS_SKIP_UNTITLED_MARKDOWN=true.

If config.json is missing, Build Pages falls back to defaults. This keeps the workflow usable for simple Markdown directories.