@zeropress/build-pages 0.6.2 → 0.6.3

package/README.md

@@ -85,7 +85,6 @@ jobs:
         uses: zeropress-app/zeropress-build-pages@v0
         with:
           source: ./docs
-          public-dir: ./public
           destination: ./_site
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v5
@@ -117,7 +116,6 @@ That is equivalent to:
   uses: zeropress-app/zeropress-build-pages@v0
   with:
     source: ./docs
-    public-dir: ./docs
     destination: ./_site
     theme: docs
     skip-untitled-markdown: false
@@ -131,19 +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 and optional `.zeropress/config.json`. The default is `./docs`.
-- `public-dir` is the directory copied as public passthrough files. The default is `source`.
+- `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`.
@@ -151,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.
 
@@ -169,12 +178,32 @@ with:
   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
@@ -188,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"
   }
 }
 ```
@@ -204,15 +233,15 @@ 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 optional config |
-| `--public-dir <dir>` | source | Public passthrough directory |
+| `--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
 
@@ -245,7 +274,7 @@ The source directory must not overlap the destination directory, the selected th
 
 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`
@@ -272,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:
 
@@ -332,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.
@@ -340,18 +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": {
@@ -395,27 +479,36 @@ 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.search` controls native ZeroPress search when the selected theme supports search UI. Missing or `true` enables native search for the bundled docs theme; `false` omits `/_zeropress/search.json`, `/_zeropress/search.js`, and `/_zeropress/search_pagefind.js` and hides the bundled search form.
+`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://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
-
+npx pagefind@latest --site ./_site --output-subdir _zeropress/pagefind
 cp ./_site/_zeropress/search_pagefind.js ./_site/_zeropress/search.js
 rm ./_site/_zeropress/search.json
 ```
 
-`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)
-
 ## Workspace Internal `.zeropress/` Files
 
 Build Pages reads optional site config from `<source>/.zeropress/config.json`. Separately, it writes internal working files to `.zeropress/` in the current working directory. These generated working files are not the final deploy output. The final static site is written to the `destination` directory.