@zeropress/build-pages 0.5.5 → 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 +71 -12
- package/dist/action.js +2159 -289
- package/dist/prebuild.js +147 -24
- package/package.json +2 -2
- package/schemas/zeropress-build-pages.config.v0.1.schema.json +35 -14
- package/src/action.js +1 -1
- package/src/prebuild.js +161 -22
- package/themes/docs/layout.html +1 -1
- package/themes/docs/theme.json +4 -4
- package/schemas/zeropress-build-pages.config.schema.json +0 -5
package/README.md
CHANGED
|
@@ -49,7 +49,7 @@ flowchart TD
|
|
|
49
49
|
output --> html["HTML pages"]
|
|
50
50
|
output --> assets["Theme assets"]
|
|
51
51
|
output --> copied["Copied public files"]
|
|
52
|
-
output --> special["sitemap.xml / robots.txt / feed.xml"]
|
|
52
|
+
output --> special["sitemap.xml / fallback robots.txt / feed.xml"]
|
|
53
53
|
```
|
|
54
54
|
|
|
55
55
|
## Usage
|
|
@@ -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
|
|
@@ -213,6 +226,10 @@ my-site/
|
|
|
213
226
|
|
|
214
227
|
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.
|
|
215
228
|
|
|
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.
|
|
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
|
+
|
|
216
233
|
The source directory must not overlap the destination directory, the selected theme directory, or the internal `.zeropress/` working directory.
|
|
217
234
|
|
|
218
235
|
Ignored while staging and Markdown discovery:
|
|
@@ -252,8 +269,16 @@ title: Install ZeroPress
|
|
|
252
269
|
description: Build a static docs site from Markdown.
|
|
253
270
|
path: guides/install
|
|
254
271
|
status: published
|
|
272
|
+
discoverability: default
|
|
255
273
|
meta:
|
|
256
274
|
source: docs
|
|
275
|
+
data:
|
|
276
|
+
stack:
|
|
277
|
+
- ZeroPress
|
|
278
|
+
- Cloudflare
|
|
279
|
+
facts:
|
|
280
|
+
- label: Role
|
|
281
|
+
value: Documentation
|
|
257
282
|
---
|
|
258
283
|
|
|
259
284
|
Body content...
|
|
@@ -269,10 +294,31 @@ Supported front matter fields:
|
|
|
269
294
|
| `description` | Page excerpt and description. |
|
|
270
295
|
| `path` | Generated route path, such as `guides/install` for `/guides/install`. |
|
|
271
296
|
| `status` | `published` includes the page. `draft` skips the page. Other values warn and skip. |
|
|
297
|
+
| `discoverability` | `default`, `noindex`, or `delist`. Missing is `default`. |
|
|
272
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. |
|
|
273
300
|
|
|
274
301
|
Unknown front matter fields are ignored to make migration from existing Markdown sites easier.
|
|
275
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
|
+
|
|
276
322
|
## Config
|
|
277
323
|
|
|
278
324
|
Build Pages reads `<source>/.zeropress/config.json` when present. Missing config falls back to defaults.
|
|
@@ -287,11 +333,11 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
|
|
|
287
333
|
"title": "My Docs",
|
|
288
334
|
"description": "Project documentation",
|
|
289
335
|
"url": "https://example.github.io/project",
|
|
336
|
+
"expose_generator": true,
|
|
337
|
+
"indexing": true,
|
|
290
338
|
"footer": {
|
|
291
339
|
"copyright_text": "Copyright 2026 Example Corp.",
|
|
292
|
-
"attribution":
|
|
293
|
-
"enabled": true
|
|
294
|
-
}
|
|
340
|
+
"attribution": true
|
|
295
341
|
}
|
|
296
342
|
},
|
|
297
343
|
"front_page": {
|
|
@@ -302,7 +348,14 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
|
|
|
302
348
|
"name": "Primary Menu",
|
|
303
349
|
"items": [
|
|
304
350
|
{ "title": "Home", "url": "/" },
|
|
305
|
-
{
|
|
351
|
+
{
|
|
352
|
+
"title": "Guide",
|
|
353
|
+
"url": "/guide",
|
|
354
|
+
"meta": {
|
|
355
|
+
"icon": "book-open",
|
|
356
|
+
"badge": "New"
|
|
357
|
+
}
|
|
358
|
+
}
|
|
306
359
|
]
|
|
307
360
|
}
|
|
308
361
|
},
|
|
@@ -322,17 +375,23 @@ See the public config reference at [zeropress.dev/build-pages-config](https://ze
|
|
|
322
375
|
|
|
323
376
|
HTML front page and `custom_html` files must stay inside `.zeropress/`.
|
|
324
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
|
+
|
|
325
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.
|
|
326
381
|
|
|
327
|
-
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.
|
|
385
|
+
|
|
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.
|
|
328
387
|
|
|
329
388
|
Schemas:
|
|
330
389
|
|
|
331
390
|
- [ZeroPress Build Pages Config v0.1](https://zeropress.dev/schemas/zeropress-build-pages.config.v0.1.schema.json)
|
|
332
391
|
|
|
333
|
-
## Internal `.zeropress/` Files
|
|
392
|
+
## Workspace Internal `.zeropress/` Files
|
|
334
393
|
|
|
335
|
-
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.
|
|
336
395
|
|
|
337
396
|
```txt
|
|
338
397
|
.zeropress/
|
|
@@ -352,7 +411,7 @@ Build Pages writes internal working files to `.zeropress/` in the current workin
|
|
|
352
411
|
|
|
353
412
|
## Destination Output
|
|
354
413
|
|
|
355
|
-
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.
|
|
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`.
|
|
356
415
|
|
|
357
416
|
## Demo
|
|
358
417
|
|