@uniweb/build 1.13.11 → 1.14.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uniweb/build",
3
- "version": "1.13.11",
3
+ "version": "1.14.0",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -56,15 +56,15 @@
56
56
  "js-yaml": "^4.3.2",
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
- "@uniweb/projections": "~1.2.9",
60
- "@uniweb/semantic-parser": "~1.13.2",
61
- "@uniweb/schemas": "~1.6.7",
62
59
  "@uniweb/content-reader": "~1.5.8",
60
+ "@uniweb/projections": "~1.2.10",
61
+ "@uniweb/schemas": "~1.6.7",
63
62
  "@uniweb/theming": "~1.2.1",
63
+ "@uniweb/semantic-parser": "~1.13.2",
64
64
  "@uniweb/content-writer": "~1.3.1"
65
65
  },
66
66
  "optionalDependencies": {
67
- "@uniweb/runtime": "~1.3.7"
67
+ "@uniweb/runtime": "~1.3.9"
68
68
  },
69
69
  "peerDependencies": {
70
70
  "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,8 +73,8 @@
73
73
  "@tailwindcss/vite": "^4.0.0",
74
74
  "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
75
75
  "vite-plugin-svgr": "^4.0.0",
76
- "@uniweb/runtime": "~1.3.7",
77
- "@uniweb/core": "~1.5.2"
76
+ "@uniweb/core": "~1.6.0",
77
+ "@uniweb/runtime": "~1.3.9"
78
78
  },
79
79
  "peerDependenciesMeta": {
80
80
  "vite": {
@@ -0,0 +1,385 @@
1
+ /**
2
+ * Freezing a site's docs as a version: `uniweb add version v2`.
3
+ *
4
+ * The docs stay where they are, at their URLs. A copy goes into a folder named `v2` beside them, and
5
+ * from then on it is an ordinary folder of pages at its own URL (`@uniweb/projections/versions`).
6
+ * What makes this more than `cp -R` is what a copy gets wrong:
7
+ *
8
+ * - **Page ids.** An id is unique across a site, and it's how a `page:` link finds its page, so a
9
+ * copy that keeps them makes every such link an accident of page order. A frozen copy never moves,
10
+ * which is what an id is for, so it gets none. The app mints its own for a page it receives.
11
+ * - **Links.** A link into the pages being copied must lead to the copy, or an old version's pages
12
+ * send a reader to the latest with nothing to say so. Each becomes a path into the copy. A relative
13
+ * link inside the copy already works, and one that leaves it needs one more `../`.
14
+ * - **Search engines.** An older version is kept out of them, so a search sends people to the latest.
15
+ *
16
+ * ⛔ Text, not a parse. These are an author's files, and a parse and a print would drop their
17
+ * comments and reflow them. A code sample that reads `[a](page:b)` is words about a link, as it is to
18
+ * the sync (`uwx/page-refs.js`); a tagged data block (`yaml:nav`) is content, and its links count.
19
+ *
20
+ * Nothing is written until the whole copy is planned, so a refusal leaves no trace.
21
+ */
22
+
23
+ import { existsSync, statSync } from 'node:fs'
24
+ import { copyFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
25
+ import { dirname, join, posix, resolve, relative } from 'node:path'
26
+ import yaml from 'js-yaml'
27
+ import { isVersionFolder } from '@uniweb/projections/versions'
28
+ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
29
+ import { collectSiteContent, mountEntriesOf, readFolderConfig, readYamlFile, rootOrderConfig } from './content-collector.js'
30
+
31
+ const routeKey = (route) => String(route).replace(/^\/+/, '').replace(/\/+$/, '')
32
+ const CONFIG_FILES = new Set(['page.yml', 'folder.yml'])
33
+ // What of the docs folder's own config still describes the copy. The rest names the folder itself.
34
+ const CARRIED_KEYS = ['pages', 'sections', 'nest', 'redirect']
35
+
36
+ /**
37
+ * The folder holding the docs, as a path under `pages/`.
38
+ *
39
+ * Named, or the one that already holds versions, or `docs`. Refused rather than guessed otherwise.
40
+ */
41
+ function findFolder(named, { pages, pagesDir, mounts, homepage }) {
42
+ if (named !== undefined && named !== null) {
43
+ const clean = routeKey(String(named).replace(/^\.\/?/, '').replace(/^pages(\/|$)/, ''))
44
+ if (clean.split('/').some(isVersionFolder)) {
45
+ throw new Error(`"${named}" is a version. Name the folder that holds the versions.`)
46
+ }
47
+ return clean
48
+ }
49
+
50
+ const holding = new Set()
51
+ for (const { route } of pages) {
52
+ const segments = route.split('/').filter(Boolean)
53
+ const at = segments.findIndex(isVersionFolder)
54
+ if (at === -1) continue
55
+ const above = segments.slice(0, at).join('/')
56
+ holding.add(!above && homepage && existsSync(join(pagesDir, homepage, segments[0])) ? homepage : above)
57
+ }
58
+ if (holding.size === 1) return [...holding][0]
59
+ if (holding.size > 1) {
60
+ throw new Error(
61
+ `More than one folder holds versions: ${[...holding].map((f) => f || '.').join(', ')}. Say which with --in <folder>.`
62
+ )
63
+ }
64
+ if (mounts.has('docs') || existsSync(join(pagesDir, 'docs'))) return 'docs'
65
+ throw new Error('Say which folder holds the docs with --in <folder>, or --in . for the whole site.')
66
+ }
67
+
68
+ /** One link's new address, or null if it leads nowhere the copy changes. */
69
+ function linkRewriter({ routes, ids }) {
70
+ const count = { links: 0 }
71
+ const rewrite = (dest) => {
72
+ const cut = dest.search(/[#?]/)
73
+ const [path, tail] = cut === -1 ? [dest, ''] : [dest.slice(0, cut), dest.slice(cut)]
74
+ if (path.startsWith('page:')) {
75
+ const name = path.slice('page:'.length)
76
+ const to = ids.get(name) ?? routes.get(routeKey(name))
77
+ if (to === undefined) return null
78
+ count.links++
79
+ return `page:${routeKey(to)}${tail}`
80
+ }
81
+ if (path.startsWith('/')) {
82
+ const to = routes.get(routeKey(path))
83
+ if (to === undefined) return null
84
+ count.links++
85
+ return `${to}${tail}`
86
+ }
87
+ return null
88
+ }
89
+ return { rewrite, count }
90
+ }
91
+
92
+ /** A relative link that leaves the copied tree, or enters another version, is one level further now. */
93
+ function deeperLink(dest, fileDir) {
94
+ if (!/^\.\.?\//.test(dest)) return null
95
+ const target = posix.normalize(posix.join(fileDir, dest))
96
+ const first = target.split('/')[0]
97
+ return first === '..' || isVersionFolder(first) ? `../${dest}` : null
98
+ }
99
+
100
+ /** One line's links, outside its code spans. */
101
+ function rewriteInline(line, { rewrite, count }, fileDir) {
102
+ const replaceLinks = (text) =>
103
+ text.replace(/(\]\(\s*<?)([^)\s>]+)/g, (whole, open, dest) => {
104
+ const next = rewrite(dest) ?? deeperLink(dest, fileDir)
105
+ if (next === null) return whole
106
+ if (!dest.startsWith('page:') && !dest.startsWith('/')) count.links++
107
+ return `${open}${next}`
108
+ })
109
+
110
+ let out = ''
111
+ let at = 0
112
+ while (at < line.length) {
113
+ const tick = line.indexOf('`', at)
114
+ if (tick === -1) break
115
+ let run = tick
116
+ while (line[run] === '`') run++
117
+ const fence = line.slice(tick, run)
118
+ let close = line.indexOf(fence, run)
119
+ while (close !== -1 && (line[close - 1] === '`' || line[close + fence.length] === '`')) {
120
+ close = line.indexOf(fence, close + 1)
121
+ }
122
+ out += replaceLinks(line.slice(at, tick))
123
+ if (close === -1) {
124
+ out += fence
125
+ at = run
126
+ } else {
127
+ out += line.slice(tick, close + fence.length)
128
+ at = close + fence.length
129
+ }
130
+ }
131
+ return out + replaceLinks(line.slice(at))
132
+ }
133
+
134
+ /** A line of YAML whose whole value is an address: `link: page:guide`, `- /docs/guide`. */
135
+ function rewriteYamlLine(line, { rewrite }) {
136
+ const match = line.match(/^(\s*(?:-\s+)?(?:[\w.-]+:\s+)?)(['"]?)((?:page:|\/)[^'"\s]*)\2(\s*(?:#.*)?)$/)
137
+ if (!match) return line
138
+ const [, lead, quote, dest, rest] = match
139
+ const next = rewrite(dest)
140
+ return next === null ? line : `${lead}${quote}${next}${quote}${rest}`
141
+ }
142
+
143
+ /** JSON strings that are an address. */
144
+ function rewriteJsonLine(line, { rewrite }) {
145
+ return line.replace(/"((?:page:|\/)[^"\s]*)"/g, (whole, dest) => {
146
+ const next = rewrite(dest)
147
+ return next === null ? whole : `"${next}"`
148
+ })
149
+ }
150
+
151
+ /** A markdown file: its frontmatter's addresses, and its links outside of code. */
152
+ function rewriteMarkdown(text, links, fileDir) {
153
+ const lines = text.split('\n')
154
+ let i = 0
155
+ if (lines[0]?.trim() === '---') {
156
+ for (i = 1; i < lines.length && lines[i].trim() !== '---'; i++) lines[i] = rewriteYamlLine(lines[i], links)
157
+ i++
158
+ }
159
+ let fence = null
160
+ for (; i < lines.length; i++) {
161
+ const opens = lines[i].match(/^ {0,3}(`{3,}|~{3,})\s*([^\s`]*)/)
162
+ if (fence) {
163
+ const closes = opens && opens[1][0] === fence.mark[0] && opens[1].length >= fence.mark.length && !opens[2]
164
+ if (closes) fence = null
165
+ else if (fence.kind === 'yaml') lines[i] = rewriteYamlLine(lines[i], links)
166
+ else if (fence.kind === 'json') lines[i] = rewriteJsonLine(lines[i], links)
167
+ else if (fence.kind === 'md') lines[i] = rewriteInline(lines[i], links, fileDir)
168
+ } else if (opens) {
169
+ // A tagged block holds content; any other fence holds a sample, and is left as written.
170
+ const tagged = opens[2].match(/^(yaml|yml|json|md):/)
171
+ fence = { mark: opens[1], kind: tagged ? tagged[1].replace('yml', 'yaml') : null }
172
+ } else {
173
+ lines[i] = rewriteInline(lines[i], links, fileDir)
174
+ }
175
+ }
176
+ return lines.join('\n')
177
+ }
178
+
179
+ /** A page's config: no id, and its addresses into the copy. */
180
+ function rewriteConfig(text, links) {
181
+ const lines = text.split('\n').filter((line) => !/^id\s*:/.test(line))
182
+ return lines.map((line) => rewriteYamlLine(line, links)).join('\n')
183
+ }
184
+
185
+ /** `seo: { noindex: true }` added to a page's config, for a page a folder's can't speak for. */
186
+ function withNoindex(text) {
187
+ const parsed = yaml.load(text, YAML_OPTIONS) || {}
188
+ if (parsed.seo?.noindex === true) return text
189
+ if (/^seo\s*:\s*$/m.test(text)) return text.replace(/^seo\s*:\s*$/m, 'seo:\n noindex: true')
190
+ if (parsed.seo) return yaml.dump({ ...parsed, seo: { ...parsed.seo, noindex: true } })
191
+ return `${text.replace(/\n*$/, '\n')}seo:\n noindex: true\n`
192
+ }
193
+
194
+ /** Every file below a folder, as paths relative to it. The folder's own versions stay out. */
195
+ async function filesBelow(dir, { top = false, base = '' } = {}) {
196
+ const files = []
197
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
198
+ if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
199
+ const rel = base ? `${base}/${entry.name}` : entry.name
200
+ const isDirectory = entry.isDirectory() || (entry.isSymbolicLink() && statSync(join(dir, entry.name)).isDirectory())
201
+ if (isDirectory) {
202
+ if (top && isVersionFolder(entry.name)) continue
203
+ files.push(...(await filesBelow(join(dir, entry.name), { base: rel })))
204
+ } else if (!(top && CONFIG_FILES.has(entry.name))) {
205
+ files.push(rel)
206
+ }
207
+ }
208
+ return files
209
+ }
210
+
211
+ /**
212
+ * Freeze the docs in a folder as a version beside them.
213
+ *
214
+ * @param {string} siteRoot
215
+ * @param {Object} options
216
+ * @param {string} options.name - the version's folder name: `v2`, `v2.1`
217
+ * @param {string} [options.folder] - the folder holding the docs, under `pages/`; `.` for all of it
218
+ * @param {string} [options.label] - what a version switcher calls it (default: the name)
219
+ * @param {boolean} [options.keepInSearch=false] - leave it open to search engines
220
+ * @param {boolean} [options.dryRun=false] - say what would happen, and write nothing
221
+ * @returns {Promise<Object>} what it did: `{ name, folder, path, route, url, pages, files, ids, links, notes }`
222
+ */
223
+ export async function addVersion(siteRoot, { name, folder: named, label, keepInSearch = false, dryRun = false } = {}) {
224
+ if (!isVersionFolder(name)) {
225
+ const bare = /^\d/.test(String(name)) ? ` Did you mean v${name}?` : ''
226
+ throw new Error(`"${name}" isn't a version's name. It's a "v" and a number: v2, v2.1.${bare}`)
227
+ }
228
+
229
+ const site = await readYamlFile(join(siteRoot, 'site.yml'))
230
+ const pagesDir = resolve(siteRoot, site.paths?.pages ?? 'pages')
231
+ const mounts = new Map(mountEntriesOf(site.paths).map(([key, value]) => [key, resolve(siteRoot, value)]))
232
+ const { config: rootConfig } = await readFolderConfig(pagesDir, 'sections')
233
+ const homepage = rootOrderConfig(site, rootConfig).homepage
234
+ const { pages } = await collectSiteContent(siteRoot)
235
+
236
+ const folder = findFolder(named, { pages, pagesDir, mounts, homepage })
237
+ const segments = folder ? folder.split('/') : []
238
+ const dir = mounts.has(segments[0])
239
+ ? join(mounts.get(segments[0]), ...segments.slice(1))
240
+ : join(pagesDir, ...segments)
241
+ if (!existsSync(dir) || !statSync(dir).isDirectory()) {
242
+ throw new Error(`There's no folder pages/${folder}.`)
243
+ }
244
+ const target = join(dir, name)
245
+ if (existsSync(target)) {
246
+ throw new Error(`pages/${posix.join(folder, name)} already exists. To freeze the docs again, name a new version.`)
247
+ }
248
+
249
+ // Where the folder's pages are. A folder promoted to the homepage puts its pages at the root.
250
+ const isHomepage = segments[0] === homepage
251
+ const scope = `/${(isHomepage ? segments.slice(1) : segments).join('/')}`
252
+ const prefix = scope === '/' ? '' : scope
253
+ const versionRoute = `${prefix}/${name}`
254
+ const names = new Set(
255
+ (await readdir(dir, { withFileTypes: true }))
256
+ .filter((entry) => entry.isDirectory() || entry.name.endsWith('.md'))
257
+ .map((entry) => entry.name.replace(/^\d+(\.\d+)*-/, '').replace(/\.md$/, ''))
258
+ .filter((entry) => !isVersionFolder(entry) && !(folder === '' && entry === '404'))
259
+ )
260
+
261
+ // Every page being copied: where it is, and where its copy will be.
262
+ const copied = []
263
+ const routes = new Map()
264
+ const ids = new Map()
265
+ for (const page of pages) {
266
+ const from = page.sourcePath || page.route
267
+ let rest
268
+ if (scope === '/') rest = from === '/' || (isHomepage && from === `/${homepage}`) ? '' : from
269
+ else if (from === scope) rest = ''
270
+ else if (from.startsWith(`${scope}/`)) rest = from.slice(scope.length)
271
+ else continue
272
+ const first = rest.split('/').filter(Boolean)[0]
273
+ if (first && !names.has(first)) {
274
+ // A homepage's own pages sit at the root, and in the copy under its folder, like any other's.
275
+ if (scope !== '/' || !names.has(homepage)) continue
276
+ rest = `/${homepage}${rest}`
277
+ }
278
+ if (!first && page.route !== scope && !(isHomepage && from === `/${homepage}`)) continue
279
+ const to = `${versionRoute}${rest}`
280
+ copied.push({ page, to })
281
+ routes.set(routeKey(page.route), to)
282
+ routes.set(routeKey(from), to)
283
+ if (page.id !== null && page.id !== undefined && page.id !== '') ids.set(String(page.id), to)
284
+ }
285
+
286
+ const links = linkRewriter({ routes, ids })
287
+ const { config: ownConfig, mode } = await readFolderConfig(dir, 'sections')
288
+ const files = await filesBelow(dir, { top: true })
289
+ const hasOwnContent = mode !== 'pages' && files.some((file) => !file.includes('/') && file.endsWith('.md'))
290
+
291
+ // The copy, planned in full: text for what changes, a source for what doesn't.
292
+ const plan = []
293
+ let idsDropped = 0
294
+ for (const file of files) {
295
+ const from = join(dir, file)
296
+ const to = join(target, file)
297
+ const base = posix.basename(file)
298
+ if (CONFIG_FILES.has(base)) {
299
+ const original = await readFile(from, 'utf8')
300
+ if (/^id\s*:/m.test(original)) idsDropped++
301
+ let text = rewriteConfig(original, links)
302
+ // A folder with content speaks only for itself, so here each page has to say it.
303
+ if (hasOwnContent && !keepInSearch && base === 'page.yml') text = withNoindex(text)
304
+ plan.push({ to, text })
305
+ } else if (base.endsWith('.md')) {
306
+ plan.push({ to, text: rewriteMarkdown(await readFile(from, 'utf8'), links, posix.dirname(file)) })
307
+ } else {
308
+ plan.push({ to, from })
309
+ }
310
+ }
311
+
312
+ // The version's own page: what a switcher calls it, and how far search engines go.
313
+ const own = { title: label || name }
314
+ if (!keepInSearch) own.seo = { noindex: true }
315
+ for (const key of CARRIED_KEYS) {
316
+ if (ownConfig[key] === undefined) continue
317
+ own[key] =
318
+ key === 'pages' && Array.isArray(ownConfig.pages)
319
+ ? ownConfig.pages.filter((entry) => !isVersionFolder(entry))
320
+ : ownConfig[key]
321
+ }
322
+ if (typeof own.redirect === 'string') own.redirect = links.rewrite(own.redirect) ?? own.redirect
323
+ if (Array.isArray(own.pages) && !own.pages.length) delete own.pages
324
+ plan.push({ to: join(target, mode === 'pages' ? 'folder.yml' : 'page.yml'), text: yaml.dump(own, { lineWidth: -1 }) })
325
+
326
+ // Translations written by hand are kept by route or by id, and the copy has only a route.
327
+ const notes = []
328
+ const freeformRoot = join(resolve(siteRoot, site.paths?.locales ?? 'locales'), 'freeform')
329
+ if (existsSync(freeformRoot)) {
330
+ for (const locale of await readdir(freeformRoot, { withFileTypes: true })) {
331
+ if (!locale.isDirectory()) continue
332
+ const root = join(freeformRoot, locale.name)
333
+ for (const { page, to } of copied) {
334
+ const sources = [
335
+ page.id ? join(root, 'page-ids', String(page.id)) : null,
336
+ join(root, 'pages', routeKey(page.route)),
337
+ ].filter((source) => source && existsSync(source))
338
+ const seen = new Set()
339
+ for (const source of sources) {
340
+ for (const entry of await readdir(source, { withFileTypes: true })) {
341
+ if (!entry.isFile() || !entry.name.endsWith('.md') || seen.has(entry.name)) continue
342
+ seen.add(entry.name)
343
+ const text = rewriteMarkdown(await readFile(join(source, entry.name), 'utf8'), links, '.')
344
+ plan.push({ to: join(root, 'pages', routeKey(to), entry.name), text })
345
+ }
346
+ }
347
+ }
348
+ }
349
+ }
350
+
351
+ if (mounts.has(segments[0])) {
352
+ notes.push(`pages/${segments[0]} is mounted from ${relative(siteRoot, mounts.get(segments[0]))}, so the copy went there.`)
353
+ }
354
+ if (hasOwnContent && !keepInSearch) {
355
+ notes.push(
356
+ `pages/${folder} has content of its own, so its noindex can't speak for the pages below it. Each copied page.yml says it, and a page added to this version later needs to as well.`
357
+ )
358
+ }
359
+
360
+ if (!dryRun) {
361
+ try {
362
+ for (const { to, text, from } of plan) {
363
+ await mkdir(dirname(to), { recursive: true })
364
+ if (from) await copyFile(from, to)
365
+ else await writeFile(to, text)
366
+ }
367
+ } catch (err) {
368
+ await rm(target, { recursive: true, force: true })
369
+ throw err
370
+ }
371
+ }
372
+
373
+ return {
374
+ name,
375
+ folder,
376
+ path: relative(siteRoot, target),
377
+ route: versionRoute,
378
+ pages: copied.filter(({ page }) => page.hasContent !== false).length,
379
+ files: plan.length,
380
+ ids: idsDropped,
381
+ links: links.count.links,
382
+ keptOutOfSearch: !keepInSearch,
383
+ notes,
384
+ }
385
+ }
@@ -33,12 +33,14 @@ import { YAML_OPTIONS } from '../utils/yaml-schema.js'
33
33
  import { collectSectionAssets, mergeAssetCollections, collectConfigAssets, disambiguateAssetRefs } from './assets.js'
34
34
  import { collectSectionIcons, mergeIconCollections, buildIconManifest, refuseRetiredIconKey } from './icons.js'
35
35
  import { normalizeHideIn, dropUnpublishedPages, dropHiddenSections } from './nav-visibility.js'
36
+ import { warnOfDuplicatePageIds } from './duplicate-page-ids.js'
36
37
  import { parseFetchConfig, toFetchList } from './data-fetcher.js'
37
38
  import { resolveExtensionUrls } from './extension-urls.js'
38
39
  import { buildTheme, extractFoundationVars } from '../theme/index.js'
39
40
  import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig, pageRouteQuery, currentFor } from '@uniweb/core'
40
41
  import { authoredRedirectTarget } from '@uniweb/core/resolve-route'
41
42
  import { parentRouteOf } from '@uniweb/core/route-match'
43
+ import { compareVersionFolders, isVersionFolder } from '@uniweb/projections/versions'
42
44
  import { parseFrontmatter } from '../utils/frontmatter.js'
43
45
  import { noteSectionFile, rewriteFileLinks } from './file-links.js'
44
46
  import { valuesCutByComment } from '../utils/yaml-comment-trap.js'
@@ -174,56 +176,29 @@ function inheritedRouteParam(parentRoute) {
174
176
  return params.length ? params[params.length - 1] : null
175
177
  }
176
178
 
177
- // ─────────────────────────────────────────────────────────────────
178
- // Version Detection
179
- // ─────────────────────────────────────────────────────────────────
180
-
181
179
  /**
182
- * Check if a folder name represents a version (e.g., v1, v2, v1.0, v2.1)
183
- * @param {string} folderName - The folder name to check
184
- * @returns {boolean}
180
+ * ⛔ `versions:` is retired. A build used to move the latest version's pages out of its folder and
181
+ * read each version's label from this key, and a site published to a backend did neither. A version's
182
+ * URL is its folder now, on every lane, and its label is its own page's `title`.
185
183
  */
186
- function isVersionFolder(folderName) {
187
- return /^v\d+(\.\d+)?$/.test(folderName)
184
+ function refuseVersionsKey(folderYml, pageYml, dirPath) {
185
+ if (folderYml.versions === undefined && pageYml.versions === undefined) return
186
+ const file = relative(process.cwd(), join(dirPath, folderYml.versions !== undefined ? 'folder.yml' : 'page.yml'))
187
+ throw new Error(
188
+ `[uniweb] ${file}: \`versions:\` is retired. A version is a folder named like \`v1\`, labelled by the ` +
189
+ `\`title\` in its own page.yml, and the pages beside those folders are the latest. Move the latest ` +
190
+ `version's pages up beside the folders, and delete this key.`
191
+ )
188
192
  }
189
193
 
190
194
  /**
191
- * Parse version info from folder name
192
- * @param {string} folderName - The folder name (e.g., "v1", "v2.1")
193
- * @returns {Object} Version info { id, major, minor, sortKey }
195
+ * Version folders after the pages beside them, newest first, so a folder with no content of its own
196
+ * leads to the latest pages rather than the oldest. An `order:` still comes first.
194
197
  */
195
- function parseVersionInfo(folderName) {
196
- const match = folderName.match(/^v(\d+)(?:\.(\d+))?$/)
197
- if (!match) return null
198
-
199
- const major = parseInt(match[1], 10)
200
- const minor = match[2] ? parseInt(match[2], 10) : 0
201
-
202
- return {
203
- id: folderName,
204
- major,
205
- minor,
206
- sortKey: major * 1000 + minor // For sorting: v2.1 > v2.0 > v1.9
207
- }
208
- }
209
-
210
- /**
211
- * Detect if a set of folders contains version folders
212
- * @param {Array<string>} folderNames - List of folder names
213
- * @returns {Array<Object>|null} Sorted version infos (highest first) or null if not versioned
214
- */
215
- function detectVersions(folderNames) {
216
- const versions = folderNames
217
- .filter(isVersionFolder)
218
- .map(parseVersionInfo)
219
- .filter(Boolean)
220
-
221
- if (versions.length === 0) return null
222
-
223
- // Sort by version (highest first)
224
- versions.sort((a, b) => b.sortKey - a.sortKey)
225
-
226
- return versions
198
+ function versionFoldersLast(a, b) {
199
+ const [left, right] = [isVersionFolder(a), isVersionFolder(b)]
200
+ if (left && right) return compareVersionFolders(a, b)
201
+ return left ? 1 : right ? -1 : 0
227
202
  }
228
203
 
229
204
  /**
@@ -375,38 +350,6 @@ function warnUnreadCurrent(pages, layouts, siteFetch) {
375
350
  }
376
351
  }
377
352
 
378
- /**
379
- * Build version metadata from detected versions and page.yml config
380
- * @param {Array<Object>} detectedVersions - Detected version infos
381
- * @param {Object} pageConfig - page.yml configuration
382
- * @returns {Object} Version metadata { versions, latestId, scope }
383
- */
384
- function buildVersionMetadata(detectedVersions, pageConfig = {}) {
385
- const configVersions = pageConfig.versions || {}
386
-
387
- // Build version list with metadata
388
- const versions = detectedVersions.map((v, index) => {
389
- const config = configVersions[v.id] || {}
390
- const isLatest = config.latest === true || (index === 0 && !Object.values(configVersions).some(c => c.latest))
391
-
392
- return {
393
- id: v.id,
394
- label: config.label || v.id,
395
- latest: isLatest,
396
- deprecated: config.deprecated || false,
397
- sortKey: v.sortKey
398
- }
399
- })
400
-
401
- // Find the latest version
402
- const latestVersion = versions.find(v => v.latest) || versions[0]
403
-
404
- return {
405
- versions,
406
- latestId: latestVersion?.id || null
407
- }
408
- }
409
-
410
353
  /**
411
354
  * Malformed YAML met during the current collect.
412
355
  *
@@ -558,6 +501,7 @@ function getContentProfile(configFile) {
558
501
  async function readFolderConfig(dirPath, inheritedMode) {
559
502
  const folderYml = await readYamlFile(join(dirPath, 'folder.yml'))
560
503
  const pageYml = Object.keys(folderYml).length > 0 ? {} : await readYamlFile(join(dirPath, 'page.yml'))
504
+ refuseVersionsKey(folderYml, pageYml, dirPath)
561
505
  const { mode, source } = folderContentMode(folderYml, pageYml, existsSync(join(dirPath, 'folder.yml')), inheritedMode)
562
506
  return { config: source === 'folder.yml' ? folderYml : source === 'page.yml' ? pageYml : {}, mode, source }
563
507
  }
@@ -1121,9 +1065,6 @@ async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
1121
1065
  lastModified: fileStat.mtime?.toISOString() || null,
1122
1066
  isDynamic: false,
1123
1067
  paramName: null,
1124
- version: null,
1125
- versionMeta: null,
1126
- versionScope: null,
1127
1068
  // The file IS the page, so its `hidden: true` drafts the page — left out of a published
1128
1069
  // build, kept in dev — rather than leaving a page with no section (2026-09-28).
1129
1070
  hidden: section.hidden === true,
@@ -1449,7 +1390,6 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
1449
1390
  * @param {boolean} options.isIndex - Whether this page is the index for its parent route
1450
1391
  * @param {string} options.parentRoute - The parent route (e.g., '/' or '/docs')
1451
1392
  * @param {Object} options.parentFetch - Parent page's fetch config (for dynamic routes)
1452
- * @param {Object} options.versionContext - Version context from parent { version, versionMeta, scope }
1453
1393
  * @returns {Object} Page data with assets manifest
1454
1394
  */
1455
1395
  /**
@@ -1491,7 +1431,7 @@ function mergeLayoutConfig(inherited, own) {
1491
1431
  return { ...(inherited || {}), ...(own || {}) }
1492
1432
  }
1493
1433
 
1494
- async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null, versionContext = null, inheritedLayout = null } = {}) {
1434
+ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, parentRoute = '/', parentFetch = null, inheritedLayout = null } = {}) {
1495
1435
  const pageConfig = await readYamlFile(join(pagePath, 'page.yml'))
1496
1436
 
1497
1437
  // Note: We no longer skip hidden pages here - they still exist as valid pages,
@@ -1823,11 +1763,6 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
1823
1763
  isDynamic,
1824
1764
  paramName, // e.g., "slug" from [slug]; a nested page's ancestor's
1825
1765
 
1826
- // Version metadata (if within a versioned section)
1827
- version: versionContext?.version || null,
1828
- versionMeta: versionContext?.versionMeta || null,
1829
- versionScope: versionContext?.scope || null,
1830
-
1831
1766
  // Navigation options
1832
1767
  hidden: pageConfig.hidden || false, // Hide from all navigation
1833
1768
  hideIn: normalizeHideIn(pageConfig), // Named nav areas to suppress this page from
@@ -1928,8 +1863,7 @@ function declaredHomepage(config) {
1928
1863
  /**
1929
1864
  * The homepage a level's order config names. The root's was already decided across
1930
1865
  * its two configs, and arrives as `homepage` (`rootOrderConfig`); any other level
1931
- * that promotes one — a folder promoted to `/`, the latest version of a scope at the
1932
- * root — names it in its own config.
1866
+ * that promotes one, a folder promoted to `/`, names it in its own config.
1933
1867
  */
1934
1868
  function homepageOf(orderConfig) {
1935
1869
  return orderConfig && 'homepage' in orderConfig ? orderConfig.homepage : declaredHomepage(orderConfig)
@@ -1998,7 +1932,7 @@ function determineIndexPage(orderConfig, availableFolders) {
1998
1932
  const orderA = a.order ?? Infinity
1999
1933
  const orderB = b.order ?? Infinity
2000
1934
  if (orderA !== orderB) return orderA - orderB
2001
- return a.name.localeCompare(b.name)
1935
+ return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
2002
1936
  })
2003
1937
 
2004
1938
  return sorted[0].name
@@ -2012,11 +1946,10 @@ function determineIndexPage(orderConfig, availableFolders) {
2012
1946
  * @param {string} siteRoot - Site root directory for asset resolution
2013
1947
  * @param {Object} orderConfig - { pages: [...], index: 'name', order: [...] } from parent's config
2014
1948
  * @param {Object} parentFetch - Parent page's fetch config (for dynamic child routes)
2015
- * @param {Object} versionContext - Version context from parent { version, versionMeta }
2016
1949
  * @param {string} contentMode - 'sections' (default) or 'pages' (md files are child pages)
2017
- * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound, versionedScopes }
1950
+ * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound }
2018
1951
  */
2019
- async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, versionContext = null, contentMode = 'sections', mounts = null, parentLayout = null) {
1952
+ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, contentMode = 'sections', mounts = null, parentLayout = null) {
2020
1953
  const entries = await readdir(dirPath)
2021
1954
  const pages = []
2022
1955
  let assetCollection = {
@@ -2028,7 +1961,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2028
1961
  bySource: new Map()
2029
1962
  }
2030
1963
  let notFound = null
2031
- const versionedScopes = new Map() // scope route → versionMeta
2032
1964
 
2033
1965
  // First pass: discover all page folders and read their config.
2034
1966
  //
@@ -2083,7 +2015,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2083
2015
  const orderA = a.order ?? Infinity
2084
2016
  const orderB = b.order ?? Infinity
2085
2017
  if (orderA !== orderB) return orderA - orderB
2086
- return a.name.localeCompare(b.name)
2018
+ return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
2087
2019
  })
2088
2020
 
2089
2021
  // Apply ordering: pages: (wildcard-aware) > order: [array] (backward compat) > default
@@ -2106,56 +2038,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2106
2038
  orderedFolders = pageFolders
2107
2039
  }
2108
2040
 
2109
- // Check if this directory contains version folders (versioned section)
2110
- const folderNames = orderedFolders.map(f => f.name)
2111
- const detectedVersions = detectVersions(folderNames)
2112
-
2113
- // If versioned section, handle version folders specially (always page mode)
2114
- if (detectedVersions && !versionContext) {
2115
- const parentConfig = await readYamlFile(join(dirPath, 'page.yml'))
2116
- const versionMeta = buildVersionMetadata(detectedVersions, parentConfig)
2117
- versionedScopes.set(parentRoute, versionMeta)
2118
-
2119
- for (const folder of orderedFolders) {
2120
- const { name: entry, path: entryPath, childOrderConfig, childLayout } = folder
2121
-
2122
- if (isVersionFolder(entry)) {
2123
- const versionInfo = versionMeta.versions.find(v => v.id === entry)
2124
- const isLatest = versionInfo?.latest || false
2125
- const versionRoute = isLatest
2126
- ? parentRoute
2127
- : parentRoute === '/'
2128
- ? `/${entry}`
2129
- : `${parentRoute}/${entry}`
2130
-
2131
- const subResult = await collectPagesRecursive(
2132
- entryPath, versionRoute, siteRoot, childOrderConfig, parentFetch,
2133
- { version: versionInfo, versionMeta, scope: parentRoute },
2134
- 'sections', null, mergeLayoutConfig(parentLayout, childLayout)
2135
- )
2136
-
2137
- pages.push(...subResult.pages)
2138
- assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2139
- iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2140
- for (const [scope, meta] of subResult.versionedScopes) {
2141
- versionedScopes.set(scope, meta)
2142
- }
2143
- } else {
2144
- const result = await processPage(entryPath, entry, siteRoot, {
2145
- isIndex: false, parentRoute, parentFetch,
2146
- inheritedLayout: mergeLayoutConfig(parentLayout, childLayout)
2147
- })
2148
- if (result) {
2149
- pages.push(result.page)
2150
- assetCollection = mergeAssetCollections(assetCollection, result.assetCollection)
2151
- iconCollection = mergeIconCollections(iconCollection, result.iconCollection)
2152
- }
2153
- }
2154
- }
2155
-
2156
- return { pages, assetCollection, iconCollection, notFound, versionedScopes }
2157
- }
2158
-
2159
2041
  // --- Pages mode: .md files are child pages ---
2160
2042
  if (contentMode === 'pages') {
2161
2043
  // Each .md file is a page, in the order `folderModePageFiles` gives — the one the push sends
@@ -2214,7 +2096,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2214
2096
  if (dirMode === 'sections') {
2215
2097
  // Subdirectory overrides to page mode — process normally
2216
2098
  const result = await processPage(entryPath, entry, siteRoot, {
2217
- isIndex, parentRoute, parentFetch, versionContext,
2099
+ isIndex, parentRoute, parentFetch,
2218
2100
  inheritedLayout: effectiveLayout
2219
2101
  })
2220
2102
 
@@ -2245,13 +2127,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2245
2127
  const childParentRoute = isIndex ? parentRoute : page.route
2246
2128
  const childFetch = page.fetch || parentFetch
2247
2129
  const childContentMode = childMode
2248
- const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext, childContentMode, null, effectiveLayout)
2130
+ const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout)
2249
2131
  pages.push(...subResult.pages)
2250
2132
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2251
2133
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2252
- for (const [scope, meta] of subResult.versionedScopes) {
2253
- versionedScopes.set(scope, meta)
2254
- }
2255
2134
  }
2256
2135
  } else {
2257
2136
  // Container directory in folder mode — create minimal page, recurse
@@ -2272,9 +2151,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2272
2151
  lastModified: null,
2273
2152
  isDynamic: false,
2274
2153
  paramName: null,
2275
- version: versionContext?.version || null,
2276
- versionMeta: versionContext?.versionMeta || null,
2277
- versionScope: versionContext?.scope || null,
2278
2154
  hidden: dirConfig.hidden || false,
2279
2155
  hideIn: normalizeHideIn(dirConfig),
2280
2156
  ...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
@@ -2302,13 +2178,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2302
2178
  // Recurse in folder mode — pass container's own fetch config (or fall back to parent's)
2303
2179
  const childDirPath = mounts?.get(entry) || entryPath
2304
2180
  const containerFetch = containerPage.fetch || parentFetch
2305
- const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, childMode, null, effectiveLayout)
2181
+ const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout)
2306
2182
  pages.push(...subResult.pages)
2307
2183
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2308
2184
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2309
- for (const [scope, meta] of subResult.versionedScopes) {
2310
- versionedScopes.set(scope, meta)
2311
- }
2312
2185
  }
2313
2186
  }
2314
2187
 
@@ -2326,7 +2199,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2326
2199
  }
2327
2200
  }
2328
2201
 
2329
- return { pages, assetCollection, iconCollection, notFound, versionedScopes }
2202
+ return { pages, assetCollection, iconCollection, notFound }
2330
2203
  }
2331
2204
 
2332
2205
  // --- Sections mode (default): existing behavior ---
@@ -2369,9 +2242,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2369
2242
  lastModified: null,
2370
2243
  isDynamic: false,
2371
2244
  paramName: null,
2372
- version: versionContext?.version || null,
2373
- versionMeta: versionContext?.versionMeta || null,
2374
- versionScope: versionContext?.scope || null,
2375
2245
  hidden: dirConfig.hidden || false,
2376
2246
  hideIn: normalizeHideIn(dirConfig),
2377
2247
  ...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
@@ -2404,17 +2274,14 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2404
2274
  // container above passes it.
2405
2275
  const childDirPath = mounts?.get(entry) || entryPath
2406
2276
  const containerFetch = containerPage.fetch || parentFetch
2407
- const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, versionContext, childMode, null, effectiveLayout)
2277
+ const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout)
2408
2278
  pages.push(...subResult.pages)
2409
2279
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2410
2280
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2411
- for (const [scope, meta] of subResult.versionedScopes) {
2412
- versionedScopes.set(scope, meta)
2413
- }
2414
2281
  } else {
2415
2282
  // Sections mode — process directory as a page (existing behavior)
2416
2283
  const result = await processPage(entryPath, entry, siteRoot, {
2417
- isIndex, parentRoute, parentFetch, versionContext,
2284
+ isIndex, parentRoute, parentFetch,
2418
2285
  inheritedLayout: effectiveLayout
2419
2286
  })
2420
2287
 
@@ -2447,13 +2314,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2447
2314
  : page.route
2448
2315
  const childFetch = page.fetch || parentFetch
2449
2316
  const childContentMode = childMode
2450
- const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext, childContentMode, null, effectiveLayout)
2317
+ const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout)
2451
2318
  pages.push(...subResult.pages)
2452
2319
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2453
2320
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2454
- for (const [scope, meta] of subResult.versionedScopes) {
2455
- versionedScopes.set(scope, meta)
2456
- }
2457
2321
  }
2458
2322
  }
2459
2323
  }
@@ -2472,7 +2336,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2472
2336
  }
2473
2337
  }
2474
2338
 
2475
- return { pages, assetCollection, iconCollection, notFound, versionedScopes }
2339
+ return { pages, assetCollection, iconCollection, notFound }
2476
2340
  }
2477
2341
 
2478
2342
  /**
@@ -2821,8 +2685,8 @@ export async function collectSiteContent(sitePath, options = {}) {
2821
2685
  const siteLayout = normalizeLayoutConfig(siteConfig.layout)
2822
2686
 
2823
2687
  // Recursively collect all pages
2824
- let { pages, assetCollection, iconCollection, notFound, versionedScopes } =
2825
- await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, null, rootContentMode, mounts, siteLayout)
2688
+ let { pages, assetCollection, iconCollection, notFound } =
2689
+ await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, rootContentMode, mounts, siteLayout)
2826
2690
 
2827
2691
  // The layout sections' assets and icons, beside the pages'.
2828
2692
  assetCollection = mergeAssetCollections(assetCollection, layoutAssets)
@@ -2872,10 +2736,11 @@ export async function collectSiteContent(sitePath, options = {}) {
2872
2736
  }
2873
2737
  }
2874
2738
 
2739
+ warnOfDuplicatePageIds(pages)
2740
+
2875
2741
  // Compute parent route for each page (hierarchy declaration), by the one parent rule
2876
- // (`parentRouteOf`) — so the parent declared here is the one every lane derives, past a
2877
- // version folder included. This runs once at build time so runtime doesn't need to
2878
- // re-derive hierarchy.
2742
+ // (`parentRouteOf`) — so the parent declared here is the one every lane derives. This runs
2743
+ // once at build time so runtime doesn't need to re-derive hierarchy.
2879
2744
  const pageRouteMap = new Map()
2880
2745
  for (const page of pages) {
2881
2746
  pageRouteMap.set(page.route, page)
@@ -2917,8 +2782,6 @@ export async function collectSiteContent(sitePath, options = {}) {
2917
2782
  console.log(`[content-collector] Found ${iconManifest.count} icon references from ${iconManifest.families.length} families: ${iconManifest.families.join(', ')}`)
2918
2783
  }
2919
2784
 
2920
- // Convert versionedScopes Map to plain object for JSON serialization
2921
- const versionedScopesObj = Object.fromEntries(versionedScopes)
2922
2785
 
2923
2786
  // Compile per-page `slug:` maps into config.i18n.routeTranslations
2924
2787
  // (canonical route → per-locale display route). Producer-only: the runtime
@@ -3063,8 +2926,6 @@ export async function collectSiteContent(sitePath, options = {}) {
3063
2926
  // No cascade to resolve: this slot is root-level only, so its own flag is
3064
2927
  // the only one that can apply.
3065
2928
  notFound: dropUnpublished ? (notFound?.hidden ? null : withoutHiddenSections(notFound)) : notFound,
3066
- // Versioned scopes: route → { versions, latestId }
3067
- versionedScopes: versionedScopesObj,
3068
2929
  assets: assetCollection.assets,
3069
2930
  hasExplicitPoster: assetCollection.hasExplicitPoster,
3070
2931
  // Icon manifest for preloading
@@ -3226,7 +3087,10 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
3226
3087
  */
3227
3088
  function orderFolders(folders, parentPages) {
3228
3089
  const sorted = [...folders].sort(
3229
- (a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || compareFilenames(a.dirName, b.dirName)
3090
+ (a, b) =>
3091
+ (a.order ?? Infinity) - (b.order ?? Infinity) ||
3092
+ versionFoldersLast(a.dirName, b.dirName) ||
3093
+ compareFilenames(a.dirName, b.dirName)
3230
3094
  )
3231
3095
  const parsed = Array.isArray(parentPages) ? parseWildcardArray(parentPages) : null
3232
3096
  return parsed && parsed.mode !== 'all' ? applyWildcardOrder(sorted, parsed) : sorted
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Two pages with one `id:` — a `page:` link names one of them, and which one depends on the order
3
+ * the site lists them in, so a link can lead to the wrong page with nothing to say so. Ids must be
4
+ * unique across a site (`page-id-uniqueness`), and copying a folder of pages is how they stop being:
5
+ * the id travels with the copy.
6
+ *
7
+ * @param {Array<{id?: string|null, route: string}>} pages
8
+ * @returns {Array<{id: string, routes: string[]}>} what it warned about
9
+ */
10
+ export function warnOfDuplicatePageIds(pages) {
11
+ const routesOf = new Map()
12
+ for (const { id, route } of pages) {
13
+ if (id === null || id === undefined || id === '') continue
14
+ routesOf.set(id, [...(routesOf.get(id) ?? []), route])
15
+ }
16
+ const duplicates = [...routesOf]
17
+ .filter(([, routes]) => routes.length > 1)
18
+ .map(([id, routes]) => ({ id, routes }))
19
+ for (const { id, routes } of duplicates) {
20
+ console.warn(
21
+ `[uniweb] Page id "${id}" is on ${routes.length} pages: ${routes.join(', ')}. ` +
22
+ `A \`page:${id}\` link leads to only one of them. Give each its own id, or remove the id and link by path.`
23
+ )
24
+ }
25
+ return duplicates
26
+ }
package/src/site/index.js CHANGED
@@ -15,6 +15,7 @@ export { DEV_PORT_ENV, DEV_RECORD_ENV, runningDevServer, stopDevServer } from '.
15
15
  // Where a statically built site lives, as its deploy target or author states it (`./site-address.js`).
16
16
  export { ORIGIN_ENV, refuseUnreadableAddress } from './site-address.js'
17
17
  export { collectSiteContent, mountEntriesOf } from './content-collector.js'
18
+ export { addVersion } from './add-version.js'
18
19
  // The favicon a build links when site.yml names none, for `uniweb doctor` (`./favicon.js`).
19
20
  export { findPublicFavicon } from './favicon.js'
20
21
  // The `agents:` vocabulary lives in @uniweb/projections (which owns the block);
package/src/uwx/site.js CHANGED
@@ -40,8 +40,7 @@
40
40
  // they ride under their parent section's `$children` (page_sections is
41
41
  // self_nesting), via the same `processNesting` the normal build uses.
42
42
  //
43
- // v0 scope (stated, not silent): versioned scopes, and media/asset bytes
44
- // (favicon/assets — carried out of band). Folder-mode `.md`-as-pages and
43
+ // v0 scope (stated, not silent): media/asset bytes (favicon/assets — carried out of band). Folder-mode `.md`-as-pages and
45
44
  // `paths: { pages/<segment> }` mounts are carried since 2026-10-23, read by the
46
45
  // build's own rules; a pull leaves those pages alone (`git-authored.js`).
47
46
 
@@ -83,6 +82,7 @@ import { resolveDefaultLocale, validateLanguageConfig, queryDataUrl } from '@uni
83
82
  import { emitEntitySyncPackage } from './entity-document.js'
84
83
  import { locateSectionMedia, siteTree } from './located-media.js'
85
84
  import { mapPageRefs, pageRefIndex, pageRefPages, storedPageRef } from './page-refs.js'
85
+ import { warnOfDuplicatePageIds } from '../site/duplicate-page-ids.js'
86
86
  import { readKept, restoreKept, contextKey, loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent, isProseMirrorDoc, plainTextTargets } from './locale-sync.js'
87
87
  import { unwrapLocalized } from './backfill.js'
88
88
  import { loadFreeformTranslation } from '../i18n/freeform.js'
@@ -542,8 +542,7 @@ const CATCH_ALL_MARKER = '...path'
542
542
  // `multi` section is read as new (inserted, stored counterpart deleted). See
543
543
  // the IDENTITY note in the file header and `site-diff.js`.
544
544
  //
545
- // v0 deferrals: versioned scopes, and media/asset bytes (favicon/assets, carried
546
- // out of band). `@`-prefix `nest:` hierarchy, folder-mode `.md`-as-pages and
545
+ // v0 deferral: media/asset bytes (favicon/assets, carried out of band). `@`-prefix `nest:` hierarchy, folder-mode `.md`-as-pages and
547
546
  // `paths: { pages/<segment> }` mounts are NOT deferred — each is read here by the
548
547
  // build's own rule (folder-mode pages and mounts since 2026-10-23).
549
548
  // ===========================================================================
@@ -1725,7 +1724,9 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
1725
1724
 
1726
1725
  // ⭐ A link to a page is stored by the page's id where it has one (`page-refs.js`), so it
1727
1726
  // survives a rename in an editor, and a pull writes it back as the path a file shows.
1728
- const refIndex = pageRefIndex(pageRefPages(pages, sourceLocale, buildRouteOf))
1727
+ const refPages = pageRefPages(pages, sourceLocale, buildRouteOf)
1728
+ warnOfDuplicatePageIds(refPages)
1729
+ const refIndex = pageRefIndex(refPages)
1729
1730
  mapPageRefs({ pages, layoutSections }, (ref) => storedPageRef(ref, refIndex))
1730
1731
 
1731
1732
  // Collection DECLARATIONS — the merged collections.yml + site.yml::collections