@nera-static/core 4.9.2 → 4.10.0
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 +83 -156
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,231 +1,158 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @nera-static/core – the Nera engine
|
|
2
2
|
|
|
3
3
|
[](https://github.com/seebaermichi/nera/actions/workflows/test.yml)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**`@nera-static/core`** is the engine behind [Nera](https://github.com/seebaermichi/nera-cli): the four-stage build pipeline that turns Markdown + [Pug](https://pugjs.org/) into static HTML, plus the layered theme/view resolver. It is an **importable library**, consumed by the [`@nera-static/nera`](https://www.npmjs.com/package/@nera-static/nera) CLI, by [`@nera-static/validate`](https://www.npmjs.com/package/@nera-static/validate), and by other tooling.
|
|
6
|
+
|
|
7
|
+
📖 **Documentation:** [nera.js.org](https://nera.js.org)
|
|
6
8
|
|
|
7
9
|
> ⚠️ This project is under active development. Breaking changes may occur.
|
|
8
10
|
|
|
9
11
|
---
|
|
10
12
|
|
|
11
|
-
##
|
|
13
|
+
## 👉 Building a website? You probably don't want this package
|
|
14
|
+
|
|
15
|
+
If you want to **create and build a site**, install the CLI, not the engine — it brings `@nera-static/core` and `@nera-static/validate` transitively:
|
|
12
16
|
|
|
13
17
|
```bash
|
|
14
|
-
npm install -g @nera-static/
|
|
18
|
+
npm install -g @nera-static/nera
|
|
15
19
|
|
|
16
|
-
# Create a new project
|
|
17
20
|
nera new my-nera-site
|
|
18
|
-
|
|
19
21
|
cd my-nera-site
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Alternatively, clone manually:
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
git clone git@github.com:seebaermichi/nera.git
|
|
28
|
-
cd nera
|
|
29
|
-
rm -fr .git
|
|
30
|
-
npm install
|
|
31
|
-
npm run dev
|
|
22
|
+
nera dev # build + live-reload dev server
|
|
23
|
+
nera build # render pages/ → public/
|
|
32
24
|
```
|
|
33
25
|
|
|
34
|
-
|
|
26
|
+
A site is a **thin project** — a `package.json` whose only Nera dependency is `@nera-static/nera`, plus `config/`, `pages/`, and a `theme/`. It is not a clone of this repo. See the [CLI README](https://github.com/seebaermichi/nera-cli) for the full site workflow (content, translations, deployment).
|
|
35
27
|
|
|
36
|
-
|
|
28
|
+
Install `@nera-static/core` directly only if you are **embedding the engine** — a custom build script, a hosted platform, or your own tooling:
|
|
37
29
|
|
|
38
30
|
```bash
|
|
39
|
-
|
|
40
|
-
├── config/
|
|
41
|
-
│ └── app.yaml # Global site config (name, lang, translations, etc.)
|
|
42
|
-
├── pages/ # Markdown content with frontmatter metadata
|
|
43
|
-
├── public/ # Rendered static site output
|
|
44
|
-
├── src/
|
|
45
|
-
│ ├── plugins/ # Local plugins (optional)
|
|
46
|
-
│ ├── core.js
|
|
47
|
-
│ ├── index.js
|
|
48
|
-
│ ├── render.js
|
|
49
|
-
│ └── setup-plugins.js
|
|
50
|
-
├── theme/ # Your site's presentation (layered over an installed theme)
|
|
51
|
-
│ ├── assets/ # CSS, JS, images, fonts – copied to /public
|
|
52
|
-
│ └── views/ # Pug templates (layouts and partials)
|
|
53
|
-
└── .neraignore # List of asset files or folders to ignore during render
|
|
31
|
+
npm install @nera-static/core
|
|
54
32
|
```
|
|
55
33
|
|
|
56
|
-
> **Presentation lives under `theme/`.** Your site's `theme/views/` and
|
|
57
|
-
> `theme/assets/` are yours to edit; if you also set `theme: <name>` in
|
|
58
|
-
> `config/app.yaml`, an installed theme package is layered *under* them and your
|
|
59
|
-
> files override it per file. Sites created before this layout keep their
|
|
60
|
-
> `views/`/`assets/` at the project root — that still works (with a deprecation
|
|
61
|
-
> warning), but move them to `theme/views/` and `theme/assets/` when you can.
|
|
62
|
-
|
|
63
34
|
---
|
|
64
35
|
|
|
65
|
-
##
|
|
36
|
+
## 🧱 What the engine does
|
|
66
37
|
|
|
67
|
-
|
|
38
|
+
`run()` executes a fixed **four-stage pipeline** against the current working directory:
|
|
68
39
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
---
|
|
74
|
-
# Welcome to Nera
|
|
40
|
+
1. **`loadAppData`** — parse `config/app.yaml` into `app`; resolve the presentation folders (and the `theme/` probe) and list `pages/` recursively.
|
|
41
|
+
2. **`getPagesData`** — render each Markdown file with markdown-it, extract frontmatter, and derive `meta.href`/`dirname`/`filename`/`createdAt`. Returns `[{ content, meta }]`.
|
|
42
|
+
3. **`getPluginsData`** — load and apply plugins (see the plugin contract below), threading their `app`/`pagesData` results.
|
|
43
|
+
4. **render** — delete `public/`, write the HTML files (layering theme views under the site's), copy assets (theme first, site second), and rewrite root-absolute URLs for `base_path` deploys.
|
|
75
44
|
|
|
76
|
-
|
|
77
|
-
```
|
|
45
|
+
Two things that are easy to miss:
|
|
78
46
|
|
|
79
|
-
|
|
47
|
+
- A page is only rendered if its frontmatter defines `layout`. Pages without it are silently skipped.
|
|
48
|
+
- `public/` is deleted on every render, so nothing may be authored there by hand.
|
|
80
49
|
|
|
81
50
|
---
|
|
82
51
|
|
|
83
|
-
##
|
|
84
|
-
|
|
85
|
-
Nera uses [Pug](https://pugjs.org/) for layout rendering. You have access to:
|
|
52
|
+
## 📦 Public API
|
|
86
53
|
|
|
87
|
-
|
|
88
|
-
- `meta`: metadata from the current markdown page
|
|
89
|
-
- `t(key)`: translation function
|
|
90
|
-
- `url(path)`: prefixes a root-absolute path with the site's `base_path` (see
|
|
91
|
-
[Deploying to a subdirectory](#-deploying-to-a-subdirectory-base_path)); a
|
|
92
|
-
no-op when `base_path` is unset
|
|
54
|
+
The package is ESM (`"type": "module"`), requires **Node ≥ 20**, and exposes a barrel at the root plus per-module subpath exports.
|
|
93
55
|
|
|
94
|
-
|
|
56
|
+
```js
|
|
57
|
+
import { run } from '@nera-static/core'
|
|
95
58
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
html(lang=app.lang)
|
|
99
|
-
head
|
|
100
|
-
title= meta.title
|
|
101
|
-
meta(name="description", content=meta.description || t('app_description'))
|
|
102
|
-
body
|
|
103
|
-
h1= meta.title
|
|
104
|
-
!= content
|
|
59
|
+
// Build the site in process.cwd(): pages/ → public/
|
|
60
|
+
await run()
|
|
105
61
|
```
|
|
106
62
|
|
|
107
|
-
|
|
63
|
+
`run(settings?)` accepts an optional `settings` object (defaults to `defaultSettings`); its `folders` block is normally taken from the site's `config/app.yaml`, not passed here.
|
|
108
64
|
|
|
109
|
-
|
|
65
|
+
### Exports
|
|
110
66
|
|
|
111
|
-
|
|
67
|
+
| Export | From | Purpose |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| `run` (also default) | `.` | Run the whole four-stage build against the cwd. |
|
|
70
|
+
| `loadAppData`, `getPagesData`, `computeFolders`, `defaultSettings`, `normalizeBasePath` | `./core` | Pipeline stages 1–2 and the folder/base-path helpers. |
|
|
71
|
+
| `getPluginsData` | (`.` / `setup-plugins`) | Pipeline stage 3 — load and apply plugins. |
|
|
72
|
+
| `makeLayeredResolver`, `resolveEntry`, `defaultResolvePath` | `./resolve` | The layered Pug view resolver (site over theme, per file). |
|
|
73
|
+
| `resolveSiteModel` | `./site-model` | Read-only: the folders, theme, and resolver `roots` chain for a directory **without building it** — the bridge `@nera-static/validate` and the platform use to agree with the engine on "how this site resolves." |
|
|
74
|
+
| `resolveTheme`, `checkThemeCompatibility`, `deepMerge` | `./theme` | Theme discovery, `nera.generator`/peer-dependency compatibility checks, config merge. |
|
|
112
75
|
|
|
113
|
-
|
|
114
|
-
lang: en
|
|
115
|
-
translations:
|
|
116
|
-
en:
|
|
117
|
-
app_description: Nera is a simple static site generator.
|
|
118
|
-
de:
|
|
119
|
-
app_description: Nera ist ein einfacher Generator für statische Webseiten.
|
|
120
|
-
```
|
|
76
|
+
Subpath exports (`@nera-static/core/resolve`, `/site-model`, `/core`, `/render`, `/theme`) are available for callers that want a single module without pulling in the whole barrel.
|
|
121
77
|
|
|
122
|
-
|
|
78
|
+
```js
|
|
79
|
+
import { resolveSiteModel } from '@nera-static/core/site-model'
|
|
123
80
|
|
|
124
|
-
|
|
125
|
-
|
|
81
|
+
const model = resolveSiteModel({ cwd: '/path/to/site' })
|
|
82
|
+
// → { folders, theme, roots, appConfigError, themeError, ... } (never throws)
|
|
126
83
|
```
|
|
127
84
|
|
|
128
85
|
---
|
|
129
86
|
|
|
130
|
-
##
|
|
87
|
+
## 🔌 Plugin contract
|
|
131
88
|
|
|
132
|
-
|
|
133
|
-
assume the site is served from a domain root. When it is served from a
|
|
134
|
-
**subdirectory** instead — most commonly a GitHub **project** Pages site at
|
|
135
|
-
`https://<user>.github.io/<repo>/` — those URLs resolve against the domain root
|
|
136
|
-
and 404.
|
|
89
|
+
Plugins are discovered from two places: local directories under the configured plugins folder (`folders.plugins`, default `./src/plugins`; a thin site sets `./plugins`), and any dependency in the **site's** `package.json` whose name starts with **`@nera-static/plugin-`** (excluding the `@nera-static/plugin-utils` library).
|
|
137
90
|
|
|
138
|
-
|
|
91
|
+
A plugin is an ESM module exporting either or both hooks — no registration, no base class:
|
|
139
92
|
|
|
140
|
-
```
|
|
141
|
-
|
|
93
|
+
```js
|
|
94
|
+
export function getAppData({ app, pagesData }) { /* return a new app object */ }
|
|
95
|
+
export function getMetaData({ app, pagesData }) { /* return a new pagesData array */ }
|
|
142
96
|
```
|
|
143
97
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
*is* the served subdirectory), and `meta.href` stays in the site's logical
|
|
149
|
-
(un-prefixed) namespace so template URL logic keeps working.
|
|
150
|
-
|
|
151
|
-
It is fully additive: with no `base_path` (or `base_path: ''`) the build is
|
|
152
|
-
byte-identical to before. Remove it when you move the site to a domain root (e.g.
|
|
153
|
-
a custom domain).
|
|
98
|
+
- `getAppData` runs first and must return a **plain object**; `getMetaData` must return an **array**. A wrong return type is discarded with a warning and the build continues.
|
|
99
|
+
- Results are threaded: `getMetaData` sees the `app` that `getAppData` returned.
|
|
100
|
+
- Both hooks are awaited (generator ≥ 4.3.0), but keeping them synchronous is the safe default.
|
|
101
|
+
- Config is read from the **user's site** (`config/<name>.yaml` via `getConfig`), not from the plugin package; supply per-key JS fallbacks.
|
|
154
102
|
|
|
155
|
-
|
|
156
|
-
set the relevant plugin's origin to include the subdirectory, or wrap a hardcoded
|
|
157
|
-
path in the `url()` helper:
|
|
158
|
-
|
|
159
|
-
```pug
|
|
160
|
-
link(rel="preload", as="font", href=url('/fonts/body.woff2'))
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
If the key or language is missing, the key itself is returned as fallback.
|
|
103
|
+
Execution order: names under `start:` in `config/plugin-order.yaml`, then everything else alphabetically, then names under `end:`. For the full catalog see [PLUGINS.md](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md).
|
|
164
104
|
|
|
165
105
|
---
|
|
166
106
|
|
|
167
|
-
##
|
|
107
|
+
## 🎨 Templates and the layered resolver
|
|
168
108
|
|
|
169
|
-
|
|
109
|
+
Rendering uses [Pug](https://pugjs.org/). Templates receive:
|
|
170
110
|
|
|
171
|
-
-
|
|
172
|
-
-
|
|
173
|
-
-
|
|
174
|
-
-
|
|
111
|
+
- `app`: values from `config/app.yaml` (including `app.theme` when a theme is set)
|
|
112
|
+
- `meta`: frontmatter metadata for the current page
|
|
113
|
+
- `t(key)`: translation helper — resolves `app.translations[meta.lang || app.lang][key]`, falling back to the key itself
|
|
114
|
+
- `url(path)`: prefixes a root-absolute path with the site's `base_path` (a no-op when unset)
|
|
175
115
|
|
|
176
|
-
|
|
116
|
+
Views resolve **layered**: a site's `theme/views/<file>` overrides an installed theme package's same-path file, WordPress child-theme style. A themeless site renders exactly as before this layer existed. The design lives in [`ROADMAP-themes.md`](./ROADMAP-themes.md); the consolidation that made this package importable is in [`ROADMAP-core.md`](./ROADMAP-core.md).
|
|
177
117
|
|
|
178
|
-
|
|
179
|
-
npm install @nera-static/plugin-navigation
|
|
180
|
-
```
|
|
118
|
+
---
|
|
181
119
|
|
|
182
|
-
|
|
120
|
+
## 📁 Deploying to a subdirectory (`base_path`)
|
|
183
121
|
|
|
184
|
-
|
|
122
|
+
By default the engine writes root-absolute URLs (`/css/main.css`, `/about.html`), which assume the site is served from a domain root. When it is served from a **subdirectory** instead — most commonly a GitHub **project** Pages site at `https://<user>.github.io/<repo>/` — those URLs 404.
|
|
185
123
|
|
|
186
|
-
|
|
124
|
+
Set `base_path` in `config/app.yaml`:
|
|
187
125
|
|
|
188
126
|
```yaml
|
|
189
|
-
|
|
190
|
-
- start:
|
|
191
|
-
- plugin-tags
|
|
192
|
-
- end:
|
|
193
|
-
- plugin-search
|
|
127
|
+
base_path: /my-repo
|
|
194
128
|
```
|
|
195
129
|
|
|
196
|
-
- `
|
|
197
|
-
- `end`: plugins listed here will run last (in the order listed).
|
|
198
|
-
- Any other plugins not listed will be placed in the middle, sorted alphabetically.
|
|
130
|
+
The engine then prefixes every root-absolute URL in the built output — links, `<script>`/`<link>`/`<img>` sources, `srcset`, CSS `url(…)`, the web app manifest, and `href`/`url` values in JSON assets such as the search index. The physical output layout is unchanged, and `meta.href` stays in the site's logical (un-prefixed) namespace so template URL logic keeps working.
|
|
199
131
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
---
|
|
132
|
+
It is fully additive: with no `base_path` (or `base_path: ''`) the build is byte-identical. Remove it when you move the site to a domain root.
|
|
203
133
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
All files in the `theme/assets/` directory will be copied to `/public` during render. You can exclude files using a `.neraignore` at the project root. Example:
|
|
207
|
-
|
|
208
|
-
```
|
|
209
|
-
ignore.txt
|
|
210
|
-
css/dev-only.css
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
Supports nested paths relative to `theme/assets/`.
|
|
134
|
+
For **absolute** URLs you build yourself (canonical/OpenGraph tags, a sitemap), set the relevant plugin's origin to include the subdirectory, or wrap a hardcoded path in the `url()` helper.
|
|
214
135
|
|
|
215
136
|
---
|
|
216
137
|
|
|
217
|
-
## 🛠
|
|
138
|
+
## 🛠 Developing this engine
|
|
139
|
+
|
|
140
|
+
This repo ships a bundled demo site used to exercise the pipeline during development — the same pipeline the CLI drives via `run()`:
|
|
218
141
|
|
|
219
142
|
```bash
|
|
220
|
-
npm run
|
|
221
|
-
npm run
|
|
222
|
-
npm
|
|
143
|
+
npm run render # build the demo site to /public
|
|
144
|
+
npm run dev # render, then vite + asset watch + rebuild on change
|
|
145
|
+
npm run serve # vite over the built output
|
|
146
|
+
npm test # vitest (WATCH mode) — use `npx vitest run` for a single pass
|
|
147
|
+
npm run lint # eslint .
|
|
223
148
|
```
|
|
224
149
|
|
|
225
|
-
|
|
150
|
+
Formatting is enforced by eslint: 4-space indent, no semicolons, single quotes. There is no build step.
|
|
226
151
|
|
|
227
|
-
|
|
152
|
+
---
|
|
228
153
|
|
|
229
|
-
|
|
154
|
+
## 📚 Further reading
|
|
230
155
|
|
|
231
|
-
|
|
156
|
+
- [nera.js.org](https://nera.js.org) — the official Nera website and documentation
|
|
157
|
+
- [`@nera-static/nera`](https://github.com/seebaermichi/nera-cli) — the CLI, and the getting-started for building a site
|
|
158
|
+
- [PLUGINS.md](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md) — the plugin catalog
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nera-static/core",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.10.0",
|
|
4
4
|
"description": "The Nera static site generator engine — the build pipeline and the layered theme/view resolver, importable by the Nera CLI, @nera-static/validate and tooling",
|
|
5
5
|
"main": "./src/index.js",
|
|
6
6
|
"exports": {
|
|
@@ -65,7 +65,7 @@
|
|
|
65
65
|
"dotenv": "^17.2.0",
|
|
66
66
|
"fs-readdir-recursive": "^1.1.0",
|
|
67
67
|
"gray-matter": "^4.0.3",
|
|
68
|
-
"markdown-it": "^
|
|
68
|
+
"markdown-it": "^15.0.0",
|
|
69
69
|
"markdown-it-meta": "^0.0.1",
|
|
70
70
|
"pretty": "^2.0.0",
|
|
71
71
|
"pug": "^3.0.2",
|