@nera-static/core 4.9.3 → 4.11.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 +20 -2
- package/package.json +2 -2
- package/src/index.js +6 -0
- package/src/render.js +159 -0
package/README.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
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
|
+
📖 **Documentation:** [nera.js.org](https://nera.js.org)
|
|
8
|
+
|
|
7
9
|
> ⚠️ This project is under active development. Breaking changes may occur.
|
|
8
10
|
|
|
9
11
|
---
|
|
@@ -38,7 +40,7 @@ npm install @nera-static/core
|
|
|
38
40
|
1. **`loadAppData`** — parse `config/app.yaml` into `app`; resolve the presentation folders (and the `theme/` probe) and list `pages/` recursively.
|
|
39
41
|
2. **`getPagesData`** — render each Markdown file with markdown-it, extract frontmatter, and derive `meta.href`/`dirname`/`filename`/`createdAt`. Returns `[{ content, meta }]`.
|
|
40
42
|
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),
|
|
43
|
+
4. **render** — delete `public/`, write the HTML files (layering theme views under the site's), copy assets (theme first, site second), rewrite root-absolute URLs for `base_path` deploys, and (opt-in) version asset URLs with content hashes for cache busting.
|
|
42
44
|
|
|
43
45
|
Two things that are easy to miss:
|
|
44
46
|
|
|
@@ -133,6 +135,22 @@ For **absolute** URLs you build yourself (canonical/OpenGraph tags, a sitemap),
|
|
|
133
135
|
|
|
134
136
|
---
|
|
135
137
|
|
|
138
|
+
## 🔄 Cache busting (`asset_hashing`)
|
|
139
|
+
|
|
140
|
+
Browsers cache stylesheets, scripts and fonts, so after a deploy visitors can keep seeing the old CSS/JS until they force a reload. Enable content hashing in `config/app.yaml`:
|
|
141
|
+
|
|
142
|
+
```yaml
|
|
143
|
+
asset_hashing: true
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
As the last build step the engine appends `?v=<hash>` — the first 10 hex chars of the file's SHA-256 — to every local asset URL in the output: `<link>`/`<script>`/`<img>` sources, `srcset`, `poster`, `data-search-index`, and `url(…)` inside CSS. The hash is taken from the file that actually landed in `public/`, so site assets, theme-package assets and plugin output are all covered, and templates keep writing plain `/css/main.css`. Each file is versioned on its own: its URL changes exactly when its content does, and stays cacheable otherwise. A stylesheet is hashed after its `url()` references are rewritten, so a changed font busts the CSS as well.
|
|
147
|
+
|
|
148
|
+
Left untouched: links to pages (`.html`, directories), external and protocol-relative URLs, other schemes (`data:`, `mailto:`), fragment-only refs, URLs that already carry a query string, and references that don't resolve to a file in `public/`. It composes with `base_path`. URLs a script builds at runtime (a `fetch('/data.json')` literal in JS) are not rewritten — pass them in through an attribute such as `data-search-index` instead.
|
|
149
|
+
|
|
150
|
+
Opt-in and additive: without the key the build is byte-identical.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
136
154
|
## 🛠 Developing this engine
|
|
137
155
|
|
|
138
156
|
This repo ships a bundled demo site used to exercise the pipeline during development — the same pipeline the CLI drives via `run()`:
|
|
@@ -151,6 +169,6 @@ Formatting is enforced by eslint: 4-space indent, no semicolons, single quotes.
|
|
|
151
169
|
|
|
152
170
|
## 📚 Further reading
|
|
153
171
|
|
|
172
|
+
- [nera.js.org](https://nera.js.org) — the official Nera website and documentation
|
|
154
173
|
- [`@nera-static/nera`](https://github.com/seebaermichi/nera-cli) — the CLI, and the getting-started for building a site
|
|
155
174
|
- [PLUGINS.md](https://github.com/seebaermichi/nera/blob/main/PLUGINS.md) — the plugin catalog
|
|
156
|
-
- [How Nera is used to build its own website](https://medium.com/@micha.becker79/building-nera-website-with-nera-4b50ed5dbff2)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nera-static/core",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.11.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",
|
package/src/index.js
CHANGED
|
@@ -5,6 +5,7 @@ import {
|
|
|
5
5
|
deleteFolder,
|
|
6
6
|
createHtmlFiles,
|
|
7
7
|
rewriteAssetUrls,
|
|
8
|
+
hashAssetUrls,
|
|
8
9
|
} from './render.js'
|
|
9
10
|
import { resolveTheme, checkThemeCompatibility } from './theme.js'
|
|
10
11
|
|
|
@@ -70,6 +71,11 @@ const run = async (settings = defaultSettings) => {
|
|
|
70
71
|
// the HTML rewrite can't reach (CSS `url(/…)`, the web app manifest). Runs
|
|
71
72
|
// after both asset passes; no-op when `base_path` is unset.
|
|
72
73
|
await rewriteAssetUrls(dist, data.app.basePath)
|
|
74
|
+
|
|
75
|
+
// Cache busting: append `?v=<content hash>` to local asset URLs in the
|
|
76
|
+
// output. Last, so it hashes the final files behind the final URLs. No-op
|
|
77
|
+
// unless `asset_hashing: true` is set in config/app.yaml.
|
|
78
|
+
await hashAssetUrls(dist, data.app.basePath, data.app.asset_hashing === true)
|
|
73
79
|
}
|
|
74
80
|
|
|
75
81
|
export default run
|
package/src/render.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import fs from 'fs/promises'
|
|
2
2
|
import fssync from 'fs'
|
|
3
3
|
import path from 'path'
|
|
4
|
+
import { createHash } from 'crypto'
|
|
4
5
|
import cpy from 'cpy'
|
|
5
6
|
import pug from 'pug'
|
|
6
7
|
import pretty from 'pretty'
|
|
@@ -154,6 +155,164 @@ export const rewriteAssetUrls = async (publicFolder, basePath) => {
|
|
|
154
155
|
}
|
|
155
156
|
// -----------------------------------------------------------------------------
|
|
156
157
|
|
|
158
|
+
// --- Asset hashing (config `asset_hashing: true` → cache busting) -------------
|
|
159
|
+
//
|
|
160
|
+
// Appends `?v=<content hash>` to every local asset URL in the built output, so
|
|
161
|
+
// a browser's cached copy is invalidated exactly when that file changes and
|
|
162
|
+
// kept otherwise. Runs as the very last build pass, over the files that actually
|
|
163
|
+
// landed in `public/` — site assets, theme-package assets and plugin output
|
|
164
|
+
// alike — so templates and themes keep writing plain `/css/main.css` and never
|
|
165
|
+
// need to know about it. Opt-in: without the key the output is byte-identical.
|
|
166
|
+
//
|
|
167
|
+
// Order matters: CSS files are rewritten first (their `url()` references —
|
|
168
|
+
// fonts, images — are leaves), and a file's hash is taken from its *final*
|
|
169
|
+
// content, so a font change changes the CSS hash too and busts the stylesheet.
|
|
170
|
+
//
|
|
171
|
+
// Left alone: external and protocol-relative URLs, `data:`/`mailto:` and other
|
|
172
|
+
// schemes, fragment-only refs, URLs that already carry a query string (the
|
|
173
|
+
// author chose one), links to pages (`.html`/`.htm`, directories), and any
|
|
174
|
+
// reference that does not resolve to a file in `public/`.
|
|
175
|
+
|
|
176
|
+
const HASH_LENGTH = 10
|
|
177
|
+
const PAGE_EXTENSIONS = new Set(['.html', '.htm'])
|
|
178
|
+
|
|
179
|
+
// Split `path#fragment` so the query lands before the fragment.
|
|
180
|
+
const splitFragment = (url) => {
|
|
181
|
+
const i = url.indexOf('#')
|
|
182
|
+
return i === -1 ? [url, ''] : [url.slice(0, i), url.slice(i)]
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
const isHashable = (url) =>
|
|
186
|
+
typeof url === 'string' &&
|
|
187
|
+
url !== '' &&
|
|
188
|
+
!url.startsWith('#') &&
|
|
189
|
+
!url.startsWith('//') &&
|
|
190
|
+
!/^[a-z][a-z0-9+.-]*:/i.test(url) &&
|
|
191
|
+
!url.includes('?')
|
|
192
|
+
|
|
193
|
+
// Returns `hashUrl(url, fromFile)`. Hashes are memoised per hasher and read
|
|
194
|
+
// from the file as it is on disk at first use.
|
|
195
|
+
const makeHasher = (publicFolder, basePath) => {
|
|
196
|
+
const cache = new Map()
|
|
197
|
+
const root = path.resolve(publicFolder)
|
|
198
|
+
|
|
199
|
+
// Resolve a URL as written in `fromFile` to a file inside `public/`, or null.
|
|
200
|
+
const resolveTarget = (url, fromFile) => {
|
|
201
|
+
let decoded
|
|
202
|
+
try {
|
|
203
|
+
decoded = decodeURI(url)
|
|
204
|
+
} catch {
|
|
205
|
+
return null
|
|
206
|
+
}
|
|
207
|
+
let target
|
|
208
|
+
if (decoded.startsWith('/')) {
|
|
209
|
+
// Root-absolute: strip a `base_path` prefix the base-path pass added.
|
|
210
|
+
const local =
|
|
211
|
+
basePath && decoded.startsWith(`${basePath}/`)
|
|
212
|
+
? decoded.slice(basePath.length)
|
|
213
|
+
: decoded
|
|
214
|
+
target = path.join(root, local)
|
|
215
|
+
} else {
|
|
216
|
+
target = path.resolve(path.dirname(fromFile), decoded)
|
|
217
|
+
}
|
|
218
|
+
if (!target.startsWith(`${root}${path.sep}`)) return null
|
|
219
|
+
if (PAGE_EXTENSIONS.has(path.extname(target).toLowerCase())) return null
|
|
220
|
+
try {
|
|
221
|
+
return fssync.statSync(target).isFile() ? target : null
|
|
222
|
+
} catch {
|
|
223
|
+
return null
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
return (url, fromFile) => {
|
|
228
|
+
if (!isHashable(url)) return url
|
|
229
|
+
const [pathPart, fragment] = splitFragment(url)
|
|
230
|
+
if (!pathPart) return url
|
|
231
|
+
const target = resolveTarget(pathPart, fromFile)
|
|
232
|
+
if (!target) return url
|
|
233
|
+
|
|
234
|
+
let hash = cache.get(target)
|
|
235
|
+
if (!hash) {
|
|
236
|
+
hash = createHash('sha256')
|
|
237
|
+
.update(fssync.readFileSync(target))
|
|
238
|
+
.digest('hex')
|
|
239
|
+
.slice(0, HASH_LENGTH)
|
|
240
|
+
cache.set(target, hash)
|
|
241
|
+
}
|
|
242
|
+
return `${pathPart}?v=${hash}${fragment}`
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
// Version the URL-bearing attributes of one HTML document. Mirrors the
|
|
247
|
+
// attribute set of the base-path rewrite, but also accepts relative values.
|
|
248
|
+
export const hashHtmlUrls = (html, htmlFile, hashUrl) =>
|
|
249
|
+
html
|
|
250
|
+
.replace(
|
|
251
|
+
/\b(href|src|poster|data-search-index)=("|')([^"']*)\2/gi,
|
|
252
|
+
(m, attr, quote, val) =>
|
|
253
|
+
`${attr}=${quote}${hashUrl(val, htmlFile)}${quote}`
|
|
254
|
+
)
|
|
255
|
+
.replace(/\bsrcset=("|')([^"']*)\1/gi, (m, quote, list) => {
|
|
256
|
+
const rewritten = list
|
|
257
|
+
.split(',')
|
|
258
|
+
.map((part) => {
|
|
259
|
+
const seg = part.trim()
|
|
260
|
+
if (!seg) return part
|
|
261
|
+
const [url, ...descriptor] = seg.split(/\s+/)
|
|
262
|
+
return [hashUrl(url, htmlFile), ...descriptor].join(' ')
|
|
263
|
+
})
|
|
264
|
+
.join(', ')
|
|
265
|
+
return `srcset=${quote}${rewritten}${quote}`
|
|
266
|
+
})
|
|
267
|
+
|
|
268
|
+
// Version the `url()` references of one CSS file (root-absolute or relative).
|
|
269
|
+
export const hashCssUrls = (css, cssFile, hashUrl) =>
|
|
270
|
+
css.replace(
|
|
271
|
+
/url\(\s*(['"]?)([^)'"]*)\1\s*\)/gi,
|
|
272
|
+
(m, quote, val) =>
|
|
273
|
+
`url(${quote}${hashUrl(val.trim(), cssFile)}${quote})`
|
|
274
|
+
)
|
|
275
|
+
|
|
276
|
+
// The pass itself. No-op unless `enabled`; run it after every asset copy and
|
|
277
|
+
// after rewriteAssetUrls, so it sees the final files and final (prefixed) URLs.
|
|
278
|
+
export const hashAssetUrls = async (publicFolder, basePath, enabled) => {
|
|
279
|
+
if (!enabled || !fssync.existsSync(publicFolder)) return
|
|
280
|
+
|
|
281
|
+
const cssFiles = []
|
|
282
|
+
const htmlFiles = []
|
|
283
|
+
const walk = async (dir) => {
|
|
284
|
+
for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
|
|
285
|
+
const full = path.join(dir, entry.name)
|
|
286
|
+
if (entry.isDirectory()) {
|
|
287
|
+
await walk(full)
|
|
288
|
+
continue
|
|
289
|
+
}
|
|
290
|
+
const ext = path.extname(entry.name).toLowerCase()
|
|
291
|
+
if (ext === '.css') cssFiles.push(full)
|
|
292
|
+
else if (PAGE_EXTENSIONS.has(ext)) htmlFiles.push(full)
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
await walk(publicFolder)
|
|
296
|
+
|
|
297
|
+
// CSS first, so each stylesheet's hash is taken from its rewritten content.
|
|
298
|
+
// The HTML pass gets a fresh hasher: a stylesheet hashed during the CSS pass
|
|
299
|
+
// (as an `@import` target) may have been rewritten since.
|
|
300
|
+
const hashInCss = makeHasher(publicFolder, basePath)
|
|
301
|
+
for (const file of cssFiles.sort()) {
|
|
302
|
+
const css = await fs.readFile(file, 'utf-8')
|
|
303
|
+
const out = hashCssUrls(css, file, hashInCss)
|
|
304
|
+
if (out !== css) await fs.writeFile(file, out, 'utf-8')
|
|
305
|
+
}
|
|
306
|
+
const hashInHtml = makeHasher(publicFolder, basePath)
|
|
307
|
+
for (const file of htmlFiles) {
|
|
308
|
+
const html = await fs.readFile(file, 'utf-8')
|
|
309
|
+
const out = hashHtmlUrls(html, file, hashInHtml)
|
|
310
|
+
if (out !== html) await fs.writeFile(file, out, 'utf-8')
|
|
311
|
+
}
|
|
312
|
+
console.log(SUCCESS_COLOR, 'Asset URLs hashed')
|
|
313
|
+
}
|
|
314
|
+
// -----------------------------------------------------------------------------
|
|
315
|
+
|
|
157
316
|
const getIgnoredFiles = (basePath) => {
|
|
158
317
|
const ignorePath = path.join(basePath, '.neraignore')
|
|
159
318
|
|