@uniweb/build 1.15.5 → 1.16.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.15.5",
3
+ "version": "1.16.0",
4
4
  "description": "Build tooling for the Uniweb Component Web Platform",
5
5
  "type": "module",
6
6
  "exports": {
@@ -56,11 +56,11 @@
56
56
  "js-yaml": "^4.3.2",
57
57
  "sharp": "^0.35.5",
58
58
  "yaml": "^2.5.0",
59
- "@uniweb/content-reader": "~1.5.8",
59
+ "@uniweb/content-reader": "~1.5.9",
60
+ "@uniweb/content-writer": "~1.3.1",
60
61
  "@uniweb/projections": "~1.2.11",
61
- "@uniweb/schemas": "~1.6.7",
62
+ "@uniweb/schemas": "~1.6.8",
62
63
  "@uniweb/semantic-parser": "~1.13.2",
63
- "@uniweb/content-writer": "~1.3.1",
64
64
  "@uniweb/theming": "~1.2.1"
65
65
  },
66
66
  "optionalDependencies": {
@@ -11,6 +11,9 @@
11
11
  */
12
12
 
13
13
  export { collectSiteContent, pageSectionFiles } from '../site/content-collector.js'
14
+ // The one rule for a leading number that orders a name (`1-hero`, `2.5-x`, `404`), for a headless
15
+ // caller that lists a folder as the collector reads it (`@uniweb/unipress`'s `materialize.js`).
16
+ export { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
14
17
 
15
18
  // Query + fetch resolution. Pure functions on the clean dep
16
19
  // chain — re-exported here so headless callers (unipress, sidecars)
@@ -20,19 +20,51 @@
20
20
  * Nothing is written until the whole copy is planned, so a refusal leaves no trace.
21
21
  */
22
22
 
23
- import { existsSync, statSync } from 'node:fs'
23
+ import { existsSync, readdirSync, statSync } from 'node:fs'
24
24
  import { copyFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
25
25
  import { dirname, join, posix, resolve, relative } from 'node:path'
26
26
  import yaml from 'js-yaml'
27
27
  import { isVersionFolder } from '@uniweb/projections/versions'
28
28
  import { YAML_OPTIONS } from '../utils/yaml-schema.js'
29
29
  import { collectSiteContent, mountEntriesOf, readFolderConfig, readYamlFile, rootOrderConfig } from './content-collector.js'
30
+ import { parseNumericPrefix } from '../utils/numeric-prefix.js'
30
31
 
31
32
  const routeKey = (route) => String(route).replace(/^\/+/, '').replace(/\/+$/, '')
32
33
  const CONFIG_FILES = new Set(['page.yml', 'folder.yml'])
33
34
  // What of the docs folder's own config still describes the copy. The rest names the folder itself.
34
35
  const CARRIED_KEYS = ['pages', 'sections', 'nest', 'redirect']
35
36
 
37
+ // A page's name in a route: its folder's or file's, less the number that orders it (`2-guide` is `guide`).
38
+ const pageNameOf = (entry) => parseNumericPrefix(entry).name || entry
39
+
40
+ /**
41
+ * The folder holding a route's pages, as a path under `pages/` — each segment the folder whose page
42
+ * name it is, a mount's key where the first one is a mount — or null where no folder holds it.
43
+ */
44
+ function folderOfRoute(segments, { pagesDir, mounts }) {
45
+ const named = (dir, segment) => {
46
+ try {
47
+ return readdirSync(dir, { withFileTypes: true }).find((e) => e.isDirectory() && (e.name === segment || pageNameOf(e.name) === segment))?.name ?? null
48
+ } catch {
49
+ return null
50
+ }
51
+ }
52
+ const out = []
53
+ let dir = pagesDir
54
+ for (const [i, segment] of segments.entries()) {
55
+ if (i === 0 && mounts.has(segment)) {
56
+ out.push(segment)
57
+ dir = mounts.get(segment)
58
+ continue
59
+ }
60
+ const hit = named(dir, segment)
61
+ if (!hit) return null
62
+ out.push(hit)
63
+ dir = join(dir, hit)
64
+ }
65
+ return out.join('/')
66
+ }
67
+
36
68
  /**
37
69
  * The folder holding the docs, as a path under `pages/`.
38
70
  *
@@ -52,8 +84,11 @@ function findFolder(named, { pages, pagesDir, mounts, homepage }) {
52
84
  const segments = route.split('/').filter(Boolean)
53
85
  const at = segments.findIndex(isVersionFolder)
54
86
  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)
87
+ const above = segments.slice(0, at)
88
+ // A homepage's own pages sit at the root, so a version there is in the homepage's folder.
89
+ const inHomepage = !above.length && homepage && folderOfRoute([homepage, segments[0]], { pagesDir, mounts })
90
+ const folder = inHomepage ? folderOfRoute([homepage], { pagesDir, mounts }) : folderOfRoute(above, { pagesDir, mounts })
91
+ holding.add(folder ?? (inHomepage ? homepage : above.join('/')))
57
92
  }
58
93
  if (holding.size === 1) return [...holding][0]
59
94
  if (holding.size > 1) {
@@ -246,15 +281,17 @@ export async function addVersion(siteRoot, { name, folder: named, label, keepInS
246
281
  throw new Error(`pages/${posix.join(folder, name)} already exists. To freeze the docs again, name a new version.`)
247
282
  }
248
283
 
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('/')}`
284
+ // Where the folder's pages are, by their names as pages. A folder promoted to the homepage puts its
285
+ // pages at the root.
286
+ const routeSegments = segments.map(pageNameOf)
287
+ const isHomepage = routeSegments[0] === homepage
288
+ const scope = `/${(isHomepage ? routeSegments.slice(1) : routeSegments).join('/')}`
252
289
  const prefix = scope === '/' ? '' : scope
253
290
  const versionRoute = `${prefix}/${name}`
254
291
  const names = new Set(
255
292
  (await readdir(dir, { withFileTypes: true }))
256
293
  .filter((entry) => entry.isDirectory() || entry.name.endsWith('.md'))
257
- .map((entry) => entry.name.replace(/^\d+(\.\d+)*-/, '').replace(/\.md$/, ''))
294
+ .map((entry) => pageNameOf(entry.name.replace(/\.md$/, '')))
258
295
  .filter((entry) => !isVersionFolder(entry) && !(folder === '' && entry === '404'))
259
296
  )
260
297
 
@@ -26,6 +26,7 @@ import { isSectionKey } from '@uniweb/schemas/section'
26
26
  import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
27
27
  import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
28
28
  import { readLayoutFolder, DEFAULT_LAYOUT, layoutAreaRoute } from './layout-folder.js'
29
+ import { mountEntriesOf } from './mount-entries.js'
29
30
  import { basename, join, parse, relative, resolve, sep } from 'node:path'
30
31
  import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
31
32
  import yaml from 'js-yaml'
@@ -555,7 +556,7 @@ async function readFolderConfig(dirPath, inheritedMode) {
555
556
  /**
556
557
  * A folder's content mode from its two config files — `readFolderConfig`'s rule, as a pure
557
558
  * function, so a synchronous reader applies the same one: the pull, which must know which pages
558
- * a folder's `.md` files are (`uwx/git-authored.js`).
559
+ * a folder's `.md` files are (`uwx/page-files.js`).
559
560
  *
560
561
  * - a `folder.yml` with keys → folder mode
561
562
  * - else a `page.yml` with keys → page mode
@@ -604,25 +605,8 @@ function mountHasContent(dirPath) {
604
605
  })
605
606
  }
606
607
 
607
- /**
608
- * The `pages/<segment>` keys in a site.yml `paths:` group, unvalidated.
609
- *
610
- * Split out from resolveMounts so the dev server can learn which directories a
611
- * site mounts without re-running resolveMounts' validation — that would repeat
612
- * its warnings on every startup, and the watcher only needs paths. Every reader —
613
- * the collector, the watcher, a pull (`uwx/git-authored.js`) and `uniweb status` among
614
- * them — shares this one definition of what a mount key looks like, so the prefix can never mean
615
- * one thing to one of them and another to the next.
616
- *
617
- * @param {Object} pathsConfig - The paths: object from site.yml
618
- * @returns {Array<[string, string]>} [routeSegment, relativePath] pairs
619
- */
620
- export function mountEntriesOf(pathsConfig) {
621
- if (!pathsConfig || typeof pathsConfig !== 'object') return []
622
- return Object.entries(pathsConfig)
623
- .filter(([key]) => key.startsWith('pages/'))
624
- .map(([key, value]) => [key.slice('pages/'.length), value])
625
- }
608
+ // The one definition of a mount key, a leaf (`./mount-entries.js`), re-exported for its readers here.
609
+ export { mountEntriesOf }
626
610
 
627
611
  /**
628
612
  * Extract page mounts from site.yml paths: config.
@@ -660,6 +644,22 @@ function resolveMounts(pathsConfig, sitePath, pagesPath, { strict = false } = {}
660
644
  )
661
645
  }
662
646
 
647
+ // ⛔ A mount is its folder. `{ path, writable }` was its form for part of 2026-11-04; whether a pull
648
+ // writes into a mount is no setting now, so the object is refused, saying what replaced it.
649
+ if (relativePath !== null && typeof relativePath === 'object' && !Array.isArray(relativePath)) {
650
+ const named = typeof relativePath.path === 'string' && relativePath.path ? relativePath.path : '../docs'
651
+ throw new Error(
652
+ `[content-collector] The mount "pages/${routeSegment}" in site.yml paths is an object. A mount is its folder: \`pages/${routeSegment}: ${named}\`.\n` +
653
+ ` \`writable\` is retired: a pull writes the app's edits into a mounted folder wherever it can merge them — a folder of the site's repository, or of a submodule — and holds them where it cannot.`
654
+ )
655
+ }
656
+ if (typeof relativePath !== 'string' || !relativePath) {
657
+ throw new Error(
658
+ `[content-collector] The mount "pages/${routeSegment}" in site.yml paths names no folder.\n` +
659
+ ` Give it one: \`pages/${routeSegment}: ../docs\`.`
660
+ )
661
+ }
662
+
663
663
  const absolutePath = resolve(sitePath, relativePath)
664
664
 
665
665
  // Check existence
@@ -772,6 +772,30 @@ export function layerMountedFolder(name, local, mounted, contentMode) {
772
772
  return { dirConfig, dirMode, childMode }
773
773
  }
774
774
 
775
+ /**
776
+ * ⛔ A page with a `page.yml` of its own inside folder mode stops a site's build, and with it a push: in
777
+ * folder mode each page is one `.md` file holding one section, so a page whose parent is in folder mode is
778
+ * always that, and the app offers no second section there. A document's content (`document.yml`) is in
779
+ * folder mode by default, and a chapter of several sections is a `page.yml` there, so this is a site's
780
+ * rule only. A page of several sections, or a parametric one,
781
+ * goes outside the folder. ⭐ One rule for the build's walk (`collectPagesRecursive`) and the push's
782
+ * (`uwx/site.js::orderedSubfolders`), so a site that cannot build cannot sync either [Diego, 2026-11-04:
783
+ * "we can agree with framework to forbid the case … We have never seen a need for it"]. ⛔ Until then a
784
+ * `page.yml` there switched its folder back to page mode.
785
+ *
786
+ * @param {string} contentMode - the mode of the level the folder is on
787
+ * @param {string} dirMode - the folder's own, from `layerMountedFolder`
788
+ * @param {string} where - the folder, as the message names it
789
+ */
790
+ export function refusePageInFolderMode(contentMode, dirMode, where) {
791
+ if (contentMode !== 'pages' || dirMode !== 'sections') return
792
+ throw new Error(
793
+ `[uniweb] pages: \`${where}\` has a page.yml of its own inside folder mode, where each page is one \`.md\` ` +
794
+ `file holding one section — a folder.yml above it puts it there. Make it one \`.md\` file, or move it out ` +
795
+ `of the folder. A folder that holds no \`.md\` page of its own can take a page.yml instead of its folder.yml.`
796
+ )
797
+ }
798
+
775
799
  /**
776
800
  * A folder-mode folder's `.md` pages, in the order the build lists them: by filename (numeric
777
801
  * prefix first), then by the folder's own `pages:`. Each name is the page's slug — the filename
@@ -849,10 +873,11 @@ function extractH1(proseMirrorDoc) {
849
873
 
850
874
  /**
851
875
  * Prettify a slug into a human-readable title.
852
- * Strips numeric prefixes, replaces hyphens with spaces, title-cases.
876
+ * Strips a numeric prefix (`parseNumericPrefix`, the one rule), replaces hyphens with spaces, title-cases.
877
+ * ⛔ Until 2026-11-04 it stripped by a rule of its own, so `2.5-setup` was titled "5 Setup".
853
878
  */
854
879
  function prettifySlug(slug) {
855
- const stripped = slug.replace(/^\d+[-.]?\s*/, '')
880
+ const stripped = parseNumericPrefix(slug).name
856
881
  return stripped
857
882
  .split('-')
858
883
  .map(word => word.charAt(0).toUpperCase() + word.slice(1))
@@ -1967,22 +1992,14 @@ function determineIndexPage(orderConfig, availableFolders) {
1967
1992
  const declared = homepageOf(orderConfig)
1968
1993
  if (declared !== undefined) return declared
1969
1994
 
1970
- // 3. Fallback: lowest order value, or first alphabetically
1995
+ // 3. Fallback: the page that comes first, in the order the level's menu lists them (`compareFolders`):
1996
+ // lowest `order:`, then a folder's number, then its name.
1971
1997
  // IMPORTANT: Dynamic route folders (e.g., [slug]) can never be index pages
1972
1998
  // They are templates for dynamic content, not actual navigable pages
1973
1999
  const staticFolders = availableFolders.filter(f => !isDynamicRoute(f.name))
1974
2000
  if (staticFolders.length === 0) return null
1975
2001
 
1976
- const sorted = [...staticFolders].sort((a, b) => {
1977
- // Sort by order (lower first), then alphabetically
1978
- // Pages without explicit order come after ordered pages
1979
- const orderA = a.order ?? Infinity
1980
- const orderB = b.order ?? Infinity
1981
- if (orderA !== orderB) return orderA - orderB
1982
- return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
1983
- })
1984
-
1985
- return sorted[0].name
2002
+ return [...staticFolders].sort(compareFolders)[0].name
1986
2003
  }
1987
2004
 
1988
2005
  /**
@@ -2012,7 +2029,7 @@ function notePagesOfHomepage(pages) {
2012
2029
  * page at its own address, while a push kept the folder as a container at `/`, leading to it.
2013
2030
  * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound }
2014
2031
  */
2015
- async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, contentMode = 'sections', mounts = null, parentLayout = null, isSiteRoot = false) {
2032
+ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, contentMode = 'sections', mounts = null, parentLayout = null, isSiteRoot = false, isSite = true) {
2016
2033
  const entries = await readdir(dirPath)
2017
2034
  const pages = []
2018
2035
  let assetCollection = {
@@ -2053,12 +2070,17 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2053
2070
  const mounted = mountPath ? await readFolderConfig(mountPath, 'pages') : null
2054
2071
  const local = localPath ? await readFolderConfig(localPath, contentMode) : null
2055
2072
  const { dirConfig, dirMode, childMode } = layerMountedFolder(name, local, mounted, contentMode)
2073
+ if (isSite) refusePageInFolderMode(contentMode, dirMode, relative(siteRoot, localPath ?? mountPath))
2056
2074
  if (mountPath && localPath) await warnOfLocalFoldersUnderAMount(localPath, name)
2057
2075
 
2058
2076
  const folderLayout = normalizeLayoutConfig(dirConfig.layout)
2059
2077
 
2060
2078
  pageFolders.push({
2061
- name,
2079
+ // ⭐ ITS NAME AS A PAGE: the folder's, less the number that orders it — `2-about/` is `/about`, as
2080
+ // `1-install.md` is `/install` — on every lane [Diego, 2026-11-04: "The build should drop the number
2081
+ // too"]. ⛔ Until then the build served `2-about/` at `/2-about` while a push sent it as `about`.
2082
+ name: isDynamicRoute(name) ? name : parseNumericPrefix(name).name,
2083
+ dirName: name,
2062
2084
  path: localPath ?? mountPath,
2063
2085
  order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined,
2064
2086
  dirConfig,
@@ -2072,14 +2094,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2072
2094
  })
2073
2095
  }
2074
2096
 
2075
- // Sort page folders by order (ascending), then alphabetically
2076
- // Pages without explicit order come after ordered pages (order ?? Infinity)
2077
- pageFolders.sort((a, b) => {
2078
- const orderA = a.order ?? Infinity
2079
- const orderB = b.order ?? Infinity
2080
- if (orderA !== orderB) return orderA - orderB
2081
- return versionFoldersLast(a.name, b.name) || a.name.localeCompare(b.name)
2082
- })
2097
+ // A level's folders in the order every lane reads them in (`compareFolders`): `order:`, then the
2098
+ // number a folder's name starts with, then its name.
2099
+ pageFolders.sort(compareFolders)
2083
2100
 
2084
2101
  // Apply ordering: pages: (wildcard-aware) > order: [array] (backward compat) > default
2085
2102
  let orderedFolders
@@ -2151,8 +2168,8 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2151
2168
  continue
2152
2169
  }
2153
2170
 
2154
- const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = child
2155
- assertRouteFolder(entry, parentRoute)
2171
+ const { name: entry, dirName, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = child
2172
+ assertRouteFolder(dirName, parentRoute)
2156
2173
  const isIndex = entry === indexName
2157
2174
  const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
2158
2175
 
@@ -2186,11 +2203,11 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2186
2203
  // Recurse into subdirectories (page mode). When the children come from
2187
2204
  // a mount, they are walked in the mount's own mode — it is the mount's
2188
2205
  // tree, and its root config is what declared how its content is shaped.
2189
- const childDirPath = mounts?.get(entry) || entryPath
2206
+ const childDirPath = mounts?.get(dirName) || entryPath
2190
2207
  const childParentRoute = isIndex ? parentRoute : page.route
2191
2208
  const childFetch = page.fetch || parentFetch
2192
2209
  const childContentMode = childMode
2193
- const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout)
2210
+ const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout, false, isSite)
2194
2211
  pages.push(...subResult.pages)
2195
2212
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2196
2213
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2239,9 +2256,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2239
2256
  pages.push(containerPage)
2240
2257
 
2241
2258
  // Recurse in folder mode — pass container's own fetch config (or fall back to parent's)
2242
- const childDirPath = mounts?.get(entry) || entryPath
2259
+ const childDirPath = mounts?.get(dirName) || entryPath
2243
2260
  const containerFetch = containerPage.fetch || parentFetch
2244
- const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout)
2261
+ const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout, false, isSite)
2245
2262
  pages.push(...subResult.pages)
2246
2263
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2247
2264
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2281,8 +2298,8 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2281
2298
 
2282
2299
  // Second pass: process each page folder
2283
2300
  for (const folder of orderedFolders) {
2284
- const { name: entry, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = folder
2285
- assertRouteFolder(entry, parentRoute)
2301
+ const { name: entry, dirName, path: entryPath, dirConfig, dirMode, childMode, childOrderConfig, childLayout } = folder
2302
+ assertRouteFolder(dirName, parentRoute)
2286
2303
  const isIndex = entry === indexPageName
2287
2304
  const effectiveLayout = mergeLayoutConfig(parentLayout, childLayout)
2288
2305
 
@@ -2336,9 +2353,9 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2336
2353
 
2337
2354
  // The container's own fetch config, or the parent's — as the folder-mode
2338
2355
  // container above passes it.
2339
- const childDirPath = mounts?.get(entry) || entryPath
2356
+ const childDirPath = mounts?.get(dirName) || entryPath
2340
2357
  const containerFetch = containerPage.fetch || parentFetch
2341
- const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout)
2358
+ const subResult = await collectPagesRecursive(childDirPath, containerRoute, siteRoot, childOrderConfig, containerFetch, childMode, null, effectiveLayout, false, isSite)
2342
2359
  pages.push(...subResult.pages)
2343
2360
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2344
2361
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2372,13 +2389,13 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
2372
2389
  // walked in the mount's own mode — its root config declared how its
2373
2390
  // content is shaped, and this local stub holds none of that content.
2374
2391
  {
2375
- const childDirPath = mounts?.get(entry) || entryPath
2392
+ const childDirPath = mounts?.get(dirName) || entryPath
2376
2393
  const childParentRoute = isIndex
2377
2394
  ? (hasExplicitOrder ? parentRoute : (page.sourcePath || page.route))
2378
2395
  : page.route
2379
2396
  const childFetch = page.fetch || parentFetch
2380
2397
  const childContentMode = childMode
2381
- const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout)
2398
+ const subResult = await collectPagesRecursive(childDirPath, childParentRoute, siteRoot, childOrderConfig, childFetch, childContentMode, null, effectiveLayout, false, isSite)
2382
2399
  pages.push(...subResult.pages)
2383
2400
  assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
2384
2401
  iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
@@ -2751,7 +2768,7 @@ export async function collectSiteContent(sitePath, options = {}) {
2751
2768
 
2752
2769
  // Recursively collect all pages
2753
2770
  let { pages, assetCollection, iconCollection, notFound } =
2754
- await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, rootContentMode, mounts, siteLayout, true)
2771
+ await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, rootContentMode, mounts, siteLayout, true, profile === CONTENT_PROFILES['site.yml'])
2755
2772
 
2756
2773
  // The layout sections' assets and icons, beside the pages'.
2757
2774
  assetCollection = mergeAssetCollections(assetCollection, layoutAssets)
@@ -3140,26 +3157,29 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
3140
3157
  }
3141
3158
 
3142
3159
  /**
3143
- * One level's pages in the order a push walks them, and a pull reproduces: explicit `order:`, then
3144
- * numeric-prefix filename order, then the parent config's `pages:` list. Shared by the push's walk
3145
- * (`uwx/site.js::orderedSubfolders`) and the pull (`uwx/site-project.js`), so the two cannot
3146
- * disagree on what a level's order is.
3160
+ * Two of a level's page folders, in the order every lane reads them: explicit `order:`, then version
3161
+ * folders after the rest, then the number a folder's name starts with, then its name. The build's walk
3162
+ * (`collectPagesRecursive`) sorts with it, and `orderFolders` below.
3147
3163
  *
3148
- * ⚠️ The build's own page-folder sort (`collectPagesRecursive`) is not this function: it compares
3149
- * folder names whole, as strings. The two differ only for numbered page folders — see the note at
3150
- * `orderedSubfolders`.
3164
+ * @param {{ dirName: string, order?: number }} a
3165
+ * @param {{ dirName: string, order?: number }} b
3166
+ */
3167
+ function compareFolders(a, b) {
3168
+ return (a.order ?? Infinity) - (b.order ?? Infinity) || versionFoldersLast(a.dirName, b.dirName) || compareFilenames(a.dirName, b.dirName)
3169
+ }
3170
+
3171
+ /**
3172
+ * One level's pages in the order a push walks them, and a pull reproduces: `compareFolders`, then the
3173
+ * parent config's `pages:` list — the order the build gives them too. Shared by the push's walk
3174
+ * (`uwx/site.js::orderedSubfolders`) and the pull (`uwx/site-project.js`), so no two lanes can
3175
+ * disagree on what a level's order is.
3151
3176
  *
3152
3177
  * @param {Array<{ dirName: string, name: string, order?: number }>} folders
3153
3178
  * @param {Array} [parentPages] - the parent config's `pages:`
3154
3179
  * @returns {Array} the folders, ordered
3155
3180
  */
3156
3181
  function orderFolders(folders, parentPages) {
3157
- const sorted = [...folders].sort(
3158
- (a, b) =>
3159
- (a.order ?? Infinity) - (b.order ?? Infinity) ||
3160
- versionFoldersLast(a.dirName, b.dirName) ||
3161
- compareFilenames(a.dirName, b.dirName)
3162
- )
3182
+ const sorted = [...folders].sort(compareFolders)
3163
3183
  const parsed = Array.isArray(parentPages) ? parseWildcardArray(parentPages) : null
3164
3184
  return parsed && parsed.mode !== 'all' ? applyWildcardOrder(sorted, parsed) : sorted
3165
3185
  }
@@ -3188,6 +3208,10 @@ export {
3188
3208
  resolveMounts,
3189
3209
  findSectionFile,
3190
3210
  processNesting,
3211
+ // The title a folder-mode `.md` page gives — its first heading, else its name — which a pull asks
3212
+ // before it writes one back (`uwx/page-files.js`).
3213
+ extractH1,
3214
+ prettifySlug,
3191
3215
  }
3192
3216
 
3193
3217
  export default collectSiteContent
@@ -14,6 +14,11 @@
14
14
  * The anchor is translated too. A link written for GitHub names GitHub's anchor for a heading, and a
15
15
  * page's heading has its own (`headingId`, `@uniweb/kit`): "it doesn't — matter" is
16
16
  * `it-doesnt--matter` on one and `it-doesn-t-matter` on the other.
17
+ *
18
+ * ⭐ AND A PULL PUTS EACH ONE BACK AS THE FILE WROTE IT (`fileLinksIn`). ⛔ Until 2026-11-04 a pull wrote
19
+ * the backend's page link into the file in its place, so every file of a docs folder linking another
20
+ * by file read as changed and came back with `/docs/...` links, which lead nowhere on GitHub: 68 of the
21
+ * framework's own docs, measured that day, the first time a pull wrote into a mounted docs folder.
17
22
  */
18
23
  import { realpathSync } from 'node:fs'
19
24
  import { dirname, relative, resolve } from 'node:path'
@@ -30,6 +35,11 @@ export function carrySectionFile(from, to) {
30
35
  if (FILES.has(from)) FILES.set(to, FILES.get(from))
31
36
  }
32
37
 
38
+ /** The file a section — or a record the push made from one — was read from, or null. */
39
+ export function sectionFileOf(section) {
40
+ return FILES.get(section) ?? null
41
+ }
42
+
33
43
  // A relative path to a markdown file: no scheme, no leading `/`, `#` or `?`.
34
44
  const FILE_LINK = /^(?![a-z][a-z0-9+.-]*:|[/#?])([^#?]+\.md)(?:#(.*))?$/i
35
45
 
@@ -97,6 +107,43 @@ function rewriteDoc(node, rewrite) {
97
107
  if (Array.isArray(node.content)) for (const child of node.content) rewriteDoc(child, rewrite)
98
108
  }
99
109
 
110
+ /**
111
+ * The pages a site's files became, for the links written as files: each file by its real path, with
112
+ * its page's route, its section's id where the page is of several files, and its headings' anchors.
113
+ *
114
+ * @param {Array<{ route: string, files: Array<{ file: string, id: string|null, content: object }> }>} pages
115
+ * @returns {Map<string, { route: string, section: string|null, anchors: Map<string, string> }>}
116
+ */
117
+ export function fileLinkTargets(pages) {
118
+ const files = new Map()
119
+ for (const { route, files: held } of pages) {
120
+ for (const { file, id, content } of held) {
121
+ // A page of several files: this file is a section of it, with an anchor of its own.
122
+ files.set(real(file), { route, section: held.length > 1 ? id || null : null, anchors: anchorsOf(content) })
123
+ }
124
+ }
125
+ return files
126
+ }
127
+
128
+ /**
129
+ * The page link a push writes for `href`, written in the file `from` — `{ href, missing }`, `missing`
130
+ * naming what it leads to that is not there (`'file'`, `'anchor'`) — or null for a link no file's.
131
+ *
132
+ * @param {string} href
133
+ * @param {string} from
134
+ * @param {Map} files - `fileLinkTargets`
135
+ * @returns {{ href: string, missing: 'file'|'anchor'|null }|null}
136
+ */
137
+ export function pageLinkFor(href, from, files) {
138
+ const link = FILE_LINK.exec(href)
139
+ if (!link) return null
140
+ const target = files.get(real(resolve(dirname(from), decode(link[1]))))
141
+ if (!target) return { href, missing: 'file' }
142
+ if (!link[2]) return { href: target.section ? `${target.route}#section-${target.section}` : target.route, missing: null }
143
+ const anchor = target.anchors.get(decode(link[2]))
144
+ return { href: `${target.route}#${anchor ?? link[2]}`, missing: anchor ? null : 'anchor' }
145
+ }
146
+
100
147
  /**
101
148
  * Rewrites every link written as a file, in the sections of a site's pages. Mutates the sections.
102
149
  *
@@ -105,39 +152,57 @@ function rewriteDoc(node, rewrite) {
105
152
  * @param {{ siteRoot: string, warn: (message: string) => void }} options
106
153
  */
107
154
  export function rewriteFileLinks(pages, { siteRoot, warn }) {
108
- const files = new Map()
109
- for (const { route, sections } of pages) {
110
- const held = []
111
- eachSection(sections, (section) => {
112
- if (FILES.has(section)) held.push(section)
113
- })
114
- for (const section of held) {
115
- files.set(real(FILES.get(section)), {
116
- route,
117
- // A page of several files: this file is a section of it, with an anchor of its own.
118
- section: held.length > 1 ? section.stableId || section.$id || null : null,
119
- anchors: anchorsOf(section.content),
155
+ const files = fileLinkTargets(
156
+ pages.map(({ route, sections }) => {
157
+ const held = []
158
+ eachSection(sections, (section) => {
159
+ if (FILES.has(section)) held.push({ file: FILES.get(section), id: section.stableId || section.$id || null, content: section.content })
120
160
  })
121
- }
122
- }
123
-
161
+ return { route, files: held }
162
+ })
163
+ )
124
164
  for (const { sections } of pages) {
125
165
  eachSection(sections, (section) => {
126
166
  const from = FILES.get(section)
127
167
  if (!from) return
128
168
  rewriteDoc(section.content, (href) => {
129
- const link = FILE_LINK.exec(href)
130
- if (!link) return href
131
- const target = files.get(real(resolve(dirname(from), decode(link[1]))))
132
- if (!target) {
133
- warn(`${relative(siteRoot, from)}: the link to ${href} names a file that is no page of this site, so it leads nowhere`)
134
- return href
135
- }
136
- if (!link[2]) return target.section ? `${target.route}#section-${target.section}` : target.route
137
- const anchor = target.anchors.get(decode(link[2]))
138
- if (!anchor) warn(`${relative(siteRoot, from)}: the link to ${href}: that page has no such heading`)
139
- return `${target.route}#${anchor ?? link[2]}`
169
+ const page = pageLinkFor(href, from, files)
170
+ if (page?.missing === 'file') warn(`${relative(siteRoot, from)}: the link to ${href} names a file that is no page of this site, so it leads nowhere`)
171
+ if (page?.missing === 'anchor') warn(`${relative(siteRoot, from)}: the link to ${href}: that page has no such heading`)
172
+ return page ? page.href : href
140
173
  })
141
174
  })
142
175
  }
143
176
  }
177
+
178
+ /**
179
+ * ⭐ A FILE'S LINKS AS A PUSH READS THEM, AND BACK, for a pull writing the backend's document into the
180
+ * file a section was read from (`uwx/project-writer.js`). `resolve` gives a node of the file the page
181
+ * links a push sends for its file links, so it compares with the backend's; `restore` writes each page
182
+ * link the file wrote as a file back in the file's own spelling — `../guide/deploying.md`, which works
183
+ * on GitHub and in an editor, never `/docs/guide/deploying`. A link the app added stays the app's.
184
+ *
185
+ * @param {string} from - the file
186
+ * @param {Map} files - `fileLinkTargets`
187
+ * @param {object|null} authored - the file's own document, as it reads
188
+ * @returns {{ resolve: (node: object) => object, restore: (node: object) => object }}
189
+ */
190
+ export function fileLinksIn(from, files, authored) {
191
+ const back = new Map()
192
+ if (authored) {
193
+ rewriteDoc(structuredClone(authored), (href) => {
194
+ const page = pageLinkFor(href, from, files)
195
+ if (page && page.href !== href && !back.has(page.href)) back.set(page.href, href)
196
+ return href
197
+ })
198
+ }
199
+ const mapped = (node, rewrite) => {
200
+ const copy = structuredClone(node)
201
+ rewriteDoc(copy, rewrite)
202
+ return copy
203
+ }
204
+ return {
205
+ resolve: (node) => mapped(node, (href) => pageLinkFor(href, from, files)?.href ?? href),
206
+ restore: (node) => (back.size ? mapped(node, (href) => back.get(href) ?? href) : node),
207
+ }
208
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The `pages/<segment>` keys in a site.yml `paths:` group, unvalidated.
3
+ *
4
+ * Split out from resolveMounts so the dev server can learn which directories a
5
+ * site mounts without re-running resolveMounts' validation — that would repeat
6
+ * its warnings on every startup, and the watcher only needs paths. Every reader —
7
+ * the collector, the watcher, a pull (`uwx/page-files.js`), the roots a push sends
8
+ * and a pull merges (`uwx/site-dirs.js`) and `uniweb status` among them — shares this
9
+ * one definition of what a mount key looks like, so the prefix can never mean one
10
+ * thing to one of them and another to the next.
11
+ *
12
+ * A mount is its folder, `pages/docs: ../docs`, and nothing else. ⭐ Whether a pull writes
13
+ * the app's edits into it is no setting: it does wherever it can merge them, a folder of
14
+ * the site's repository or of a submodule, and holds them where it cannot (the CLI's
15
+ * `utils/site-roots.js`) [Diego, 2026-11-04]. ⛔ An object, `{ path, writable }`, was a
16
+ * mount's form for part of that day; `resolveMounts` refuses it, saying so. Each value is
17
+ * handed over as written, so a reader never takes such an object for no mount at all.
18
+ *
19
+ * A leaf, with no imports, so a module that must stay light can ask it.
20
+ *
21
+ * @param {Object} pathsConfig - The paths: object from site.yml
22
+ * @returns {Array<[string, *]>} [routeSegment, folder] pairs — a folder is a string
23
+ */
24
+ export function mountEntriesOf(pathsConfig) {
25
+ if (!pathsConfig || typeof pathsConfig !== 'object') return []
26
+ return Object.entries(pathsConfig)
27
+ .filter(([key]) => key.startsWith('pages/'))
28
+ .map(([key, value]) => [key.slice('pages/'.length), value])
29
+ }
@@ -12,7 +12,11 @@
12
12
  /**
13
13
  * Split a leading numeric prefix off a filename stem.
14
14
  *
15
- * Dots are sub-levels, so `1`, `1.5`, `2` order as you would read them.
15
+ * ⭐ A NUMBER ORDERS ONLY WHERE A DASH FOLLOWS IT, `1-hero`, or where it is the whole name, `404`,
16
+ * as the docs teach it [Diego, 2026-11-04: "tighten the rule"]. Dots are sub-levels, so `1`, `1.5`,
17
+ * `2` order as you would read them, and `2.5-x` slots between. ⛔ Until 2026-11-04 the dash was
18
+ * optional, so `3d-printing` read as 3 and `d-printing`, `100days` as `days`: every lane that drops
19
+ * the number dropped a name's own digits, and `05b-books.md` was a section called `b-books`.
16
20
  *
17
21
  * ⛔ THE RECORDS LANE USES THIS FOR ORDERING ONLY — it does NOT strip the prefix
18
22
  * from a record's slug. A record's slug is its filename stem, whole. An earlier
@@ -30,9 +34,9 @@
30
34
  * @returns {{ prefix: string|null, name: string }}
31
35
  */
32
36
  export function parseNumericPrefix(filename) {
33
- const match = filename.match(/^(\d+(?:\.\d+)*)-?(.*)$/)
37
+ const match = filename.match(/^(\d+(?:\.\d+)*)(?:-(.+))?$/)
34
38
  if (match) {
35
- return { prefix: match[1], name: match[2] || match[1] }
39
+ return { prefix: match[1], name: match[2] ?? match[1] }
36
40
  }
37
41
  return { prefix: null, name: filename }
38
42
  }