@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 +4 -4
- package/src/content/index.js +3 -0
- package/src/site/add-version.js +44 -7
- package/src/site/content-collector.js +93 -69
- package/src/site/file-links.js +91 -26
- package/src/site/mount-entries.js +29 -0
- package/src/utils/numeric-prefix.js +7 -3
- package/src/uwx/body-splice.js +85 -0
- package/src/uwx/data-schema.js +4 -0
- package/src/uwx/emit-surface.json +0 -3
- package/src/uwx/held-units.js +94 -0
- package/src/uwx/index.js +5 -0
- package/src/uwx/page-files.js +255 -0
- package/src/uwx/project-writer.js +32 -5
- package/src/uwx/route-mode.js +18 -0
- package/src/uwx/same-content.js +7 -4
- package/src/uwx/site-diff.js +7 -2
- package/src/uwx/site-dirs.js +50 -6
- package/src/uwx/site-project.js +561 -60
- package/src/uwx/site.js +20 -12
- package/src/uwx/sync-package.js +36 -5
- package/src/uwx/git-authored.js +0 -85
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@uniweb/build",
|
|
3
|
-
"version": "1.
|
|
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.
|
|
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.
|
|
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": {
|
package/src/content/index.js
CHANGED
|
@@ -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)
|
package/src/site/add-version.js
CHANGED
|
@@ -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)
|
|
56
|
-
|
|
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
|
|
250
|
-
|
|
251
|
-
const
|
|
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(
|
|
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/
|
|
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
|
-
|
|
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
|
|
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.
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
2076
|
-
//
|
|
2077
|
-
pageFolders.sort(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
-
*
|
|
3144
|
-
*
|
|
3145
|
-
* (`
|
|
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
|
-
*
|
|
3149
|
-
*
|
|
3150
|
-
|
|
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
|
package/src/site/file-links.js
CHANGED
|
@@ -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 =
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
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
|
|
130
|
-
if (
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
*
|
|
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]
|
|
39
|
+
return { prefix: match[1], name: match[2] ?? match[1] }
|
|
36
40
|
}
|
|
37
41
|
return { prefix: null, name: filename }
|
|
38
42
|
}
|