@nera-static/core 4.9.2 → 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.
Files changed (2) hide show
  1. package/README.md +80 -155
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,231 +1,156 @@
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
6
 
7
7
  > ⚠️ This project is under active development. Breaking changes may occur.
8
8
 
9
9
  ---
10
10
 
11
- ## 🚀 Getting Started
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/installer
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
- 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
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
- ## 🗂️ Directory Structure
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
- 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
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
- ## 📄 Page Content (`pages/`)
34
+ ## 🧱 What the engine does
66
35
 
67
- Each Markdown file must define frontmatter metadata, e.g.:
36
+ `run()` executes a fixed **four-stage pipeline** against the current working directory:
68
37
 
69
- ```markdown
70
- ---
71
- layout: pages/default.pug
72
- title: Homepage
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
- This content will be injected into the layout file defined above.
77
- ```
43
+ Two things that are easy to miss:
78
44
 
79
- > All frontmatter values are accessible as the `meta` object in your Pug templates.
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
- ## 🎨 Templates (`theme/views/`)
84
-
85
- Nera uses [Pug](https://pugjs.org/) for layout rendering. You have access to:
50
+ ## 📦 Public API
86
51
 
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
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
- Example:
54
+ ```js
55
+ import { run } from '@nera-static/core'
95
56
 
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
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
- ## 🌍 Translations
63
+ ### Exports
110
64
 
111
- You can define translations in `config/app.yaml`:
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
- ```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
- ```
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
- Use the `t` function in templates:
76
+ ```js
77
+ import { resolveSiteModel } from '@nera-static/core/site-model'
123
78
 
124
- ```pug
125
- meta(name="description", content=t('app_description'))
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
- ## 📁 Deploying to a subdirectory (`base_path`)
85
+ ## 🔌 Plugin contract
131
86
 
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.
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
- Set `base_path` in `config/app.yaml` to the subdirectory:
89
+ A plugin is an ESM module exporting either or both hooks — no registration, no base class:
139
90
 
140
- ```yaml
141
- base_path: /my-repo
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
- 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).
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
- 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.
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
- ## 🔌 Plugins
105
+ ## 🎨 Templates and the layered resolver
168
106
 
169
- Nera supports plugins that can:
107
+ Rendering uses [Pug](https://pugjs.org/). Templates receive:
170
108
 
171
- - Add data to the app or individual pages
172
- - Modify metadata
173
- - Inject routes or components
174
- - Extend rendering logic
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
- You can place local plugins in `src/plugins/` or install official ones via npm:
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
- ```bash
179
- npm install @nera-static/plugin-navigation
180
- ```
116
+ ---
181
117
 
182
- For a complete list of existing plugins, see [PLUGINS.md](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md).
118
+ ## 📁 Deploying to a subdirectory (`base_path`)
183
119
 
184
- ### ⚙️ Plugin Execution Order
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
- To control the **execution order** of plugins, you can define a `config/plugin-order.yaml` file like this:
122
+ Set `base_path` in `config/app.yaml`:
187
123
 
188
124
  ```yaml
189
- plugin-order:
190
- - start:
191
- - plugin-tags
192
- - end:
193
- - plugin-search
125
+ base_path: /my-repo
194
126
  ```
195
127
 
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.
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
- This is especially useful when some plugins (like `plugin-search`) rely on metadata added by earlier ones.
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
- ## 📁 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/`.
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
- ## 🛠 Development Scripts
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 dev # Starts local development server
221
- npm run render # Renders pages to /public
222
- npm start # Shortcut for dev mode
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 Reading
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.2",
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": {