@nera-static/core 4.9.1 → 4.9.3
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 +80 -155
- package/package.json +9 -3
- package/src/watch-assets.js +0 -29
package/README.md
CHANGED
|
@@ -1,231 +1,156 @@
|
|
|
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
6
|
|
|
7
7
|
> ⚠️ This project is under active development. Breaking changes may occur.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## 👉 Building a website? You probably don't want this package
|
|
12
|
+
|
|
13
|
+
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
14
|
|
|
13
15
|
```bash
|
|
14
|
-
npm install -g @nera-static/
|
|
16
|
+
npm install -g @nera-static/nera
|
|
15
17
|
|
|
16
|
-
# Create a new project
|
|
17
18
|
nera new my-nera-site
|
|
18
|
-
|
|
19
19
|
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
|
|
20
|
+
nera dev # build + live-reload dev server
|
|
21
|
+
nera build # render pages/ → public/
|
|
32
22
|
```
|
|
33
23
|
|
|
34
|
-
|
|
24
|
+
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
25
|
|
|
36
|
-
|
|
26
|
+
Install `@nera-static/core` directly only if you are **embedding the engine** — a custom build script, a hosted platform, or your own tooling:
|
|
37
27
|
|
|
38
28
|
```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
|
|
29
|
+
npm install @nera-static/core
|
|
54
30
|
```
|
|
55
31
|
|
|
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
32
|
---
|
|
64
33
|
|
|
65
|
-
##
|
|
34
|
+
## 🧱 What the engine does
|
|
66
35
|
|
|
67
|
-
|
|
36
|
+
`run()` executes a fixed **four-stage pipeline** against the current working directory:
|
|
68
37
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
---
|
|
74
|
-
# Welcome to Nera
|
|
38
|
+
1. **`loadAppData`** — parse `config/app.yaml` into `app`; resolve the presentation folders (and the `theme/` probe) and list `pages/` recursively.
|
|
39
|
+
2. **`getPagesData`** — render each Markdown file with markdown-it, extract frontmatter, and derive `meta.href`/`dirname`/`filename`/`createdAt`. Returns `[{ content, meta }]`.
|
|
40
|
+
3. **`getPluginsData`** — load and apply plugins (see the plugin contract below), threading their `app`/`pagesData` results.
|
|
41
|
+
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
42
|
|
|
76
|
-
|
|
77
|
-
```
|
|
43
|
+
Two things that are easy to miss:
|
|
78
44
|
|
|
79
|
-
|
|
45
|
+
- A page is only rendered if its frontmatter defines `layout`. Pages without it are silently skipped.
|
|
46
|
+
- `public/` is deleted on every render, so nothing may be authored there by hand.
|
|
80
47
|
|
|
81
48
|
---
|
|
82
49
|
|
|
83
|
-
##
|
|
84
|
-
|
|
85
|
-
Nera uses [Pug](https://pugjs.org/) for layout rendering. You have access to:
|
|
50
|
+
## 📦 Public API
|
|
86
51
|
|
|
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
|
|
52
|
+
The package is ESM (`"type": "module"`), requires **Node ≥ 20**, and exposes a barrel at the root plus per-module subpath exports.
|
|
93
53
|
|
|
94
|
-
|
|
54
|
+
```js
|
|
55
|
+
import { run } from '@nera-static/core'
|
|
95
56
|
|
|
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
|
|
57
|
+
// Build the site in process.cwd(): pages/ → public/
|
|
58
|
+
await run()
|
|
105
59
|
```
|
|
106
60
|
|
|
107
|
-
|
|
61
|
+
`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
62
|
|
|
109
|
-
|
|
63
|
+
### Exports
|
|
110
64
|
|
|
111
|
-
|
|
65
|
+
| Export | From | Purpose |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| `run` (also default) | `.` | Run the whole four-stage build against the cwd. |
|
|
68
|
+
| `loadAppData`, `getPagesData`, `computeFolders`, `defaultSettings`, `normalizeBasePath` | `./core` | Pipeline stages 1–2 and the folder/base-path helpers. |
|
|
69
|
+
| `getPluginsData` | (`.` / `setup-plugins`) | Pipeline stage 3 — load and apply plugins. |
|
|
70
|
+
| `makeLayeredResolver`, `resolveEntry`, `defaultResolvePath` | `./resolve` | The layered Pug view resolver (site over theme, per file). |
|
|
71
|
+
| `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." |
|
|
72
|
+
| `resolveTheme`, `checkThemeCompatibility`, `deepMerge` | `./theme` | Theme discovery, `nera.generator`/peer-dependency compatibility checks, config merge. |
|
|
112
73
|
|
|
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
|
-
```
|
|
74
|
+
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
75
|
|
|
122
|
-
|
|
76
|
+
```js
|
|
77
|
+
import { resolveSiteModel } from '@nera-static/core/site-model'
|
|
123
78
|
|
|
124
|
-
|
|
125
|
-
|
|
79
|
+
const model = resolveSiteModel({ cwd: '/path/to/site' })
|
|
80
|
+
// → { folders, theme, roots, appConfigError, themeError, ... } (never throws)
|
|
126
81
|
```
|
|
127
82
|
|
|
128
83
|
---
|
|
129
84
|
|
|
130
|
-
##
|
|
85
|
+
## 🔌 Plugin contract
|
|
131
86
|
|
|
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.
|
|
87
|
+
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
88
|
|
|
138
|
-
|
|
89
|
+
A plugin is an ESM module exporting either or both hooks — no registration, no base class:
|
|
139
90
|
|
|
140
|
-
```
|
|
141
|
-
|
|
91
|
+
```js
|
|
92
|
+
export function getAppData({ app, pagesData }) { /* return a new app object */ }
|
|
93
|
+
export function getMetaData({ app, pagesData }) { /* return a new pagesData array */ }
|
|
142
94
|
```
|
|
143
95
|
|
|
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).
|
|
96
|
+
- `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.
|
|
97
|
+
- Results are threaded: `getMetaData` sees the `app` that `getAppData` returned.
|
|
98
|
+
- Both hooks are awaited (generator ≥ 4.3.0), but keeping them synchronous is the safe default.
|
|
99
|
+
- Config is read from the **user's site** (`config/<name>.yaml` via `getConfig`), not from the plugin package; supply per-key JS fallbacks.
|
|
154
100
|
|
|
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.
|
|
101
|
+
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
102
|
|
|
165
103
|
---
|
|
166
104
|
|
|
167
|
-
##
|
|
105
|
+
## 🎨 Templates and the layered resolver
|
|
168
106
|
|
|
169
|
-
|
|
107
|
+
Rendering uses [Pug](https://pugjs.org/). Templates receive:
|
|
170
108
|
|
|
171
|
-
-
|
|
172
|
-
-
|
|
173
|
-
-
|
|
174
|
-
-
|
|
109
|
+
- `app`: values from `config/app.yaml` (including `app.theme` when a theme is set)
|
|
110
|
+
- `meta`: frontmatter metadata for the current page
|
|
111
|
+
- `t(key)`: translation helper — resolves `app.translations[meta.lang || app.lang][key]`, falling back to the key itself
|
|
112
|
+
- `url(path)`: prefixes a root-absolute path with the site's `base_path` (a no-op when unset)
|
|
175
113
|
|
|
176
|
-
|
|
114
|
+
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
115
|
|
|
178
|
-
|
|
179
|
-
npm install @nera-static/plugin-navigation
|
|
180
|
-
```
|
|
116
|
+
---
|
|
181
117
|
|
|
182
|
-
|
|
118
|
+
## 📁 Deploying to a subdirectory (`base_path`)
|
|
183
119
|
|
|
184
|
-
|
|
120
|
+
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
121
|
|
|
186
|
-
|
|
122
|
+
Set `base_path` in `config/app.yaml`:
|
|
187
123
|
|
|
188
124
|
```yaml
|
|
189
|
-
|
|
190
|
-
- start:
|
|
191
|
-
- plugin-tags
|
|
192
|
-
- end:
|
|
193
|
-
- plugin-search
|
|
125
|
+
base_path: /my-repo
|
|
194
126
|
```
|
|
195
127
|
|
|
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.
|
|
128
|
+
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
129
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
---
|
|
130
|
+
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
131
|
|
|
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/`.
|
|
132
|
+
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
133
|
|
|
215
134
|
---
|
|
216
135
|
|
|
217
|
-
## 🛠
|
|
136
|
+
## 🛠 Developing this engine
|
|
137
|
+
|
|
138
|
+
This repo ships a bundled demo site used to exercise the pipeline during development — the same pipeline the CLI drives via `run()`:
|
|
218
139
|
|
|
219
140
|
```bash
|
|
220
|
-
npm run
|
|
221
|
-
npm run
|
|
222
|
-
npm
|
|
141
|
+
npm run render # build the demo site to /public
|
|
142
|
+
npm run dev # render, then vite + asset watch + rebuild on change
|
|
143
|
+
npm run serve # vite over the built output
|
|
144
|
+
npm test # vitest (WATCH mode) — use `npx vitest run` for a single pass
|
|
145
|
+
npm run lint # eslint .
|
|
223
146
|
```
|
|
224
147
|
|
|
148
|
+
Formatting is enforced by eslint: 4-space indent, no semicolons, single quotes. There is no build step.
|
|
149
|
+
|
|
225
150
|
---
|
|
226
151
|
|
|
227
|
-
## 📚 Further
|
|
152
|
+
## 📚 Further reading
|
|
228
153
|
|
|
154
|
+
- [`@nera-static/nera`](https://github.com/seebaermichi/nera-cli) — the CLI, and the getting-started for building a site
|
|
155
|
+
- [PLUGINS.md](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md) — the plugin catalog
|
|
229
156
|
- [How Nera is used to build its own website](https://medium.com/@micha.becker79/building-nera-website-with-nera-4b50ed5dbff2)
|
|
230
|
-
|
|
231
|
-
---
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nera-static/core",
|
|
3
|
-
"version": "4.9.
|
|
3
|
+
"version": "4.9.3",
|
|
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": {
|
|
@@ -13,7 +13,13 @@
|
|
|
13
13
|
"./package.json": "./package.json"
|
|
14
14
|
},
|
|
15
15
|
"files": [
|
|
16
|
-
"src
|
|
16
|
+
"src/core.js",
|
|
17
|
+
"src/index.js",
|
|
18
|
+
"src/render.js",
|
|
19
|
+
"src/resolve.js",
|
|
20
|
+
"src/setup-plugins.js",
|
|
21
|
+
"src/site-model.js",
|
|
22
|
+
"src/theme.js",
|
|
17
23
|
"index.js"
|
|
18
24
|
],
|
|
19
25
|
"publishConfig": {
|
|
@@ -56,6 +62,7 @@
|
|
|
56
62
|
"homepage": "https://github.com/seebaermichi/nera#readme",
|
|
57
63
|
"dependencies": {
|
|
58
64
|
"cpy": "^13.2.2",
|
|
65
|
+
"dotenv": "^17.2.0",
|
|
59
66
|
"fs-readdir-recursive": "^1.1.0",
|
|
60
67
|
"gray-matter": "^4.0.3",
|
|
61
68
|
"markdown-it": "^14.1.0",
|
|
@@ -69,7 +76,6 @@
|
|
|
69
76
|
"devDependencies": {
|
|
70
77
|
"chokidar": "^5.0.0",
|
|
71
78
|
"concurrently": "^10.0.3",
|
|
72
|
-
"dotenv": "^17.2.0",
|
|
73
79
|
"eslint": "^10.7.0",
|
|
74
80
|
"husky": "^9.1.7",
|
|
75
81
|
"nodemon": "^3.0.3",
|
package/src/watch-assets.js
DELETED
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
import chokidar from 'chokidar'
|
|
2
|
-
import fs from 'fs'
|
|
3
|
-
import { copyFolder } from './render.js'
|
|
4
|
-
import path from 'path'
|
|
5
|
-
import dotenv from 'dotenv'
|
|
6
|
-
|
|
7
|
-
dotenv.config()
|
|
8
|
-
|
|
9
|
-
// Mirror the presentation probe in core.js (ROADMAP-themes.md §1b): a site's own
|
|
10
|
-
// assets live under theme/ in the revised layout, falling back to the legacy
|
|
11
|
-
// root assets/ so an unmigrated site still watches the right folder.
|
|
12
|
-
const sourceFolder = fs.existsSync('theme')
|
|
13
|
-
? path.resolve('theme/assets')
|
|
14
|
-
: path.resolve('assets')
|
|
15
|
-
const distFolder = path.resolve('public')
|
|
16
|
-
|
|
17
|
-
// Read the site's .neraignore from the site root ('.'), matching the render
|
|
18
|
-
// pipeline — it stays there even though assets now live under theme/assets.
|
|
19
|
-
const initialCopy = () => copyFolder(sourceFolder, distFolder, '.')
|
|
20
|
-
|
|
21
|
-
// Initial copy
|
|
22
|
-
await initialCopy()
|
|
23
|
-
|
|
24
|
-
chokidar
|
|
25
|
-
.watch(sourceFolder, { ignoreInitial: true })
|
|
26
|
-
.on('all', async (event, filePath) => {
|
|
27
|
-
console.log(`[watch-assets] ${event} → ${filePath}`)
|
|
28
|
-
await initialCopy()
|
|
29
|
-
})
|