@zeropress/build-pages 0.6.1 → 0.6.3

package/README.md

@@ -5,7 +5,7 @@
 
 Build ZeroPress static output for modern hosting platforms.
 
-`@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`](https://github.com/zeropress-app/zeropress-build).
+`@zeropress/build-pages` turns 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`](https://github.com/zeropress-app/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.
 
@@ -13,7 +13,9 @@ The generated output is plain static files that can be deployed to GitHub Pages,
 
 ```txt
 source directory
-  Markdown pages + .zeropress/config.json + public files
+  Markdown pages + .zeropress/config.json
+public directory
+  public files (defaults to source)
         |
         v
 @zeropress/build-pages
@@ -32,7 +34,7 @@ static output directory
 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"]
+  publicRoot["Public directory<br/>defaults to source"] --> publicFiles["Public files<br/>images, CSS, JS, PDF, JSON, Markdown"]
 
   markdown --> buildPages["@zeropress/build-pages"]
   config --> buildPages
@@ -127,17 +129,30 @@ Custom input example:
 - name: Build ZeroPress Pages
   uses: zeropress-app/zeropress-build-pages@v0
   with:
-    source: ./documents
+    source: ./docs
+    public-dir: ./public
     destination: ./_site
     theme-path: ./theme-docs
-    config: ./documents/.zeropress/config.json
+    config: ./docs/.zeropress/config.json
     site-url: https://example.com/docs
     copy-markdown-source: false
 ```
 
+Separate public asset directory example:
+
+```yaml
+- name: Build ZeroPress Pages
+  uses: zeropress-app/zeropress-build-pages@v0
+  with:
+    source: ./docs
+    public-dir: ./public
+    destination: ./_site
+```
+
 In the action inputs:
 
-- `source` is the directory that contains your Markdown pages, public files, and optional `.zeropress/config.json`. The default is `./docs`.
+- `source` is the directory that contains your Markdown pages and optional `.zeropress/config.json`. The default is `./docs`.
+- `public-dir` is the directory copied as public passthrough files. The default is `source`. If you set it explicitly, the directory must exist.
 - `destination` is the directory where the generated static site is written. The default is `./_site`.
 - `theme` is the bundled theme name. The default is `docs`.
 - `theme-path` is a custom local ZeroPress theme directory. It takes precedence over `theme`.
@@ -145,7 +160,7 @@ In the action inputs:
 - `site-url` overrides the canonical site URL from config.
 - `skip-untitled-markdown` skips Markdown files without a page title instead of failing. The default is `false`.
 - `skip-link-check` skips internal link checking after build. The default is `false`; broken internal links are reported as warnings and do not fail the build.
-- `copy-markdown-source` copies original Markdown files to the generated output and enables `View this page as Markdown` links in the bundled docs theme. The default is `true`.
+- `copy-markdown-source` copies original Markdown files to the generated output and enables `View this page as Markdown` links in the bundled docs theme. The default is `true`; when set to `false`, public `.md` passthrough files are also skipped.
 
 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.
 
@@ -158,16 +173,37 @@ npx @zeropress/create-theme --name my-docs-theme --template docs
 ```yaml
 with:
   source: ./docs
+  public-dir: ./public
   destination: ./_site
   theme-path: ./my-docs-theme/theme
 ```
 
+### Vercel
+
+Use the `Other` framework preset and set the generated output directory as Vercel's Output Directory.
+
+Project settings:
+
+| Setting | Value |
+| --- | --- |
+| Framework Preset | `Other` |
+| Build Command | `npx --yes @zeropress/build-pages --source ./docs --destination ./_site` |
+| Output Directory | `_site` |
+
+If your public assets live outside the source directory, include `--public-dir`:
+
+```bash
+npx --yes @zeropress/build-pages --source ./docs --public-dir ./public --destination ./_site
+```
+
+If your project uses a `package.json` script, set the Vercel Build Command to `npm run build` and keep the Output Directory as `_site`.
+
 ### npx
 
 Use `npx` when you want to run Build Pages without adding it to your project dependencies.
 
 ```bash
-npx @zeropress/build-pages --source ./documents --destination ./_site
+npx @zeropress/build-pages --source ./docs --destination ./_site
 ```
 
 ### package.json script
@@ -181,7 +217,7 @@ npm install --save-dev @zeropress/build-pages
 ```json
 {
   "scripts": {
-    "build": "zeropress-build-pages --source ./documents --destination ./_site"
+    "build": "zeropress-build-pages --source ./docs --destination ./_site"
   }
 }
 ```
@@ -196,19 +232,20 @@ The CLI requires explicit input and output paths. The GitHub Action keeps safe d
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `--source <dir>` | required | Dedicated source directory containing Markdown and public files |
+| `--source <dir>` | required | Dedicated source directory containing Markdown and optional config |
+| `--public-dir <dir>` | source | Public passthrough directory. Explicit paths must exist. |
 | `--destination <dir>` | required | Output directory |
-| `--theme docs` | `docs` | Bundled docs theme |
+| `--theme <name>` | `docs` | Bundled theme name |
 | `--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 a page title |
 | `--skip-link-check` | `false` | Skip warning-only internal link checking |
-| `--no-copy-markdown-source` | `false` | Do not copy original Markdown files to output |
+| `--no-copy-markdown-source` | `false` | Do not copy source Markdown or public `.md` files to output |
 
 ## Source Tree
 
-The source directory is the folder that Build Pages reads. It is both the Markdown source root and the public passthrough root. GitHub Action usage defaults to `./docs`; CLI usage requires `--source`.
+The source directory is the folder that Build Pages reads for Markdown pages and optional `.zeropress/config.json`. By default, the source directory is also the public passthrough root. Use `public-dir` when you want to keep Markdown source and public assets separate.
 
 Use a dedicated content directory such as `docs/` or `documents/`. Repository root source (`--source ./`) is not supported.
 
@@ -217,22 +254,27 @@ my-site/
   docs/                 # source
     index.md
     guide.md
-    assets/
-      logo.png
     .zeropress/
       config.json
+  public/               # public-dir, optional
+    assets/
+      logo.png
+    favicon.svg
+    robots.txt
   _site/                # destination, generated
 ```
 
-Build Pages stages the source tree before calling [`@zeropress/build`](https://github.com/zeropress-app/zeropress-build). Generated ZeroPress output wins over staged public files.
+Build Pages stages the public directory before calling [`@zeropress/build`](https://github.com/zeropress-app/zeropress-build). Generated ZeroPress output wins over staged public files.
+
+Root-level public files named `favicon.ico`, `favicon.svg`, `favicon.png`, and `apple-touch-icon.png` are copied to the destination and auto-injected into generated HTML `<head>` output.
 
-Root-level source favicon files named `favicon.ico`, `favicon.svg`, `favicon.png`, and `apple-touch-icon.png` are copied to the destination and auto-injected into generated HTML `<head>` output.
+A root-level public `sitemap.xsl` is copied to the destination. When ZeroPress generates `sitemap.xml`, it auto-discovers that file and adds an XML stylesheet processing instruction for `/sitemap.xsl`.
 
-A root-level source `sitemap.xsl` is copied to the destination. When ZeroPress generates `sitemap.xml`, it auto-discovers that file and adds an XML stylesheet processing instruction for `/sitemap.xsl`.
+The source directory must not overlap the destination directory, the selected theme directory, or the internal `.zeropress/` working directory. An explicit public directory must be an existing dedicated directory and must not be a file, symlink, repository root, destination directory, selected theme directory, or internal `.zeropress/` working directory.
 
-The source directory must not overlap the destination directory, the selected theme directory, or the internal `.zeropress/` working directory.
+If `public-dir` is inside `source`, Build Pages excludes that public subtree from Markdown page discovery.
 
-Ignored while staging and Markdown discovery:
+Ignored while copying public passthrough files and discovering Markdown pages:
 
 - hidden paths such as `.git`, `.env`, and `.zeropress`
 - `node_modules`
@@ -259,7 +301,7 @@ Additional Markdown discovery ignores:
 - 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 by default.
-- Use `--no-copy-markdown-source` or Action input `copy-markdown-source: false` to keep source Markdown out of the generated output. This also hides bundled theme `View this page as Markdown` links.
+- Use `--no-copy-markdown-source` or Action input `copy-markdown-source: false` to keep source Markdown and public `.md` passthrough files out of the generated output. This also hides bundled theme `View this page as Markdown` links.
 
 Optional YAML front matter is supported at the top of Markdown files:
 
@@ -319,6 +361,52 @@ Use `meta` for small scalar flags and metadata. Use `data` when a theme should i
 {{/for}}
 ```
 
+## Markdown Rendering
+
+Build Pages renders Markdown through ZeroPress build-core before writing HTML.
+This includes common Markdown extensions such as tables, strikethrough, task
+lists, GitHub-style alerts, heading IDs, and fenced code blocks.
+
+Fenced code blocks are highlighted at build time with `highlight.js`.
+
+````md
+```js
+console.log("hello");
+```
+````
+
+When a fenced code block has a language info string and `highlight.js`
+recognizes it, ZeroPress uses that language. If the language is missing or not
+recognized, ZeroPress falls back to automatic detection. The generated markup
+keeps the `language-*` class and adds `hljs-*` token classes for highlighted
+spans:
+
+```html
+<pre><code class="language-js">...</code></pre>
+```
+
+Themes only need CSS for the generated code markup. A client-side
+`highlight.js` script is not required for Markdown rendered during the build.
+
+ZeroPress build-core currently uses `highlight.js@11.11.1` and the built-in
+languages returned by `hljs.listLanguages()`. In this release, that is 192
+canonical language names, plus recognized aliases such as `js`, `ts`, `jsx`,
+`sh`, and `zsh`. A language listed in the Highlight.js documentation with a
+third-party package is not bundled by ZeroPress unless it is also present in
+`hljs.listLanguages()`.
+
+See the upstream
+[`highlight.js@11.11.1` supported languages table](https://github.com/highlightjs/highlight.js/blob/11.11.1/SUPPORTED_LANGUAGES.md)
+for language names, aliases, and third-party package notes. Common built-in
+examples include `bash`, `shell`, `js`, `javascript`, `ts`, `typescript`,
+`json`, `yaml`, `html`, `xml`, `css`, `scss`, `python`, `ruby`, `php`, `java`,
+`go`, `rust`, `c`, `cpp`, `csharp`, `sql`, `graphql`, `dockerfile`, `nginx`,
+`markdown`, and `diff`.
+
+Mermaid is intentionally different: `mermaid` fences remain readable code
+blocks such as `pre code.language-mermaid`. Diagram rendering is optional
+progressive enhancement owned by the theme or site.
+
 ## Config
 
 Build Pages reads `<source>/.zeropress/config.json` when present. Missing config falls back to defaults.
@@ -327,17 +415,27 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
 
 ```json
 {
-  "$schema": "https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json",
+  "$schema": "https://schemas.zeropress.dev/build-pages-config/v0.1/schema.json",
   "version": "0.1",
   "site": {
     "title": "My Docs",
     "description": "Project documentation",
     "url": "https://example.github.io/project",
+    "logo": {
+      "src": "/logo.svg",
+      "alt": "My Docs"
+    },
+    "locale": "en-US",
     "expose_generator": true,
+    "search": true,
     "indexing": true,
     "footer": {
       "copyright_text": "Copyright 2026 Example Corp.",
       "attribution": true
+    },
+    "meta": {
+      "issue": "Spring 2026",
+      "show_sponsor_banner": false
     }
   },
   "front_page": {
@@ -381,13 +479,35 @@ Menu item `meta` is optional scalar display metadata copied into generated previ
 
 The bundled docs theme shows `Published with ZeroPress.` by default. Set `site.footer.attribution` to `false` to hide it.
 
+`site.logo` is optional theme-facing brand data. Use a root-relative public path for public logo files, or an absolute URL for media-hosted logos. Build Pages emits `media_base_url: ""`, so root-relative logo paths remain same-host public paths.
+
+`site.locale` is optional language metadata copied into generated preview-data. It affects theme-facing `site.locale`, the common `language` render context value, generated HTML language metadata, and feed language. Missing `site.locale` defaults to `en-US`.
+
+`site.meta` is an optional scalar extension map copied into generated preview-data. Use it for site-level theme conventions such as labels, feature flags, or issue names. Values must be strings, finite numbers, booleans, or null. Use first-class fields such as `site.logo.src` instead of ad hoc keys like `site.meta.logo_url`.
+
 `site.expose_generator` controls the HTML generator meta tag. Missing or `true` emits `<meta name="generator" content="ZeroPress">`; set it to `false` for white-label sites.
 
-`site.indexing` controls only the generated fallback `robots.txt`. Missing or `true` allows indexing; `false` writes `User-agent: *` / `Disallow: /`. If the source directory contains `robots.txt`, that file is copied as-is and takes priority over `site.indexing`. ZeroPress does not append a `Sitemap` directive to a source-provided `robots.txt`; add `Sitemap: https://example.com/sitemap.xml` manually when needed.
+`site.indexing` controls only the generated fallback `robots.txt`. Missing or `true` allows indexing; `false` writes `User-agent: *` / `Disallow: /`. If the public directory contains `robots.txt`, that file is copied as-is and takes priority over `site.indexing`. ZeroPress does not append a `Sitemap` directive to a public `robots.txt`; add `Sitemap: https://example.com/sitemap.xml` manually when needed.
 
 Schemas:
 
-- [ZeroPress Build Pages Config v0.1](https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json)
+- [ZeroPress Build Pages Config v0.1](https://schemas.zeropress.dev/build-pages-config/v0.1/schema.json)
+
+## Search
+
+The bundled docs theme supports ZeroPress native search. `site.search` controls whether search artifacts and bundled search UI are enabled.
+
+Missing or `true` enables native search for the bundled docs theme. Build Pages writes `/_zeropress/search.json`, `/_zeropress/search.js`, and `/_zeropress/search_pagefind.js`.
+
+Set `site.search` to `false` to omit those search artifacts and hide the bundled search form.
+
+The bundled docs theme marks post/page body content with `data-pagefind-body`. If you run Pagefind after the ZeroPress build, keep the theme UI pointed at `/_zeropress/search.js` and replace the native adapter:
+
+```bash
+npx pagefind@latest --site ./_site --output-subdir _zeropress/pagefind
+cp ./_site/_zeropress/search_pagefind.js ./_site/_zeropress/search.js
+rm ./_site/_zeropress/search.json
+```
 
 ## Workspace Internal `.zeropress/` Files
 
@@ -405,13 +525,13 @@ Build Pages reads optional site config from `<source>/.zeropress/config.json`. S
 
 `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, source Markdown copy policy, and custom HTML slots.
+`build-report.json` records source/public roots, discovered Markdown counts, skipped Markdown files, front page resolution, source Markdown copy policy, 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 Markdown source copy is disabled or files are excluded by the public passthrough rules. A source `robots.txt` is copied as a site-owned policy file; otherwise ZeroPress writes a fallback `robots.txt` with a sitemap directive when `site.url` is available. Root-level source favicon files are copied and represented as generated HTML head links. A root-level source `sitemap.xsl` is copied and linked from generated `sitemap.xml`.
+The `destination` directory contains the deployable static site. It includes generated ZeroPress HTML, copied public files, and original Markdown files unless Markdown source copy is disabled or files are excluded by the public passthrough rules. A public `robots.txt` is copied as a site-owned policy file; otherwise ZeroPress writes a fallback `robots.txt` with a sitemap directive when `site.url` is available. Root-level public favicon files are copied and represented as generated HTML head links. A root-level public `sitemap.xsl` is copied and linked from generated `sitemap.xml`.
 
 ## Demo
 

package/action.yml

@@ -9,6 +9,9 @@ inputs:
     description: Dedicated source directory containing Markdown files and optional .zeropress/config.json. Repository root source is not supported.
     required: false
     default: ./docs
+  public-dir:
+    description: Public passthrough directory for site-owned assets. Defaults to source.
+    required: false
   destination:
     description: Output directory for the generated static site.
     required: false