@uniweb/build 1.13.10 → 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.
@@ -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)
188
- }
189
-
190
- /**
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 }
194
- */
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
- }
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
+ )
208
192
  }
209
193
 
210
194
  /**
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
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.
214
197
  */
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
  }
@@ -806,6 +750,34 @@ export function folderModePageFiles(entries, orderConfig) {
806
750
  }
807
751
  }
808
752
 
753
+ /**
754
+ * A folder-mode level's children in one order: its `.md` pages, then its folders, each in the order
755
+ * it already has, with its `pages:` over both, since that is one list. Shared by the build's walk
756
+ * and the push's. ⛔ Until 2026-11-01 each kept to its own side, so `pages: [a, guides, b]` listed
757
+ * `a`, `b`, `guides`, with no word about it.
758
+ *
759
+ * Sorted by rank, not picked by name, so a file and a folder of one name both stay.
760
+ *
761
+ * @template {{ name: string }} T
762
+ * @param {T[]} files
763
+ * @param {T[]} folders
764
+ * @param {{ pages?: Array }} [orderConfig] - the level's own config
765
+ * @returns {T[]}
766
+ */
767
+ export function folderModeChildren(files, folders, orderConfig) {
768
+ const children = [...files, ...folders]
769
+ const parsed = Array.isArray(orderConfig?.pages) ? parseWildcardArray(orderConfig.pages) : null
770
+ if (!parsed || parsed.mode === 'all') return children
771
+ const before = parsed.before.map(extractItemName).filter(Boolean)
772
+ const after = parsed.after.map(extractItemName).filter(Boolean)
773
+ const rank = new Map([
774
+ ...before.map((name, i) => [name, i]),
775
+ ...after.map((name, i) => [name, before.length + 1 + i])
776
+ ])
777
+ const rankOf = (child) => rank.get(child.name) ?? before.length
778
+ return children.sort((a, b) => rankOf(a) - rankOf(b))
779
+ }
780
+
809
781
  /**
810
782
  * Parse numeric prefix from filename (e.g., "1-hero.md" → { prefix: "1", name: "hero" })
811
783
  * Supports:
@@ -1093,9 +1065,6 @@ async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
1093
1065
  lastModified: fileStat.mtime?.toISOString() || null,
1094
1066
  isDynamic: false,
1095
1067
  paramName: null,
1096
- version: null,
1097
- versionMeta: null,
1098
- versionScope: null,
1099
1068
  // The file IS the page, so its `hidden: true` drafts the page — left out of a published
1100
1069
  // build, kept in dev — rather than leaving a page with no section (2026-09-28).
1101
1070
  hidden: section.hidden === true,
@@ -1421,7 +1390,6 @@ async function processExplicitSections(sectionsConfig, pagePath, siteRoot, paren
1421
1390
  * @param {boolean} options.isIndex - Whether this page is the index for its parent route
1422
1391
  * @param {string} options.parentRoute - The parent route (e.g., '/' or '/docs')
1423
1392
  * @param {Object} options.parentFetch - Parent page's fetch config (for dynamic routes)
1424
- * @param {Object} options.versionContext - Version context from parent { version, versionMeta, scope }
1425
1393
  * @returns {Object} Page data with assets manifest
1426
1394
  */
1427
1395
  /**
@@ -1463,7 +1431,7 @@ function mergeLayoutConfig(inherited, own) {
1463
1431
  return { ...(inherited || {}), ...(own || {}) }
1464
1432
  }
1465
1433
 
1466
- 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 } = {}) {
1467
1435
  const pageConfig = await readYamlFile(join(pagePath, 'page.yml'))
1468
1436
 
1469
1437
  // Note: We no longer skip hidden pages here - they still exist as valid pages,
@@ -1795,11 +1763,6 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
1795
1763
  isDynamic,
1796
1764
  paramName, // e.g., "slug" from [slug]; a nested page's ancestor's
1797
1765
 
1798
- // Version metadata (if within a versioned section)
1799
- version: versionContext?.version || null,
1800
- versionMeta: versionContext?.versionMeta || null,
1801
- versionScope: versionContext?.scope || null,
1802
-
1803
1766
  // Navigation options
1804
1767
  hidden: pageConfig.hidden || false, // Hide from all navigation
1805
1768
  hideIn: normalizeHideIn(pageConfig), // Named nav areas to suppress this page from
@@ -1900,8 +1863,7 @@ function declaredHomepage(config) {
1900
1863
  /**
1901
1864
  * The homepage a level's order config names. The root's was already decided across
1902
1865
  * its two configs, and arrives as `homepage` (`rootOrderConfig`); any other level
1903
- * that promotes one — a folder promoted to `/`, the latest version of a scope at the
1904
- * root — names it in its own config.
1866
+ * that promotes one, a folder promoted to `/`, names it in its own config.
1905
1867
  */
1906
1868
  function homepageOf(orderConfig) {
1907
1869
  return orderConfig && 'homepage' in orderConfig ? orderConfig.homepage : declaredHomepage(orderConfig)
@@ -1970,7 +1932,7 @@ function determineIndexPage(orderConfig, availableFolders) {
1970
1932
  const orderA = a.order ?? Infinity
1971
1933
  const orderB = b.order ?? Infinity
1972
1934
  if (orderA !== orderB) return orderA - orderB
1973
- return a.name.localeCompare(b.name)
1935
+ return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
1974
1936
  })
1975
1937
 
1976
1938
  return sorted[0].name
@@ -1984,11 +1946,10 @@ function determineIndexPage(orderConfig, availableFolders) {
1984
1946
  * @param {string} siteRoot - Site root directory for asset resolution
1985
1947
  * @param {Object} orderConfig - { pages: [...], index: 'name', order: [...] } from parent's config
1986
1948
  * @param {Object} parentFetch - Parent page's fetch config (for dynamic child routes)
1987
- * @param {Object} versionContext - Version context from parent { version, versionMeta }
1988
1949
  * @param {string} contentMode - 'sections' (default) or 'pages' (md files are child pages)
1989
- * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound, versionedScopes }
1950
+ * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound }
1990
1951
  */
1991
- 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) {
1992
1953
  const entries = await readdir(dirPath)
1993
1954
  const pages = []
1994
1955
  let assetCollection = {
@@ -2000,7 +1961,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2000
1961
  bySource: new Map()
2001
1962
  }
2002
1963
  let notFound = null
2003
- const versionedScopes = new Map() // scope route → versionMeta
2004
1964
 
2005
1965
  // First pass: discover all page folders and read their config.
2006
1966
  //
@@ -2055,7 +2015,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2055
2015
  const orderA = a.order ?? Infinity
2056
2016
  const orderB = b.order ?? Infinity
2057
2017
  if (orderA !== orderB) return orderA - orderB
2058
- return a.name.localeCompare(b.name)
2018
+ return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
2059
2019
  })
2060
2020
 
2061
2021
  // Apply ordering: pages: (wildcard-aware) > order: [array] (backward compat) > default
@@ -2078,56 +2038,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2078
2038
  orderedFolders = pageFolders
2079
2039
  }
2080
2040
 
2081
- // Check if this directory contains version folders (versioned section)
2082
- const folderNames = orderedFolders.map(f => f.name)
2083
- const detectedVersions = detectVersions(folderNames)
2084
-
2085
- // If versioned section, handle version folders specially (always page mode)
2086
- if (detectedVersions && !versionContext) {
2087
- const parentConfig = await readYamlFile(join(dirPath, 'page.yml'))
2088
- const versionMeta = buildVersionMetadata(detectedVersions, parentConfig)
2089
- versionedScopes.set(parentRoute, versionMeta)
2090
-
2091
- for (const folder of orderedFolders) {
2092
- const { name: entry, path: entryPath, childOrderConfig, childLayout } = folder
2093
-
2094
- if (isVersionFolder(entry)) {
2095
- const versionInfo = versionMeta.versions.find(v => v.id === entry)
2096
- const isLatest = versionInfo?.latest || false
2097
- const versionRoute = isLatest
2098
- ? parentRoute
2099
- : parentRoute === '/'
2100
- ? `/${entry}`
2101
- : `${parentRoute}/${entry}`
2102
-
2103
- const subResult = await collectPagesRecursive(
2104
- entryPath, versionRoute, siteRoot, childOrderConfig, parentFetch,
2105
- { version: versionInfo, versionMeta, scope: parentRoute },
2106
- 'sections', null, mergeLayoutConfig(parentLayout, childLayout)
2107
- )
2108
-
2109
- pages.push(...subResult.pages)
2110
- assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2111
- iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2112
- for (const [scope, meta] of subResult.versionedScopes) {
2113
- versionedScopes.set(scope, meta)
2114
- }
2115
- } else {
2116
- const result = await processPage(entryPath, entry, siteRoot, {
2117
- isIndex: false, parentRoute, parentFetch,
2118
- inheritedLayout: mergeLayoutConfig(parentLayout, childLayout)
2119
- })
2120
- if (result) {
2121
- pages.push(result.page)
2122
- assetCollection = mergeAssetCollections(assetCollection, result.assetCollection)
2123
- iconCollection = mergeIconCollections(iconCollection, result.iconCollection)
2124
- }
2125
- }
2126
- }
2127
-
2128
- return { pages, assetCollection, iconCollection, notFound, versionedScopes }
2129
- }
2130
-
2131
2041
  // --- Pages mode: .md files are child pages ---
2132
2042
  if (contentMode === 'pages') {
2133
2043
  // Each .md file is a page, in the order `folderModePageFiles` gives — the one the push sends
@@ -2147,37 +2057,38 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2147
2057
  indexName = homepageOf(orderConfig) ?? null
2148
2058
  }
2149
2059
 
2150
- // Add md-file-pages
2151
- for (const { name, result } of orderedMdPages) {
2152
- const { page, assetCollection: pageAssets, iconCollection: pageIcons } = result
2153
- assetCollection = mergeAssetCollections(assetCollection, pageAssets)
2154
- iconCollection = mergeIconCollections(iconCollection, pageIcons)
2155
-
2156
- // Handle index: promote to parent route
2157
- if (name === indexName) {
2158
- page.isIndex = true
2159
- page.sourcePath = page.route
2160
- page.route = parentRoute
2161
- }
2060
+ // The level's md-file-pages and subdirectories, in one order
2061
+ for (const child of folderModeChildren(orderedMdPages, orderedFolders, orderConfig)) {
2062
+ if (child.result) {
2063
+ const { name, result } = child
2064
+ const { page, assetCollection: pageAssets, iconCollection: pageIcons } = result
2065
+ assetCollection = mergeAssetCollections(assetCollection, pageAssets)
2066
+ iconCollection = mergeIconCollections(iconCollection, pageIcons)
2162
2067
 
2163
- // Inherit the layout from the folder / site cascade.
2164
- //
2165
- // ⭐ THE WHOLE OBJECT, not just the name. `processFileAsPage` (folder-mode
2166
- // `.md`-as-pages) takes no layout argument, so this post-hoc merge is where
2167
- // the cascade reaches these pages at all — the threaded path above covers
2168
- // every other kind. Until 2026-09-09 it patched `name` only, which is why a
2169
- // folder or site `hide:` never reached a folder-mode page.
2170
- //
2171
- // `normalizeLayoutConfig` first so the page's own record has no undefined
2172
- // keys to shadow an inherited value through the spread.
2173
- page.layout = mergeLayoutConfig(parentLayout, normalizeLayoutConfig(page.layout))
2174
-
2175
- pages.push(page)
2176
- }
2068
+ // Handle index: promote to parent route
2069
+ if (name === indexName) {
2070
+ page.isIndex = true
2071
+ page.sourcePath = page.route
2072
+ page.route = parentRoute
2073
+ }
2177
2074
 
2178
- // Process subdirectories
2179
- for (const folder of orderedFolders) {
2180
- const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = folder
2075
+ // Inherit the layout from the folder / site cascade.
2076
+ //
2077
+ // ⭐ THE WHOLE OBJECT, not just the name. `processFileAsPage` (folder-mode
2078
+ // `.md`-as-pages) takes no layout argument, so this post-hoc merge is where
2079
+ // the cascade reaches these pages at all — the threaded path above covers
2080
+ // every other kind. Until 2026-09-09 it patched `name` only, which is why a
2081
+ // folder or site `hide:` never reached a folder-mode page.
2082
+ //
2083
+ // `normalizeLayoutConfig` first so the page's own record has no undefined
2084
+ // keys to shadow an inherited value through the spread.
2085
+ page.layout = mergeLayoutConfig(parentLayout, normalizeLayoutConfig(page.layout))
2086
+
2087
+ pages.push(page)
2088
+ continue
2089
+ }
2090
+
2091
+ const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = child
2181
2092
  assertRouteFolder(entry, parentRoute)
2182
2093
  const isIndex = entry === indexName
2183
2094
  const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
@@ -2185,7 +2096,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2185
2096
  if (dirMode === 'sections') {
2186
2097
  // Subdirectory overrides to page mode — process normally
2187
2098
  const result = await processPage(entryPath, entry, siteRoot, {
2188
- isIndex, parentRoute, parentFetch, versionContext,
2099
+ isIndex, parentRoute, parentFetch,
2189
2100
  inheritedLayout: effectiveLayout
2190
2101
  })
2191
2102
 
@@ -2216,13 +2127,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2216
2127
  const childParentRoute = isIndex ? parentRoute : page.route
2217
2128
  const childFetch = page.fetch || parentFetch
2218
2129
  const childContentMode = childMode
2219
- 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)
2220
2131
  pages.push(...subResult.pages)
2221
2132
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2222
2133
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2223
- for (const [scope, meta] of subResult.versionedScopes) {
2224
- versionedScopes.set(scope, meta)
2225
- }
2226
2134
  }
2227
2135
  } else {
2228
2136
  // Container directory in folder mode — create minimal page, recurse
@@ -2243,9 +2151,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2243
2151
  lastModified: null,
2244
2152
  isDynamic: false,
2245
2153
  paramName: null,
2246
- version: versionContext?.version || null,
2247
- versionMeta: versionContext?.versionMeta || null,
2248
- versionScope: versionContext?.scope || null,
2249
2154
  hidden: dirConfig.hidden || false,
2250
2155
  hideIn: normalizeHideIn(dirConfig),
2251
2156
  ...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
@@ -2273,13 +2178,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2273
2178
  // Recurse in folder mode — pass container's own fetch config (or fall back to parent's)
2274
2179
  const childDirPath = mounts?.get(entry) || entryPath
2275
2180
  const containerFetch = containerPage.fetch || parentFetch
2276
- 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)
2277
2182
  pages.push(...subResult.pages)
2278
2183
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2279
2184
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2280
- for (const [scope, meta] of subResult.versionedScopes) {
2281
- versionedScopes.set(scope, meta)
2282
- }
2283
2185
  }
2284
2186
  }
2285
2187
 
@@ -2297,7 +2199,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2297
2199
  }
2298
2200
  }
2299
2201
 
2300
- return { pages, assetCollection, iconCollection, notFound, versionedScopes }
2202
+ return { pages, assetCollection, iconCollection, notFound }
2301
2203
  }
2302
2204
 
2303
2205
  // --- Sections mode (default): existing behavior ---
@@ -2340,9 +2242,6 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2340
2242
  lastModified: null,
2341
2243
  isDynamic: false,
2342
2244
  paramName: null,
2343
- version: versionContext?.version || null,
2344
- versionMeta: versionContext?.versionMeta || null,
2345
- versionScope: versionContext?.scope || null,
2346
2245
  hidden: dirConfig.hidden || false,
2347
2246
  hideIn: normalizeHideIn(dirConfig),
2348
2247
  ...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
@@ -2375,17 +2274,14 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2375
2274
  // container above passes it.
2376
2275
  const childDirPath = mounts?.get(entry) || entryPath
2377
2276
  const containerFetch = containerPage.fetch || parentFetch
2378
- 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)
2379
2278
  pages.push(...subResult.pages)
2380
2279
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2381
2280
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2382
- for (const [scope, meta] of subResult.versionedScopes) {
2383
- versionedScopes.set(scope, meta)
2384
- }
2385
2281
  } else {
2386
2282
  // Sections mode — process directory as a page (existing behavior)
2387
2283
  const result = await processPage(entryPath, entry, siteRoot, {
2388
- isIndex, parentRoute, parentFetch, versionContext,
2284
+ isIndex, parentRoute, parentFetch,
2389
2285
  inheritedLayout: effectiveLayout
2390
2286
  })
2391
2287
 
@@ -2418,13 +2314,10 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2418
2314
  : page.route
2419
2315
  const childFetch = page.fetch || parentFetch
2420
2316
  const childContentMode = childMode
2421
- 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)
2422
2318
  pages.push(...subResult.pages)
2423
2319
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2424
2320
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
2425
- for (const [scope, meta] of subResult.versionedScopes) {
2426
- versionedScopes.set(scope, meta)
2427
- }
2428
2321
  }
2429
2322
  }
2430
2323
  }
@@ -2443,7 +2336,7 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2443
2336
  }
2444
2337
  }
2445
2338
 
2446
- return { pages, assetCollection, iconCollection, notFound, versionedScopes }
2339
+ return { pages, assetCollection, iconCollection, notFound }
2447
2340
  }
2448
2341
 
2449
2342
  /**
@@ -2792,8 +2685,8 @@ export async function collectSiteContent(sitePath, options = {}) {
2792
2685
  const siteLayout = normalizeLayoutConfig(siteConfig.layout)
2793
2686
 
2794
2687
  // Recursively collect all pages
2795
- let { pages, assetCollection, iconCollection, notFound, versionedScopes } =
2796
- 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)
2797
2690
 
2798
2691
  // The layout sections' assets and icons, beside the pages'.
2799
2692
  assetCollection = mergeAssetCollections(assetCollection, layoutAssets)
@@ -2843,10 +2736,11 @@ export async function collectSiteContent(sitePath, options = {}) {
2843
2736
  }
2844
2737
  }
2845
2738
 
2739
+ warnOfDuplicatePageIds(pages)
2740
+
2846
2741
  // Compute parent route for each page (hierarchy declaration), by the one parent rule
2847
- // (`parentRouteOf`) — so the parent declared here is the one every lane derives, past a
2848
- // version folder included. This runs once at build time so runtime doesn't need to
2849
- // 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.
2850
2744
  const pageRouteMap = new Map()
2851
2745
  for (const page of pages) {
2852
2746
  pageRouteMap.set(page.route, page)
@@ -2888,8 +2782,6 @@ export async function collectSiteContent(sitePath, options = {}) {
2888
2782
  console.log(`[content-collector] Found ${iconManifest.count} icon references from ${iconManifest.families.length} families: ${iconManifest.families.join(', ')}`)
2889
2783
  }
2890
2784
 
2891
- // Convert versionedScopes Map to plain object for JSON serialization
2892
- const versionedScopesObj = Object.fromEntries(versionedScopes)
2893
2785
 
2894
2786
  // Compile per-page `slug:` maps into config.i18n.routeTranslations
2895
2787
  // (canonical route → per-locale display route). Producer-only: the runtime
@@ -3034,8 +2926,6 @@ export async function collectSiteContent(sitePath, options = {}) {
3034
2926
  // No cascade to resolve: this slot is root-level only, so its own flag is
3035
2927
  // the only one that can apply.
3036
2928
  notFound: dropUnpublished ? (notFound?.hidden ? null : withoutHiddenSections(notFound)) : notFound,
3037
- // Versioned scopes: route → { versions, latestId }
3038
- versionedScopes: versionedScopesObj,
3039
2929
  assets: assetCollection.assets,
3040
2930
  hasExplicitPoster: assetCollection.hasExplicitPoster,
3041
2931
  // Icon manifest for preloading
@@ -3197,7 +3087,10 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
3197
3087
  */
3198
3088
  function orderFolders(folders, parentPages) {
3199
3089
  const sorted = [...folders].sort(
3200
- (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)
3201
3094
  )
3202
3095
  const parsed = Array.isArray(parentPages) ? parseWildcardArray(parentPages) : null
3203
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);
@@ -184,6 +184,11 @@ export function collectUnitUuids(doc, sourceLocale) {
184
184
  * is the dangerous case — see `collectUnitUuids` — and the caller is responsible for
185
185
  * not pushing blind (the backend also refuses an all-blank `multi` section).
186
186
  *
187
+ * ⭐ One directory is one page, whichever of its two files declares it, so a page moved between
188
+ * `page.yml` and `folder.yml` keeps its identity. ⛔ Until 2026-11-01 the map was read by the file's
189
+ * name alone, so the move pushed a new page beside the stored one, under its slug, and the backend
190
+ * refused it (409, `unique_field`) after the publish had already released the foundation.
191
+ *
187
192
  * @returns {{ stamped: number, unknown: number }}
188
193
  */
189
194
  export function stampUnitUuids(doc, pathToUuid = {}, sourceLocale) {
@@ -191,7 +196,11 @@ export function stampUnitUuids(doc, pathToUuid = {}, sourceLocale) {
191
196
  let unknown = 0
192
197
  const seen = new Set()
193
198
  const collisions = []
194
- walkSiteUnits(doc, (path, record) => {
199
+ const otherPageFile = (path) =>
200
+ path.endsWith('/page.yml')
201
+ ? `${path.slice(0, -'page.yml'.length)}folder.yml`
202
+ : `${path.slice(0, -'folder.yml'.length)}page.yml`
203
+ walkSiteUnits(doc, (path, record, kind) => {
195
204
  // Two records can resolve to ONE path when their stable ids collide — most
196
205
  // easily `1-hero.md` and `hero.md` in the same page dir, since the numeric
197
206
  // prefix is stripped. Stamping both with the same uuid produces a package the
@@ -206,7 +215,7 @@ export function stampUnitUuids(doc, pathToUuid = {}, sourceLocale) {
206
215
  return
207
216
  }
208
217
  seen.add(path)
209
- const uuid = pathToUuid[path]
218
+ const uuid = pathToUuid[path] || (kind === 'page' ? pathToUuid[otherPageFile(path)] : undefined)
210
219
  if (uuid) {
211
220
  record.$uuid = uuid
212
221
  stamped++