@zeropress/build-pages 0.5.1 → 0.5.4

package/README.md

@@ -2,71 +2,156 @@
 
 Build ZeroPress static output for modern hosting platforms.
 
-`@zeropress/build-pages` turns a directory of Markdown files and public assets into static ZeroPress output. It discovers Markdown files, converts them to preview-data v0.5, stages public files, and runs `@zeropress/build`.
+`@zeropress/build-pages` turns a directory of Markdown files and public assets into a static ZeroPress site. It discovers Markdown pages, prepares the site data, stages public files, and runs `@zeropress/build`.
 
 The generated output is plain static files that can be deployed to GitHub Pages, Cloudflare Pages, Netlify, Vercel, or any static hosting provider.
 
-## GitHub Action
+## Build Flow
+
+```txt
+source directory
+  Markdown pages + .zeropress/config.json + public files
+        |
+        v
+@zeropress/build-pages
+  generates .zeropress/preview-data.json
+  stages public files
+        |
+        v
+@zeropress/build + ZeroPress theme
+        |
+        v
+static output directory
+  HTML pages + assets + copied public files
+```
+
+```mermaid
+flowchart TD
+  source["Source directory"] --> markdown["Markdown pages (*.md)"]
+  source --> config[".zeropress/config.json"]
+  source --> publicFiles["Public files<br/>images, CSS, JS, PDF, JSON, Markdown"]
+
+  markdown --> buildPages["@zeropress/build-pages"]
+  config --> buildPages
+  publicFiles --> buildPages
+
+  buildPages --> previewData[".zeropress/preview-data.json<br/>internal generated build input"]
+  buildPages --> stagedPublic["Staged public files"]
+
+  previewData --> build["@zeropress/build"]
+  stagedPublic --> build
+  theme["ZeroPress theme"] --> build
+
+  build --> output["Static output directory"]
+  output --> html["HTML pages"]
+  output --> assets["Theme assets"]
+  output --> copied["Copied public files"]
+  output --> special["sitemap.xml / robots.txt / feed.xml"]
+```
+
+## Usage
+
+### GitHub Action
+
+A basic Pages deployment workflow with the `zeropress-build-pages` action looks like this.
 
 ```yaml
+name: Build and Deploy Docs to GitHub Pages
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/configure-pages@v5
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
       - name: Build ZeroPress Pages
         uses: zeropress-app/zeropress-build-pages@v0
         with:
-          source: ./
+          source: ./documents
           destination: ./_site
-          theme: docs
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
 ```
 
-The action builds the static files only. Uploading and deploying are handled by your hosting provider's deployment action or CLI.
+The action `zeropress-build-pages` builds the static files only. Uploading and deploying are handled by your hosting provider's deployment action or CLI.
+
+In the action inputs:
+
+- `source` is the directory that contains your Markdown pages, public files, and optional `.zeropress/config.json`. The default is `./docs`.
+- `destination` is the directory where the generated static site is written. The default is `./_site`.
 
 For GitHub Pages, the generated `destination` directory can be passed to `actions/upload-pages-artifact`. For Cloudflare Pages, Netlify, Vercel, or another static host, pass the same `destination` directory to that provider's deploy step.
 
-## CLI
+### npx
+
+Use `npx` when you want to run Build Pages without adding it to your project dependencies.
 
 ```bash
-npx @zeropress/build-pages --source ./docs --destination ./_site
+npx @zeropress/build-pages --source ./documents --destination ./_site
 ```
 
-Options:
+### package.json script
+
+Use a package script when your project already has a Node.js toolchain.
+
+```bash
+npm install --save-dev @zeropress/build-pages
+```
+
+```json
+{
+  "scripts": {
+    "build": "zeropress-build-pages --source ./documents --destination ./_site"
+  }
+}
+```
+
+```bash
+npm run build
+```
+
+## CLI Options
+
+The CLI requires explicit input and output paths. The GitHub Action keeps safe defaults for workflow convenience.
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `--source <dir>` | `.` | Source directory containing Markdown and public files |
-| `--destination <dir>` | `_site` | Output directory |
-| `--out <dir>` | `_site` | Alias for `--destination` |
+| `--source <dir>` | required | Dedicated source directory containing Markdown and public files |
+| `--destination <dir>` | required | Output directory |
 | `--theme docs` | `docs` | Bundled docs theme |
 | `--theme-path <dir>` | none | Custom ZeroPress theme directory |
 | `--config <path>` | `<source>/.zeropress/config.json` | Build Pages config |
 | `--site-url <url>` | config `site.url` | Canonical URL override |
-| `--skip-untitled-markdown` | `false` | Skip Markdown without an H1 |
-| `--check-links` | `true` | Warn about broken internal links |
-| `--no-check-links` | false | Skip link checking |
-
-Equivalent environment variables:
-
-| Env | Maps to |
-| --- | --- |
-| `ZEROPRESS_PUBLIC_DIR` | `--source` |
-| `ZEROPRESS_OUT_DIR` | `--destination` |
-| `ZEROPRESS_THEME_DIR` | `--theme-path` |
-| `ZEROPRESS_BUILD_PAGES_CONFIG` | `--config` |
-| `ZEROPRESS_SITE_URL` | `--site-url` |
-| `ZEROPRESS_SKIP_UNTITLED_MARKDOWN=true` | `--skip-untitled-markdown` |
-
-CLI options take precedence over environment variables.
+| `--skip-untitled-markdown` | `false` | Skip Markdown without a page title |
+| `--skip-link-check` | `false` | Skip link checking |
 
 ## Source Tree
 
-The source directory is both the Markdown source root and the public passthrough root.
+The source directory is both the Markdown source root and the public passthrough root. GitHub Action usage defaults to `./docs`; CLI usage requires `--source`.
+
+Use a dedicated content directory such as `docs/` or `documents/`. Repository root source (`--source ./`) is not supported, because Build Pages uses `.zeropress/` in the current working directory for internal working files.
 
 ```txt
 docs/
@@ -77,7 +162,9 @@ docs/
     config.json
 ```
 
-Build Pages stages the source tree before calling `@zeropress/build`, so `--source ./` and `--destination ./_site` are supported. Generated ZeroPress output wins over staged public files.
+Build Pages stages the source tree before calling `@zeropress/build`. Generated ZeroPress output wins over staged public files.
+
+The source directory must not overlap the destination directory, the selected theme directory, or the internal `.zeropress/` working directory.
 
 Ignored while staging and Markdown discovery:
 
@@ -95,24 +182,54 @@ Additional Markdown discovery ignores:
 - path segments ending with `~`
 - `vendor`
 
-## Markdown Discovery
+## Markdown Pages
 
 - `*.md` files are discovered recursively.
-- Each Markdown page needs an ATX H1 (`# Title`) or Setext H1 (`Title` + `====`).
-- Missing or empty H1 fails the build unless `--skip-untitled-markdown` is used.
+- Each Markdown page needs a page title. Build Pages uses front matter `title`, then an ATX H1 (`# Title`), then a Setext H1 (`Title` + `====`).
+- If no title can be found, the build fails unless `--skip-untitled-markdown` is used.
+- `--skip-untitled-markdown` skips those Markdown files. It does not create untitled pages.
 - Root `index.md` becomes the front page when no config is present.
 - Nested `index.md` maps to a directory route, such as `cli/index.md` -> `/cli/`.
 - Other Markdown files map to extensionless routes, such as `cli/tool.md` -> `/cli/tool`.
 - Markdown links to other discovered `.md` files are rewritten to generated public URLs.
 - Original Markdown files remain available as public passthrough files.
 
+Optional YAML front matter is supported at the top of Markdown files:
+
+```md
+---
+title: Install ZeroPress
+description: Build a static docs site from Markdown.
+path: guides/install
+status: published
+meta:
+  source: docs
+---
+
+Body content...
+```
+
+All supported front matter fields are optional. When `status` is omitted, the page is treated as `published`.
+
+Supported front matter fields:
+
+| Field | Purpose |
+| --- | --- |
+| `title` | Page title. Takes priority over Markdown H1. |
+| `description` | Page excerpt and description. |
+| `path` | Generated route path, such as `guides/install` for `/guides/install`. |
+| `status` | `published` includes the page. `draft` skips the page. Other values warn and skip. |
+| `meta` | Optional scalar/null metadata copied to the generated page. |
+
+Unknown front matter fields are ignored to make migration from existing Markdown sites easier.
+
 ## Config
 
 Build Pages reads `<source>/.zeropress/config.json` when present. Missing config falls back to defaults.
 
 ```json
 {
-  "$schema": "../schemas/zeropress-build-pages.config.v0.1.schema.json",
+  "$schema": "https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json",
   "version": "0.1",
   "site": {
     "title": "My Docs",
@@ -162,18 +279,29 @@ Schemas:
 - `schemas/zeropress-build-pages.config.v0.1.schema.json`
 - `schemas/zeropress-build-pages.config.schema.json`
 
-## Generated Files
+## Internal `.zeropress/` Files
 
-Build Pages writes:
+Build Pages writes internal working files to `.zeropress/` in the current working directory. These files are not the final deploy output. The final static site is written to the `destination` directory.
 
 ```txt
 .zeropress/
+  build-pages-config.json
   preview-data.json
-  prebuild-report.json
-  build-pages-public/
+  build-report.json
+  public-assets/
 ```
 
-`preview-data.json` is the generated preview-data v0.5 input passed to `@zeropress/build`.
+`build-pages-config.json` is the resolved user-facing Build Pages config used for the current run. It combines source config, defaults, and CLI or Action input overrides where applicable.
+
+`preview-data.json` is an internal generated build input for the ZeroPress renderer. Most users do not need to edit or understand this file.
+
+`build-report.json` records discovered Markdown counts, skipped Markdown files, front page resolution, and custom HTML slots.
+
+`public-assets/` is a temporary staged public root used before the final ZeroPress render.
+
+## Destination Output
+
+The `destination` directory contains the deployable static site. It includes generated ZeroPress HTML, copied public files, and original Markdown files unless they are excluded by the public passthrough rules.
 
 ## Development
 

package/action.yml

@@ -6,9 +6,9 @@ branding:
   color: blue
 inputs:
   source:
-    description: Source directory containing Markdown files and optional .zeropress/config.json.
+    description: Dedicated source directory containing Markdown files and optional .zeropress/config.json. Repository root source is not supported.
     required: false
-    default: ./
+    default: ./docs
   destination:
     description: Output directory for the generated static site.
     required: false
@@ -27,13 +27,13 @@ inputs:
     description: Canonical site URL override.
     required: false
   skip-untitled-markdown:
-    description: Skip Markdown files without an H1 instead of failing.
+    description: Skip Markdown files without a page title instead of failing.
     required: false
     default: "false"
-  check-links:
-    description: Warn about broken internal links after build.
+  skip-link-check:
+    description: Skip internal link checking after the site is built.
     required: false
-    default: "true"
+    default: "false"
 runs:
   using: node24
   main: dist/action.js

package/dist/action.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createRequire as __zeropressCreateRequire } from "node:module";
+const require = __zeropressCreateRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -62137,9 +62139,9 @@ async function linkExists(siteDir, link2) {
 // src/index.js
 var __dirname = path3.dirname(fileURLToPath(import.meta.url));
 var packageDir = path3.resolve(__dirname, "..");
-var prebuildScript = path3.join(packageDir, "src", "prebuild.js");
+var prebuildScript = __dirname === path3.join(packageDir, "dist") ? path3.join(__dirname, "prebuild.js") : path3.join(packageDir, "src", "prebuild.js");
 var PREVIEW_DATA_PATH = ".zeropress/preview-data.json";
-var STAGING_DIR = ".zeropress/build-pages-public";
+var STAGING_DIR = ".zeropress/public-assets";
 var DEFAULT_THEME = "docs";
 async function runBuildPages(options2) {
   const cwd = path3.resolve(options2.cwd || process.cwd());
@@ -62149,6 +62151,13 @@ async function runBuildPages(options2) {
   const stagingDir = path3.join(cwd, STAGING_DIR);
   const previewDataPath = path3.join(cwd, PREVIEW_DATA_PATH);
   const themeDir = resolveThemeDir(cwd, options2);
+  assertBuildPagesPathLayout({
+    cwd,
+    sourceDir,
+    destinationDir,
+    themeDir,
+    generatedDir
+  });
   await assertDirectory(sourceDir, "Source directory");
   await fs3.rm(generatedDir, { recursive: true, force: true });
   await fs3.mkdir(generatedDir, { recursive: true });
@@ -62195,7 +62204,7 @@ async function runBuildPages(options2) {
       process.env.ZEROPRESS_PUBLIC_DIR = previousPublicDir;
     }
   }
-  if (options2.checkLinks) {
+  if (!options2.skipLinkCheck) {
     const result = await checkInternalLinks(destinationDir);
     if (result.brokenLinks.length) {
       console.warn("Warning: broken internal links found:");
@@ -62229,6 +62238,26 @@ async function assertDirectory(dir, label) {
     throw new Error(`${label} is not a directory: ${dir}`);
   }
 }
+function assertBuildPagesPathLayout({ cwd, sourceDir, destinationDir, themeDir, generatedDir }) {
+  if (samePath(sourceDir, cwd)) {
+    throw new Error(
+      `Source directory must be a dedicated content directory, not the current working directory. Received: ${formatPath(cwd, sourceDir)}`
+    );
+  }
+  assertNoPathOverlap(cwd, "Source directory", sourceDir, "internal .zeropress working directory", generatedDir);
+  assertNoPathOverlap(cwd, "Destination directory", destinationDir, "internal .zeropress working directory", generatedDir);
+  assertNoPathOverlap(cwd, "Theme directory", themeDir, "internal .zeropress working directory", generatedDir);
+  assertNoPathOverlap(cwd, "Source directory", sourceDir, "destination directory", destinationDir);
+  assertNoPathOverlap(cwd, "Source directory", sourceDir, "theme directory", themeDir);
+}
+function assertNoPathOverlap(cwd, firstLabel, firstPath, secondLabel, secondPath) {
+  if (!pathsOverlap2(firstPath, secondPath)) {
+    return;
+  }
+  throw new Error(
+    `${firstLabel} must not overlap the ${secondLabel}. ${firstLabel}: ${formatPath(cwd, firstPath)}; ${secondLabel}: ${formatPath(cwd, secondPath)}`
+  );
+}
 async function copyPublicStaging(sourceDir, targetDir, options2) {
   const entries = await fs3.readdir(sourceDir, { withFileTypes: true });
   for (const entry of entries) {
@@ -62265,6 +62294,9 @@ function pathsOverlap2(firstPath, secondPath) {
   const second = path3.resolve(secondPath);
   return first === second || isPathInside2(first, second) || isPathInside2(second, first);
 }
+function samePath(firstPath, secondPath) {
+  return path3.resolve(firstPath) === path3.resolve(secondPath);
+}
 function isPathInside2(parentPath, childPath) {
   const relativePath = path3.relative(parentPath, childPath);
   return Boolean(relativePath) && !relativePath.startsWith("..") && !path3.isAbsolute(relativePath);
@@ -62276,14 +62308,14 @@ function formatPath(cwd, targetPath) {
 
 // src/action.js
 var options = {
-  source: input("source") || "./",
+  source: input("source") || "./docs",
   destination: input("destination") || "./_site",
   theme: input("theme") || "docs",
   themePath: input("theme-path"),
   config: input("config"),
   siteUrl: input("site-url"),
   skipUntitledMarkdown: booleanInput("skip-untitled-markdown", false),
-  checkLinks: booleanInput("check-links", true)
+  skipLinkCheck: booleanInput("skip-link-check", false)
 };
 try {
   await runBuildPages(options);