@zeropress/build-pages 0.6.2 → 0.6.4

package/README.md

@@ -19,7 +19,7 @@ public directory
         |
         v
 @zeropress/build-pages
-  generates .zeropress/preview-data.json
+  generates .zeropress-build-page/preview-data.json
   stages public files
         |
         v
@@ -40,7 +40,7 @@ flowchart TD
   config --> buildPages
   publicFiles --> buildPages
 
-  buildPages --> previewData[".zeropress/preview-data.json<br/>internal generated build input"]
+  buildPages --> previewData[".zeropress-build-page/preview-data.json<br/>internal generated build input"]
   buildPages --> stagedPublic["Staged public files"]
 
   previewData --> build["@zeropress/build"]
@@ -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,27 +129,38 @@ 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` is the bundled theme name. The default is `docs`; `docs1` is an alias for `docs`.
 - `theme-path` is a custom local ZeroPress theme directory. It takes precedence over `theme`.
 - `config` is the config file path. The default is `<source>/.zeropress/config.json`.
 - `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. `docs1` aliases `docs`. |
 | `--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
 
@@ -241,11 +270,11 @@ Root-level public files named `favicon.ico`, `favicon.svg`, `favicon.png`, and `
 
 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`.
 
-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-build-page/` 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-build-page/` 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`
@@ -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:
 
@@ -283,6 +312,7 @@ description: Build a static docs site from Markdown.
 path: guides/install
 status: published
 discoverability: default
+last_updated: none
 meta:
   source: docs
 data:
@@ -308,6 +338,7 @@ Supported front matter fields:
 | `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. |
 | `discoverability` | `default`, `noindex`, or `delist`. Missing is `default`. |
+| `last_updated` | `none` or `git`. Overrides config `markdown.last_updated` for this page. |
 | `meta` | Optional scalar/null metadata copied to the generated page. |
 | `data` | Optional structured JSON-style data for theme-facing lists, facts, galleries, timelines, or swatches. |
 
@@ -323,6 +354,8 @@ Unknown front matter fields are ignored to make migration from existing Markdown
 
 `delist` is not a security or permission feature. Direct links, explicit menus, explicit collections, and body links can still expose the page.
 
+`last_updated` controls optional Git-based page metadata. If config uses `markdown.last_updated: "git"`, set `last_updated: none` on landing, index, or promotional pages that should not show an update date. If config uses `none`, set `last_updated: git` on a specific information page to opt in.
+
 Use `meta` for small scalar flags and metadata. Use `data` when a theme should iterate structured content:
 
 ```html
@@ -332,28 +365,86 @@ 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.
 
-See the public config reference at [zeropress.dev/build-pages-config](https://zeropress.dev/build-pages-config/).
+See the public config reference at [zeropress.dev/build-pages-config](https://zeropress.dev/build-pages/config/).
 
 ```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
     }
   },
+  "markdown": {
+    "last_updated": "git"
+  },
   "front_page": {
     "type": "markdown"
   },
@@ -373,6 +464,15 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
       ]
     }
   },
+  "collections": {
+    "guides": {
+      "title": "Guides",
+      "items": [
+        "getting-started/index.md",
+        "deployment/index.md"
+      ]
+    }
+  },
   "custom_html": {
     "head_end": { "file": ".zeropress/head-end.html" },
     "body_end": { "file": ".zeropress/body-end.html" }
@@ -391,37 +491,62 @@ HTML front page and `custom_html` files must stay inside `.zeropress/`.
 
 Menu item `meta` is optional scalar display metadata copied into generated preview-data for themes that manually iterate menus. Use it for small values such as `icon`, `badge`, or `accent`; arrays and objects are not accepted.
 
+`collections` defines group-level reading order from Markdown source paths. Build Pages converts each source-relative `.md` path into preview-data collection items such as `{ "type": "page", "slug": "deployment" }`. Collection prev/next cursors stop at collection boundaries, so the last item in `collections.guides` does not continue into another collection.
+
+`markdown.last_updated` is optional and accepts `none` or `git`. Missing or `none` keeps current behavior and generates no update date. `git` reads each Markdown file's latest Git commit date and adds `page.meta.last_updated_iso` plus `page.meta.last_updated` to generated preview-data when the page does not already define those meta keys. `last_updated_iso` keeps the Git ISO timestamp; `last_updated` is a stable `YYYY-MM-DD` fallback display string. For accurate history in GitHub Actions, configure checkout with `fetch-depth: 0`.
+
+Themes can render the generated value with normal escaped interpolation:
+
+```html
+{{#if page.meta.last_updated_iso}}
+  <time datetime="{{page.meta.last_updated_iso}}" data-zp-local-date>
+    {{page.meta.last_updated}}
+  </time>
+{{/if}}
+```
+
+Client-side progressive enhancement may replace the fallback text with a localized date. The fallback remains useful when JavaScript is unavailable.
+
 `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` 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
+## Workspace Internal `.zeropress-build-page/` 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.
+Build Pages reads optional user-authored site config from `<source>/.zeropress/config.json`. Separately, it writes generated internal working files to `.zeropress-build-page/` 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.
 
 ```txt
-.zeropress/
+.zeropress-build-page/
   build-pages-config.json
   preview-data.json
   build-report.json

package/action.yml

@@ -17,7 +17,7 @@ inputs:
     required: false
     default: ./_site
   theme:
-    description: Bundled theme name. Currently supports "docs".
+    description: Bundled theme name. Supports "docs" and alias "docs1".
     required: false
     default: docs
   theme-path: