@zeropress/build-pages 0.5.6 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +65 -11
- package/dist/action.js +1561 -299
- package/dist/prebuild.js +135 -23
- package/package.json +2 -2
- package/schemas/zeropress-build-pages.config.v0.1.schema.json +26 -12
- package/src/action.js +1 -1
- package/src/prebuild.js +149 -22
- package/themes/docs/layout.html +1 -1
- package/themes/docs/theme.json +4 -4
package/README.md
CHANGED
|
@@ -82,7 +82,7 @@ jobs:
|
|
|
82
82
|
- name: Build ZeroPress Pages
|
|
83
83
|
uses: zeropress-app/zeropress-build-pages@v0
|
|
84
84
|
with:
|
|
85
|
-
source: ./
|
|
85
|
+
source: ./docs
|
|
86
86
|
destination: ./_site
|
|
87
87
|
- name: Upload artifact
|
|
88
88
|
uses: actions/upload-pages-artifact@v5
|
|
@@ -144,11 +144,24 @@ In the action inputs:
|
|
|
144
144
|
- `config` is the config file path. The default is `<source>/.zeropress/config.json`.
|
|
145
145
|
- `site-url` overrides the canonical site URL from config.
|
|
146
146
|
- `skip-untitled-markdown` skips Markdown files without a page title instead of failing. The default is `false`.
|
|
147
|
-
- `skip-link-check` skips internal link checking after build. The default is `false
|
|
147
|
+
- `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.
|
|
148
148
|
- `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`.
|
|
149
149
|
|
|
150
150
|
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.
|
|
151
151
|
|
|
152
|
+
Need a custom theme? Start with [`@zeropress/create-theme`](https://www.npmjs.com/package/@zeropress/create-theme), then point `theme-path` to the generated `theme/` directory:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
npx @zeropress/create-theme --name my-docs-theme --template docs
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
```yaml
|
|
159
|
+
with:
|
|
160
|
+
source: ./docs
|
|
161
|
+
destination: ./_site
|
|
162
|
+
theme-path: ./my-docs-theme/theme
|
|
163
|
+
```
|
|
164
|
+
|
|
152
165
|
### npx
|
|
153
166
|
|
|
154
167
|
Use `npx` when you want to run Build Pages without adding it to your project dependencies.
|
|
@@ -190,7 +203,7 @@ The CLI requires explicit input and output paths. The GitHub Action keeps safe d
|
|
|
190
203
|
| `--config <path>` | `<source>/.zeropress/config.json` | Build Pages config |
|
|
191
204
|
| `--site-url <url>` | config `site.url` | Canonical URL override |
|
|
192
205
|
| `--skip-untitled-markdown` | `false` | Skip Markdown without a page title |
|
|
193
|
-
| `--skip-link-check` | `false` | Skip link checking |
|
|
206
|
+
| `--skip-link-check` | `false` | Skip warning-only internal link checking |
|
|
194
207
|
| `--no-copy-markdown-source` | `false` | Do not copy original Markdown files to output |
|
|
195
208
|
|
|
196
209
|
## Source Tree
|
|
@@ -215,6 +228,8 @@ Build Pages stages the source tree before calling [`@zeropress/build`](https://g
|
|
|
215
228
|
|
|
216
229
|
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.
|
|
217
230
|
|
|
231
|
+
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`.
|
|
232
|
+
|
|
218
233
|
The source directory must not overlap the destination directory, the selected theme directory, or the internal `.zeropress/` working directory.
|
|
219
234
|
|
|
220
235
|
Ignored while staging and Markdown discovery:
|
|
@@ -254,8 +269,16 @@ title: Install ZeroPress
|
|
|
254
269
|
description: Build a static docs site from Markdown.
|
|
255
270
|
path: guides/install
|
|
256
271
|
status: published
|
|
272
|
+
discoverability: default
|
|
257
273
|
meta:
|
|
258
274
|
source: docs
|
|
275
|
+
data:
|
|
276
|
+
stack:
|
|
277
|
+
- ZeroPress
|
|
278
|
+
- Cloudflare
|
|
279
|
+
facts:
|
|
280
|
+
- label: Role
|
|
281
|
+
value: Documentation
|
|
259
282
|
---
|
|
260
283
|
|
|
261
284
|
Body content...
|
|
@@ -271,10 +294,31 @@ Supported front matter fields:
|
|
|
271
294
|
| `description` | Page excerpt and description. |
|
|
272
295
|
| `path` | Generated route path, such as `guides/install` for `/guides/install`. |
|
|
273
296
|
| `status` | `published` includes the page. `draft` skips the page. Other values warn and skip. |
|
|
297
|
+
| `discoverability` | `default`, `noindex`, or `delist`. Missing is `default`. |
|
|
274
298
|
| `meta` | Optional scalar/null metadata copied to the generated page. |
|
|
299
|
+
| `data` | Optional structured JSON-style data for theme-facing lists, facts, galleries, timelines, or swatches. |
|
|
275
300
|
|
|
276
301
|
Unknown front matter fields are ignored to make migration from existing Markdown sites easier.
|
|
277
302
|
|
|
303
|
+
`status` controls route generation. `status: draft` removes the Markdown file from generated preview-data and no HTML route is created.
|
|
304
|
+
|
|
305
|
+
`discoverability` controls automatic exposure after a route is generated:
|
|
306
|
+
|
|
307
|
+
- `default`: no special handling.
|
|
308
|
+
- `noindex`: generate the page and add HTML robots `noindex`.
|
|
309
|
+
- `delist`: generate the page, add HTML robots `noindex`, and exclude it from automatic discovery outputs such as sitemap, native search, and generated post/page listing data.
|
|
310
|
+
|
|
311
|
+
`delist` is not a security or permission feature. Direct links, explicit menus, explicit collections, and body links can still expose the page.
|
|
312
|
+
|
|
313
|
+
Use `meta` for small scalar flags and metadata. Use `data` when a theme should iterate structured content:
|
|
314
|
+
|
|
315
|
+
```html
|
|
316
|
+
{{#for fact in page.data.facts}}
|
|
317
|
+
<dt>{{fact.label}}</dt>
|
|
318
|
+
<dd>{{fact.value}}</dd>
|
|
319
|
+
{{/for}}
|
|
320
|
+
```
|
|
321
|
+
|
|
278
322
|
## Config
|
|
279
323
|
|
|
280
324
|
Build Pages reads `<source>/.zeropress/config.json` when present. Missing config falls back to defaults.
|
|
@@ -289,12 +333,11 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
|
|
|
289
333
|
"title": "My Docs",
|
|
290
334
|
"description": "Project documentation",
|
|
291
335
|
"url": "https://example.github.io/project",
|
|
336
|
+
"expose_generator": true,
|
|
292
337
|
"indexing": true,
|
|
293
338
|
"footer": {
|
|
294
339
|
"copyright_text": "Copyright 2026 Example Corp.",
|
|
295
|
-
"attribution":
|
|
296
|
-
"enabled": true
|
|
297
|
-
}
|
|
340
|
+
"attribution": true
|
|
298
341
|
}
|
|
299
342
|
},
|
|
300
343
|
"front_page": {
|
|
@@ -305,7 +348,14 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
|
|
|
305
348
|
"name": "Primary Menu",
|
|
306
349
|
"items": [
|
|
307
350
|
{ "title": "Home", "url": "/" },
|
|
308
|
-
{
|
|
351
|
+
{
|
|
352
|
+
"title": "Guide",
|
|
353
|
+
"url": "/guide",
|
|
354
|
+
"meta": {
|
|
355
|
+
"icon": "book-open",
|
|
356
|
+
"badge": "New"
|
|
357
|
+
}
|
|
358
|
+
}
|
|
309
359
|
]
|
|
310
360
|
}
|
|
311
361
|
},
|
|
@@ -325,9 +375,13 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
|
|
|
325
375
|
|
|
326
376
|
HTML front page and `custom_html` files must stay inside `.zeropress/`.
|
|
327
377
|
|
|
378
|
+
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.
|
|
379
|
+
|
|
328
380
|
`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.
|
|
329
381
|
|
|
330
|
-
The bundled docs theme shows `Published with ZeroPress.` by default. Set `site.footer.attribution
|
|
382
|
+
The bundled docs theme shows `Published with ZeroPress.` by default. Set `site.footer.attribution` to `false` to hide it.
|
|
383
|
+
|
|
384
|
+
`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.
|
|
331
385
|
|
|
332
386
|
`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.
|
|
333
387
|
|
|
@@ -335,9 +389,9 @@ Schemas:
|
|
|
335
389
|
|
|
336
390
|
- [ZeroPress Build Pages Config v0.1](https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json)
|
|
337
391
|
|
|
338
|
-
## Internal `.zeropress/` Files
|
|
392
|
+
## Workspace Internal `.zeropress/` Files
|
|
339
393
|
|
|
340
|
-
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.
|
|
394
|
+
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.
|
|
341
395
|
|
|
342
396
|
```txt
|
|
343
397
|
.zeropress/
|
|
@@ -357,7 +411,7 @@ Build Pages writes internal working files to `.zeropress/` in the current workin
|
|
|
357
411
|
|
|
358
412
|
## Destination Output
|
|
359
413
|
|
|
360
|
-
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.
|
|
414
|
+
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`.
|
|
361
415
|
|
|
362
416
|
## Demo
|
|
363
417
|
|