@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.
Files changed (2) hide show
  1. package/README.md +83 -156
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,231 +1,158 @@
1
- # Nera – a lightweight static site generator
1
+ # @nera-static/core – the Nera engine
2
2
 
3
3
  [![Test](https://github.com/seebaermichi/nera/actions/workflows/test.yml/badge.svg)](https://github.com/seebaermichi/nera/actions/workflows/test.yml)
4
4
 
5
- **Nera** is a minimal static site generator that transforms Markdown content into fast, clean HTML pages using [Pug](https://pugjs.org/) templates. It is designed to be simple to use, yet extendable with plugins.
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
- ## 🚀 Getting Started
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/installer
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
- npm run dev # Start dev server with live reload
21
- npm run render # Render the static site to /public
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
- ## 🗂️ Directory Structure
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
- my-nera-site/
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
- ## 📄 Page Content (`pages/`)
36
+ ## 🧱 What the engine does
66
37
 
67
- Each Markdown file must define frontmatter metadata, e.g.:
38
+ `run()` executes a fixed **four-stage pipeline** against the current working directory:
68
39
 
69
- ```markdown
70
- ---
71
- layout: pages/default.pug
72
- title: Homepage
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
- This content will be injected into the layout file defined above.
77
- ```
45
+ Two things that are easy to miss:
78
46
 
79
- > All frontmatter values are accessible as the `meta` object in your Pug templates.
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
- ## 🎨 Templates (`theme/views/`)
84
-
85
- Nera uses [Pug](https://pugjs.org/) for layout rendering. You have access to:
52
+ ## 📦 Public API
86
53
 
87
- - `app`: values from `config/app.yaml`
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
- Example:
56
+ ```js
57
+ import { run } from '@nera-static/core'
95
58
 
96
- ```pug
97
- doctype html
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
- ## 🌍 Translations
65
+ ### Exports
110
66
 
111
- You can define translations in `config/app.yaml`:
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
- ```yaml
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
- Use the `t` function in templates:
78
+ ```js
79
+ import { resolveSiteModel } from '@nera-static/core/site-model'
123
80
 
124
- ```pug
125
- meta(name="description", content=t('app_description'))
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
- ## 📁 Deploying to a subdirectory (`base_path`)
87
+ ## 🔌 Plugin contract
131
88
 
132
- By default Nera writes root-absolute URLs (`/css/main.css`, `/about.html`), which
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
- Set `base_path` in `config/app.yaml` to the subdirectory:
91
+ A plugin is an ESM module exporting either or both hooks — no registration, no base class:
139
92
 
140
- ```yaml
141
- base_path: /my-repo
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
- Nera then prefixes every root-absolute URL in the built output with it — links,
145
- `<script>`/`<link>`/`<img>` sources, `srcset`, CSS `url(…)`, the web app
146
- manifest, and `href`/`url` values in JSON assets such as the search index. The
147
- physical output layout is unchanged (files still land at the artifact root, which
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
- For **absolute** URLs you build yourself (canonical/OpenGraph tags, a sitemap),
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
- ## 🔌 Plugins
107
+ ## 🎨 Templates and the layered resolver
168
108
 
169
- Nera supports plugins that can:
109
+ Rendering uses [Pug](https://pugjs.org/). Templates receive:
170
110
 
171
- - Add data to the app or individual pages
172
- - Modify metadata
173
- - Inject routes or components
174
- - Extend rendering logic
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
- You can place local plugins in `src/plugins/` or install official ones via npm:
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
- ```bash
179
- npm install @nera-static/plugin-navigation
180
- ```
118
+ ---
181
119
 
182
- For a complete list of existing plugins, see [PLUGINS.md](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md).
120
+ ## 📁 Deploying to a subdirectory (`base_path`)
183
121
 
184
- ### ⚙️ Plugin Execution Order
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
- To control the **execution order** of plugins, you can define a `config/plugin-order.yaml` file like this:
124
+ Set `base_path` in `config/app.yaml`:
187
125
 
188
126
  ```yaml
189
- plugin-order:
190
- - start:
191
- - plugin-tags
192
- - end:
193
- - plugin-search
127
+ base_path: /my-repo
194
128
  ```
195
129
 
196
- - `start`: plugins listed here will run first (in the order listed).
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
- This is especially useful when some plugins (like `plugin-search`) rely on metadata added by earlier ones.
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
- ## 📁 Asset Handling
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
- ## 🛠 Development Scripts
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 dev # Starts local development server
221
- npm run render # Renders pages to /public
222
- npm start # Shortcut for dev mode
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
- ## 📚 Further Reading
152
+ ---
228
153
 
229
- - [How Nera is used to build its own website](https://medium.com/@micha.becker79/building-nera-website-with-nera-4b50ed5dbff2)
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.9.2",
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": "^14.1.0",
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",