@zeropress/build-pages 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeroPress
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @zeropress/build-pages
+
+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`.
+
+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
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - name: Build ZeroPress Pages
+        uses: zeropress-app/zeropress-build-pages@v0
+        with:
+          source: ./
+          destination: ./_site
+          theme: docs
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./_site
+```
+
+The action builds the static files only. Uploading and deploying are handled by your hosting provider's deployment action or CLI.
+
+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
+
+```bash
+npx @zeropress/build-pages --source ./docs --destination ./_site
+```
+
+Options:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `--source <dir>` | `.` | Source directory containing Markdown and public files |
+| `--destination <dir>` | `_site` | Output directory |
+| `--out <dir>` | `_site` | Alias for `--destination` |
+| `--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.
+
+## Source Tree
+
+The source directory is both the Markdown source root and the public passthrough root.
+
+```txt
+docs/
+  index.md
+  guide.md
+  assets/
+  .zeropress/
+    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.
+
+Ignored while staging and Markdown discovery:
+
+- hidden paths such as `.git`, `.env`, and `.zeropress`
+- `node_modules`
+- `Thumbs.db`
+- `*.key`
+- `*.pem`
+- symlinks
+
+Additional Markdown discovery ignores:
+
+- path segments starting with `_`
+- path segments starting with `#`
+- path segments ending with `~`
+- `vendor`
+
+## Markdown Discovery
+
+- `*.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.
+- 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.
+
+## 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",
+  "version": "0.1",
+  "site": {
+    "title": "My Docs",
+    "description": "Project documentation",
+    "url": "https://example.github.io/project",
+    "footer": {
+      "copyright_text": "Copyright 2026 Example Corp.",
+      "attribution": {
+        "enabled": true
+      }
+    }
+  },
+  "front_page": {
+    "type": "markdown"
+  },
+  "menus": {
+    "primary": {
+      "name": "Primary Menu",
+      "items": [
+        { "title": "Home", "url": "/" },
+        { "title": "Guide", "url": "/guide" }
+      ]
+    }
+  },
+  "custom_html": {
+    "head_end": { "file": ".zeropress/head-end.html" },
+    "body_end": { "file": ".zeropress/body-end.html" }
+  }
+}
+```
+
+`front_page` modes:
+
+- `{ "type": "theme_index" }`: render bundled theme home.
+- `{ "type": "markdown" }`: render `index.md` through `page.html`.
+- `{ "type": "html" }`: render `.zeropress/index.html` through `page.html`.
+- `{ "type": "html", "layout": false }`: write trusted standalone HTML directly.
+
+HTML front page and `custom_html` files must stay inside `.zeropress/`.
+
+`site.footer.copyright_text` is rendered by the bundled docs theme when present. If it is omitted, the bundled docs 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.
+
+Schemas:
+
+- `schemas/zeropress-build-pages.config.v0.1.schema.json`
+- `schemas/zeropress-build-pages.config.schema.json`
+
+## Generated Files
+
+Build Pages writes:
+
+```txt
+.zeropress/
+  preview-data.json
+  prebuild-report.json
+  build-pages-public/
+```
+
+`preview-data.json` is the generated preview-data v0.5 input passed to `@zeropress/build`.
+
+## Development
+
+```bash
+npm install
+npm run build:action
+npm test
+```

package/action.yml

@@ -0,0 +1,39 @@
+name: Build ZeroPress Pages
+description: Build ZeroPress static output for GitHub Pages, Cloudflare Pages, Netlify, Vercel, and other static hosts.
+author: ZeroPress
+branding:
+  icon: book-open
+  color: blue
+inputs:
+  source:
+    description: Source directory containing Markdown files and optional .zeropress/config.json.
+    required: false
+    default: ./
+  destination:
+    description: Output directory for the generated static site.
+    required: false
+    default: ./_site
+  theme:
+    description: Bundled theme name. Currently supports "docs".
+    required: false
+    default: docs
+  theme-path:
+    description: Custom ZeroPress theme directory. Takes precedence over theme.
+    required: false
+  config:
+    description: Config file path. Defaults to <source>/.zeropress/config.json.
+    required: false
+  site-url:
+    description: Canonical site URL override.
+    required: false
+  skip-untitled-markdown:
+    description: Skip Markdown files without an H1 instead of failing.
+    required: false
+    default: "false"
+  check-links:
+    description: Warn about broken internal links after build.
+    required: false
+    default: "true"
+runs:
+  using: node24
+  main: dist/action.js

package/bin/zeropress-build-pages.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../src/index.js';
+
+runCli(process.argv.slice(2));