@nera-static/core 4.9.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/LICENSE +21 -0
- package/README.md +231 -0
- package/index.js +3 -0
- package/package.json +83 -0
- package/src/core.js +227 -0
- package/src/index.js +101 -0
- package/src/render.js +299 -0
- package/src/resolve.js +59 -0
- package/src/setup-plugins.js +237 -0
- package/src/site-model.js +64 -0
- package/src/theme.js +268 -0
- package/src/watch-assets.js +29 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) [2025] [Michael Becker]
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# Nera โ a lightweight static site generator
|
|
2
|
+
|
|
3
|
+
[](https://github.com/seebaermichi/nera/actions/workflows/test.yml)
|
|
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.
|
|
6
|
+
|
|
7
|
+
> โ ๏ธ This project is under active development. Breaking changes may occur.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## ๐ Getting Started
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install -g @nera-static/installer
|
|
15
|
+
|
|
16
|
+
# Create a new project
|
|
17
|
+
nera new my-nera-site
|
|
18
|
+
|
|
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
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## ๐๏ธ Directory Structure
|
|
37
|
+
|
|
38
|
+
```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
|
|
54
|
+
```
|
|
55
|
+
|
|
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
|
+
---
|
|
64
|
+
|
|
65
|
+
## ๐ Page Content (`pages/`)
|
|
66
|
+
|
|
67
|
+
Each Markdown file must define frontmatter metadata, e.g.:
|
|
68
|
+
|
|
69
|
+
```markdown
|
|
70
|
+
---
|
|
71
|
+
layout: pages/default.pug
|
|
72
|
+
title: Homepage
|
|
73
|
+
---
|
|
74
|
+
# Welcome to Nera
|
|
75
|
+
|
|
76
|
+
This content will be injected into the layout file defined above.
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
> All frontmatter values are accessible as the `meta` object in your Pug templates.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## ๐จ Templates (`theme/views/`)
|
|
84
|
+
|
|
85
|
+
Nera uses [Pug](https://pugjs.org/) for layout rendering. You have access to:
|
|
86
|
+
|
|
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
|
|
93
|
+
|
|
94
|
+
Example:
|
|
95
|
+
|
|
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
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## ๐ Translations
|
|
110
|
+
|
|
111
|
+
You can define translations in `config/app.yaml`:
|
|
112
|
+
|
|
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
|
+
```
|
|
121
|
+
|
|
122
|
+
Use the `t` function in templates:
|
|
123
|
+
|
|
124
|
+
```pug
|
|
125
|
+
meta(name="description", content=t('app_description'))
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## ๐ Deploying to a subdirectory (`base_path`)
|
|
131
|
+
|
|
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.
|
|
137
|
+
|
|
138
|
+
Set `base_path` in `config/app.yaml` to the subdirectory:
|
|
139
|
+
|
|
140
|
+
```yaml
|
|
141
|
+
base_path: /my-repo
|
|
142
|
+
```
|
|
143
|
+
|
|
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).
|
|
154
|
+
|
|
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.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## ๐ Plugins
|
|
168
|
+
|
|
169
|
+
Nera supports plugins that can:
|
|
170
|
+
|
|
171
|
+
- Add data to the app or individual pages
|
|
172
|
+
- Modify metadata
|
|
173
|
+
- Inject routes or components
|
|
174
|
+
- Extend rendering logic
|
|
175
|
+
|
|
176
|
+
You can place local plugins in `src/plugins/` or install official ones via npm:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
npm install @nera-static/plugin-navigation
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
For a complete list of existing plugins, see [PLUGINS.md](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md).
|
|
183
|
+
|
|
184
|
+
### โ๏ธ Plugin Execution Order
|
|
185
|
+
|
|
186
|
+
To control the **execution order** of plugins, you can define a `config/plugin-order.yaml` file like this:
|
|
187
|
+
|
|
188
|
+
```yaml
|
|
189
|
+
plugin-order:
|
|
190
|
+
- start:
|
|
191
|
+
- plugin-tags
|
|
192
|
+
- end:
|
|
193
|
+
- plugin-search
|
|
194
|
+
```
|
|
195
|
+
|
|
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.
|
|
199
|
+
|
|
200
|
+
This is especially useful when some plugins (like `plugin-search`) rely on metadata added by earlier ones.
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
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/`.
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## ๐ Development Scripts
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
npm run dev # Starts local development server
|
|
221
|
+
npm run render # Renders pages to /public
|
|
222
|
+
npm start # Shortcut for dev mode
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## ๐ Further Reading
|
|
228
|
+
|
|
229
|
+
- [How Nera is used to build its own website](https://medium.com/@micha.becker79/building-nera-website-with-nera-4b50ed5dbff2)
|
|
230
|
+
|
|
231
|
+
---
|
package/index.js
ADDED
package/package.json
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@nera-static/core",
|
|
3
|
+
"version": "4.9.1",
|
|
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
|
+
"main": "./src/index.js",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.js",
|
|
8
|
+
"./core": "./src/core.js",
|
|
9
|
+
"./render": "./src/render.js",
|
|
10
|
+
"./resolve": "./src/resolve.js",
|
|
11
|
+
"./theme": "./src/theme.js",
|
|
12
|
+
"./site-model": "./src/site-model.js",
|
|
13
|
+
"./package.json": "./package.json"
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"src/*.js",
|
|
17
|
+
"index.js"
|
|
18
|
+
],
|
|
19
|
+
"publishConfig": {
|
|
20
|
+
"access": "public"
|
|
21
|
+
},
|
|
22
|
+
"scripts": {
|
|
23
|
+
"start": "nodemon",
|
|
24
|
+
"serve": "vite",
|
|
25
|
+
"lint": "eslint .",
|
|
26
|
+
"render": "node index.js",
|
|
27
|
+
"preserve": "npm run render",
|
|
28
|
+
"watch:assets": "node src/watch-assets.js",
|
|
29
|
+
"test": "vitest",
|
|
30
|
+
"dev": "npm run render && concurrently -k -n 'vite,watch,server' -c blue,magenta,green \"npm:serve\" \"npm:watch:assets\" \"npm:start\"",
|
|
31
|
+
"prepare": "husky"
|
|
32
|
+
},
|
|
33
|
+
"type": "module",
|
|
34
|
+
"keywords": [
|
|
35
|
+
"static-site-generator",
|
|
36
|
+
"markdown",
|
|
37
|
+
"pug",
|
|
38
|
+
"jamstack",
|
|
39
|
+
"blog",
|
|
40
|
+
"documentation",
|
|
41
|
+
"website",
|
|
42
|
+
"ssg"
|
|
43
|
+
],
|
|
44
|
+
"author": "Michael Becker <micha.becker79@gmail.com> (https://github.com/seebaermichi)",
|
|
45
|
+
"license": "MIT",
|
|
46
|
+
"engines": {
|
|
47
|
+
"node": ">=20.0.0"
|
|
48
|
+
},
|
|
49
|
+
"repository": {
|
|
50
|
+
"type": "git",
|
|
51
|
+
"url": "https://github.com/seebaermichi/nera"
|
|
52
|
+
},
|
|
53
|
+
"bugs": {
|
|
54
|
+
"url": "https://github.com/seebaermichi/nera/issues"
|
|
55
|
+
},
|
|
56
|
+
"homepage": "https://github.com/seebaermichi/nera#readme",
|
|
57
|
+
"dependencies": {
|
|
58
|
+
"cpy": "^13.2.2",
|
|
59
|
+
"fs-readdir-recursive": "^1.1.0",
|
|
60
|
+
"gray-matter": "^4.0.3",
|
|
61
|
+
"markdown-it": "^14.1.0",
|
|
62
|
+
"markdown-it-meta": "^0.0.1",
|
|
63
|
+
"pretty": "^2.0.0",
|
|
64
|
+
"pug": "^3.0.2",
|
|
65
|
+
"rimraf": "^6.0.1",
|
|
66
|
+
"semver": "^7.8.5",
|
|
67
|
+
"yaml": "^2.4.1"
|
|
68
|
+
},
|
|
69
|
+
"devDependencies": {
|
|
70
|
+
"chokidar": "^5.0.0",
|
|
71
|
+
"concurrently": "^10.0.3",
|
|
72
|
+
"dotenv": "^17.2.0",
|
|
73
|
+
"eslint": "^10.7.0",
|
|
74
|
+
"husky": "^9.1.7",
|
|
75
|
+
"nodemon": "^3.0.3",
|
|
76
|
+
"npm-run-all": "^4.1.5",
|
|
77
|
+
"vite": "^8.1.5",
|
|
78
|
+
"vitest": "^4.1.10"
|
|
79
|
+
},
|
|
80
|
+
"overrides": {
|
|
81
|
+
"shell-quote": "^1.9.0"
|
|
82
|
+
}
|
|
83
|
+
}
|
package/src/core.js
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
import fs from 'fs'
|
|
2
|
+
import path from 'path'
|
|
3
|
+
import fsReaddirRecursive from 'fs-readdir-recursive'
|
|
4
|
+
import meta from 'markdown-it-meta'
|
|
5
|
+
import MarkdownIt from 'markdown-it'
|
|
6
|
+
import yaml from 'yaml'
|
|
7
|
+
|
|
8
|
+
const md = new MarkdownIt({ html: true }).use(meta)
|
|
9
|
+
|
|
10
|
+
// Normalise a site's `base_path` (config/app.yaml) into a URL prefix.
|
|
11
|
+
// Absent/blank/`/` โ '' so a root-served site is untouched and renders
|
|
12
|
+
// byte-identically. Otherwise: trim, drop trailing slashes, guarantee one
|
|
13
|
+
// leading slash. `nera-website` โ `/nera-website`; `/foo/bar/` โ `/foo/bar`.
|
|
14
|
+
// This is the prefix a subdirectory deploy (e.g. GitHub *project* Pages served
|
|
15
|
+
// under `/<repo>/`) needs so that every root-absolute link and asset resolves.
|
|
16
|
+
export const normalizeBasePath = (raw) => {
|
|
17
|
+
if (typeof raw !== 'string') return ''
|
|
18
|
+
const trimmed = raw.trim()
|
|
19
|
+
if (trimmed === '' || trimmed === '/') return ''
|
|
20
|
+
const noTrailing = trimmed.replace(/\/+$/, '')
|
|
21
|
+
return noTrailing.startsWith('/') ? noTrailing : `/${noTrailing}`
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export const defaultSettings = {
|
|
25
|
+
folders: {
|
|
26
|
+
assets: './assets',
|
|
27
|
+
config: './config',
|
|
28
|
+
pages: './pages',
|
|
29
|
+
dist: './public',
|
|
30
|
+
views: './views',
|
|
31
|
+
plugins: './src/plugins',
|
|
32
|
+
},
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
// Resolve a site's presentation folders โ the `folders` block from app.yaml
|
|
36
|
+
// merged over the defaults, then the `theme/` probe (ROADMAP-themes.md ยง1b):
|
|
37
|
+
// when `<cwd>/theme/` exists and views/assets are still the untouched defaults,
|
|
38
|
+
// point them at `./theme/views`/`./theme/assets`. `config` can only come from
|
|
39
|
+
// `settings` (app.yaml is found through it), so it is never overridden here.
|
|
40
|
+
//
|
|
41
|
+
// cwd-aware and side-effect-free by default, so a caller outside the site
|
|
42
|
+
// directory โ `@nera-static/validate`, the platform's Node service โ gets the
|
|
43
|
+
// exact same folders the build uses (see resolveSiteModel). Pass `warn: true`
|
|
44
|
+
// to emit the one-time legacy-root deprecation notice; loadAppData does, a
|
|
45
|
+
// read-only caller does not.
|
|
46
|
+
export const computeFolders = (
|
|
47
|
+
appConfig = {},
|
|
48
|
+
{ settings = defaultSettings, cwd = process.cwd(), warn = false } = {}
|
|
49
|
+
) => {
|
|
50
|
+
const baseFolders = settings?.folders || defaultSettings.folders
|
|
51
|
+
const folders = {
|
|
52
|
+
...baseFolders,
|
|
53
|
+
...(appConfig.folders || {}),
|
|
54
|
+
config: baseFolders.config,
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const themeFolderExists = fs.existsSync(path.join(cwd, 'theme'))
|
|
58
|
+
const usesDefault = (key) =>
|
|
59
|
+
folders[key] === defaultSettings.folders[key] &&
|
|
60
|
+
appConfig.folders?.[key] === undefined
|
|
61
|
+
|
|
62
|
+
if (themeFolderExists) {
|
|
63
|
+
if (usesDefault('views')) folders.views = './theme/views'
|
|
64
|
+
if (usesDefault('assets')) folders.assets = './theme/assets'
|
|
65
|
+
} else if (warn && usesDefault('views')) {
|
|
66
|
+
console.warn(
|
|
67
|
+
'โ ๏ธ Nera: rendering from the legacy root `views/`/`assets/` is ' +
|
|
68
|
+
'deprecated โ move your presentation to `theme/views/` and ' +
|
|
69
|
+
'`theme/assets/` (see ROADMAP-themes.md ยง1b).'
|
|
70
|
+
)
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
return folders
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export const loadAppData = (settings = defaultSettings) => {
|
|
77
|
+
let appConfig = {}
|
|
78
|
+
let pages = []
|
|
79
|
+
|
|
80
|
+
// Load app.yaml with better error handling
|
|
81
|
+
const appConfigPath = path.join(settings.folders.config, 'app.yaml')
|
|
82
|
+
try {
|
|
83
|
+
if (fs.existsSync(appConfigPath)) {
|
|
84
|
+
const configContent = fs.readFileSync(appConfigPath, 'utf-8')
|
|
85
|
+
appConfig = yaml.parse(configContent) || {}
|
|
86
|
+
console.log('โ
App configuration loaded successfully')
|
|
87
|
+
} else {
|
|
88
|
+
console.warn('โ ๏ธ No app.yaml found, using empty configuration')
|
|
89
|
+
}
|
|
90
|
+
} catch (err) {
|
|
91
|
+
console.error('โ Failed to load app.yaml:', err.message)
|
|
92
|
+
console.warn('โ ๏ธ Using empty configuration as fallback')
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
// Resolve the folders once, here, so every later stage reads the same
|
|
96
|
+
// answer โ the `folders` merge plus the `theme/` probe, both now owned by
|
|
97
|
+
// computeFolders so a read-only caller (the validator, the platform) gets
|
|
98
|
+
// an identical answer. `warn: true` emits the legacy-root deprecation notice
|
|
99
|
+
// once per build (loadAppData is called once).
|
|
100
|
+
const folders = computeFolders(appConfig, { settings, warn: true })
|
|
101
|
+
|
|
102
|
+
appConfig = { ...appConfig, folders }
|
|
103
|
+
|
|
104
|
+
// The site's URL prefix for subdirectory deploys, exposed to templates and
|
|
105
|
+
// plugins as `app.basePath` and used by getPagesData/render to prefix
|
|
106
|
+
// root-absolute URLs. '' for a root-served site (the default) โ no-op.
|
|
107
|
+
appConfig.basePath = normalizeBasePath(appConfig.base_path)
|
|
108
|
+
|
|
109
|
+
// Load pages directory with error handling
|
|
110
|
+
try {
|
|
111
|
+
if (fs.existsSync(appConfig.folders.pages)) {
|
|
112
|
+
pages = fsReaddirRecursive(appConfig.folders.pages)
|
|
113
|
+
console.log(`โ
Found ${pages.length} page(s) to process`)
|
|
114
|
+
} else {
|
|
115
|
+
console.warn(
|
|
116
|
+
`โ ๏ธ Pages directory not found: ${appConfig.folders.pages}`
|
|
117
|
+
)
|
|
118
|
+
}
|
|
119
|
+
} catch (err) {
|
|
120
|
+
console.error('โ Failed to read pages directory:', err.message)
|
|
121
|
+
console.warn('โ ๏ธ No pages will be processed')
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
return {
|
|
125
|
+
app: appConfig,
|
|
126
|
+
content: null,
|
|
127
|
+
meta: null,
|
|
128
|
+
pages,
|
|
129
|
+
plugins: [],
|
|
130
|
+
pagesData: [],
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
export const getPagesData = (
|
|
135
|
+
pages,
|
|
136
|
+
baseDir = defaultSettings.folders.pages
|
|
137
|
+
) => {
|
|
138
|
+
const results = []
|
|
139
|
+
let successCount = 0
|
|
140
|
+
let errorCount = 0
|
|
141
|
+
|
|
142
|
+
pages.forEach((page) => {
|
|
143
|
+
const fullPath = path.join(baseDir, page)
|
|
144
|
+
|
|
145
|
+
try {
|
|
146
|
+
// Check if file exists and is readable
|
|
147
|
+
if (!fs.existsSync(fullPath)) {
|
|
148
|
+
console.warn(`โ ๏ธ Page file not found: ${fullPath}`)
|
|
149
|
+
errorCount++
|
|
150
|
+
return
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
// Read and parse markdown
|
|
154
|
+
const fileContent = fs.readFileSync(fullPath, 'utf-8')
|
|
155
|
+
const content = md.render(fileContent)
|
|
156
|
+
|
|
157
|
+
// Resolve the creation date. Prefer an author/platform-supplied
|
|
158
|
+
// date from frontmatter โ `createdAt`, else `date` โ because the
|
|
159
|
+
// filesystem `birthtime` fallback is unreliable under CI: a fresh
|
|
160
|
+
// clone/checkout stamps every file with the same birthtime, which
|
|
161
|
+
// silently breaks anything that orders or displays by date
|
|
162
|
+
// (pagination, tag overviews, page lists, printed dates). Only when
|
|
163
|
+
// frontmatter carries neither key do we fall back to `birthtime`,
|
|
164
|
+
// which keeps a purely-local build byte-identical to before.
|
|
165
|
+
// See nera-platform R1 (plans/01) and ROADMAP notes.
|
|
166
|
+
let createdAt = md.meta.createdAt || md.meta.date
|
|
167
|
+
if (!createdAt) {
|
|
168
|
+
try {
|
|
169
|
+
createdAt = fs.statSync(fullPath).birthtime
|
|
170
|
+
} catch (statErr) {
|
|
171
|
+
console.warn(
|
|
172
|
+
`โ ๏ธ Could not get file stats for ${fullPath}:`,
|
|
173
|
+
statErr.message
|
|
174
|
+
)
|
|
175
|
+
createdAt = new Date() // Fallback to current date
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
// Single source of truth for the output path: separators are
|
|
180
|
+
// normalised to `/` so URLs are identical on every platform, and
|
|
181
|
+
// only a trailing `.md` is replaced so `.mdx` or a path
|
|
182
|
+
// containing `.md` mid-string cannot make href and fullPath
|
|
183
|
+
// disagree.
|
|
184
|
+
const wholeFilePathString = `/${page
|
|
185
|
+
.split(path.sep)
|
|
186
|
+
.join('/')
|
|
187
|
+
.replace(/\.md$/, '.html')}`
|
|
188
|
+
|
|
189
|
+
// `href` stays in the site's LOGICAL (un-prefixed) namespace โ the
|
|
190
|
+
// same value whether or not the site is deployed to a subdirectory.
|
|
191
|
+
// A `base_path` prefix is applied uniformly at the very end, in the
|
|
192
|
+
// render/asset URL rewrite, NOT here: templates and plugins do URL
|
|
193
|
+
// math on `meta.href` (e.g. a language switcher stripping `/de`, an
|
|
194
|
+
// active-link `link.href === meta.href` check), and pre-prefixing it
|
|
195
|
+
// would break that math and double-prefix on rewrite.
|
|
196
|
+
results.push({
|
|
197
|
+
content,
|
|
198
|
+
meta: {
|
|
199
|
+
...md.meta,
|
|
200
|
+
createdAt,
|
|
201
|
+
href: wholeFilePathString,
|
|
202
|
+
fullPath: wholeFilePathString,
|
|
203
|
+
dirname: path.posix.dirname(wholeFilePathString),
|
|
204
|
+
filename: path.posix.basename(wholeFilePathString),
|
|
205
|
+
},
|
|
206
|
+
})
|
|
207
|
+
|
|
208
|
+
successCount++
|
|
209
|
+
} catch (err) {
|
|
210
|
+
console.error(`โ Failed to process page ${page}:`, err.message)
|
|
211
|
+
errorCount++
|
|
212
|
+
// Skip this page - don't add it to results
|
|
213
|
+
}
|
|
214
|
+
})
|
|
215
|
+
|
|
216
|
+
// Summary logging
|
|
217
|
+
if (pages.length > 0) {
|
|
218
|
+
console.log(
|
|
219
|
+
`๐ Page processing complete: ${successCount} success, ${errorCount} errors`
|
|
220
|
+
)
|
|
221
|
+
if (errorCount > 0) {
|
|
222
|
+
console.warn(`โ ๏ธ ${errorCount} page(s) were skipped due to errors`)
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
return results
|
|
227
|
+
}
|
package/src/index.js
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { loadAppData, getPagesData, defaultSettings } from './core.js'
|
|
2
|
+
import { getPluginsData } from './setup-plugins.js'
|
|
3
|
+
import {
|
|
4
|
+
copyFolder,
|
|
5
|
+
deleteFolder,
|
|
6
|
+
createHtmlFiles,
|
|
7
|
+
rewriteAssetUrls,
|
|
8
|
+
} from './render.js'
|
|
9
|
+
import { resolveTheme, checkThemeCompatibility } from './theme.js'
|
|
10
|
+
|
|
11
|
+
const run = async (settings = defaultSettings) => {
|
|
12
|
+
let data = loadAppData(settings)
|
|
13
|
+
|
|
14
|
+
// Discover the configured theme (ROADMAP-themes.md ยง1). Null when no
|
|
15
|
+
// `theme:` key is set, in which case render behaves exactly as before.
|
|
16
|
+
const theme = resolveTheme({ app: data.app })
|
|
17
|
+
|
|
18
|
+
// Verify the theme's compatibility declarations before doing any work (ยง5):
|
|
19
|
+
// a nera.generator range that excludes THIS generator fails the build (a
|
|
20
|
+
// newer theme may use an app.* key or behaviour that does not exist here),
|
|
21
|
+
// while an unsatisfied plugin peerDependency only warns (the plugin still
|
|
22
|
+
// renders correct markup; the theme just may lack CSS for it). Synchronous;
|
|
23
|
+
// a theme declaring neither field, or a themeless site, is unaffected.
|
|
24
|
+
checkThemeCompatibility(theme)
|
|
25
|
+
|
|
26
|
+
// Expose the theme to templates as one namespaced object (ยง1c), so a layout
|
|
27
|
+
// reads `app.theme.config.colors.primary`. `config` is the theme's own
|
|
28
|
+
// `config/theme.yaml` defaults deep-merged with the site's optional override.
|
|
29
|
+
// Attached before the plugin pass so plugins see it too and it threads
|
|
30
|
+
// through the app object like `lang` and `name` do.
|
|
31
|
+
if (theme) {
|
|
32
|
+
data.app = {
|
|
33
|
+
...data.app,
|
|
34
|
+
theme: {
|
|
35
|
+
name: theme.name,
|
|
36
|
+
package: theme.package,
|
|
37
|
+
config: theme.config,
|
|
38
|
+
},
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// From `data.app`, not from `settings`: loadAppData has already merged any
|
|
43
|
+
// `folders` block in config/app.yaml over the defaults, and this is what
|
|
44
|
+
// makes that block take effect. Reading `settings.folders` here meant the
|
|
45
|
+
// key was honoured by anything reading `app.folders` โ plugins โ while the
|
|
46
|
+
// render itself ignored it, so a site that set `folders.assets` had its
|
|
47
|
+
// plugin output written to one folder and a different one copied into
|
|
48
|
+
// public/.
|
|
49
|
+
const { assets, dist, views, pages, plugins } = data.app.folders
|
|
50
|
+
|
|
51
|
+
data.pagesData = getPagesData(data.pages, pages)
|
|
52
|
+
data = await getPluginsData(data, plugins)
|
|
53
|
+
|
|
54
|
+
await deleteFolder(dist)
|
|
55
|
+
await createHtmlFiles(data, views, dist, theme)
|
|
56
|
+
|
|
57
|
+
// Assets layer like views: theme first, site second, so a site file with
|
|
58
|
+
// the same path overwrites the theme's (ยง2). A theme that ships no assets
|
|
59
|
+
// is fine โ copyFolder no-ops on a missing source. The theme pass passes
|
|
60
|
+
// `null` so it is unfiltered โ a theme package's payload is author-controlled
|
|
61
|
+
// and must not be dropped by anyone's .neraignore (ยง2d). The site pass reads
|
|
62
|
+
// the site's own .neraignore from the site root ('.'), so it keeps filtering
|
|
63
|
+
// the site's assets even though they now live under `theme/assets`.
|
|
64
|
+
if (theme) {
|
|
65
|
+
await copyFolder(theme.assetsRoot, dist, null)
|
|
66
|
+
}
|
|
67
|
+
await copyFolder(assets, dist, '.')
|
|
68
|
+
|
|
69
|
+
// Subdirectory deploys: prefix root-absolute URLs inside copied assets that
|
|
70
|
+
// the HTML rewrite can't reach (CSS `url(/โฆ)`, the web app manifest). Runs
|
|
71
|
+
// after both asset passes; no-op when `base_path` is unset.
|
|
72
|
+
await rewriteAssetUrls(dist, data.app.basePath)
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export default run
|
|
76
|
+
|
|
77
|
+
// Public API barrel for `@nera-static/core`. `run` (the whole build) doubles as
|
|
78
|
+
// the default and a named export; the rest is what the CLI, `@nera-static/validate`
|
|
79
|
+
// and tooling reuse โ the pipeline stages, the layered resolver, and the
|
|
80
|
+
// read-only site-model loader. Subpath exports (`@nera-static/core/resolve`,
|
|
81
|
+
// `/site-model`, โฆ) stay available for callers that want only one module.
|
|
82
|
+
export { run }
|
|
83
|
+
export {
|
|
84
|
+
loadAppData,
|
|
85
|
+
getPagesData,
|
|
86
|
+
computeFolders,
|
|
87
|
+
defaultSettings,
|
|
88
|
+
normalizeBasePath,
|
|
89
|
+
} from './core.js'
|
|
90
|
+
export { getPluginsData } from './setup-plugins.js'
|
|
91
|
+
export {
|
|
92
|
+
makeLayeredResolver,
|
|
93
|
+
resolveEntry,
|
|
94
|
+
defaultResolvePath,
|
|
95
|
+
} from './resolve.js'
|
|
96
|
+
export { resolveSiteModel } from './site-model.js'
|
|
97
|
+
export {
|
|
98
|
+
resolveTheme,
|
|
99
|
+
checkThemeCompatibility,
|
|
100
|
+
deepMerge,
|
|
101
|
+
} from './theme.js'
|