@uniweb/build 1.18.2 → 1.19.1
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 +8 -8
- package/src/foundation/shared-types.js +109 -0
- package/src/index.js +3 -0
- package/src/resolve-data-schema.js +13 -1
- package/src/site/content-collector.js +93 -87
- package/src/site/page-settings.js +89 -0
- package/src/uwx/page-files.js +28 -18
- package/src/uwx/site-project.js +55 -7
- package/src/uwx/site.js +11 -6
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@uniweb/build",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.19.1",
|
|
4
4
|
"description": "Build tooling for the Uniweb Component Web Platform",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
@@ -56,15 +56,15 @@
|
|
|
56
56
|
"js-yaml": "^4.3.2",
|
|
57
57
|
"sharp": "^0.35.5",
|
|
58
58
|
"yaml": "^2.5.0",
|
|
59
|
-
"@uniweb/content-reader": "~1.5.9",
|
|
60
|
-
"@uniweb/theming": "~1.3.2",
|
|
61
59
|
"@uniweb/schemas": "~1.6.11",
|
|
60
|
+
"@uniweb/semantic-parser": "~1.13.2",
|
|
61
|
+
"@uniweb/theming": "~1.3.2",
|
|
62
62
|
"@uniweb/projections": "~1.2.13",
|
|
63
|
-
"@uniweb/content-
|
|
64
|
-
"@uniweb/
|
|
63
|
+
"@uniweb/content-reader": "~1.5.9",
|
|
64
|
+
"@uniweb/content-writer": "~1.3.1"
|
|
65
65
|
},
|
|
66
66
|
"optionalDependencies": {
|
|
67
|
-
"@uniweb/runtime": "~1.5.
|
|
67
|
+
"@uniweb/runtime": "~1.5.4"
|
|
68
68
|
},
|
|
69
69
|
"peerDependencies": {
|
|
70
70
|
"vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
|
|
@@ -73,8 +73,8 @@
|
|
|
73
73
|
"@tailwindcss/vite": "^4.0.0",
|
|
74
74
|
"@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
|
|
75
75
|
"vite-plugin-svgr": "^4.0.0",
|
|
76
|
-
"@uniweb/core": "~1.6.
|
|
77
|
-
"@uniweb/runtime": "~1.5.
|
|
76
|
+
"@uniweb/core": "~1.6.9",
|
|
77
|
+
"@uniweb/runtime": "~1.5.4"
|
|
78
78
|
},
|
|
79
79
|
"peerDependenciesMeta": {
|
|
80
80
|
"vite": {
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ⭐ A REGISTERED DATA SCHEMA IS USABLE BY ANY FOUNDATION OR SITE, by its full name — `@acme/member`.
|
|
3
|
+
* Its scope is a namespace, so that names never collide, and says who may publish under it, never who
|
|
4
|
+
* may use it *[Diego, 2026-09-25; 2026-11-08]*. A foundation that renders another's type declares it by
|
|
5
|
+
* that name, and a register names it and sends no definition of it (`uwx/registry-package.js`).
|
|
6
|
+
*
|
|
7
|
+
* So a copy of a type's file in a second package of the same scope is a second definition of one type,
|
|
8
|
+
* and the copies come apart the first time one is edited. `typesDefinedTwice` names each such type, for
|
|
9
|
+
* `uniweb doctor` to recommend one definition, named in full elsewhere, with `schemas.config.js`
|
|
10
|
+
* giving a local build the file (`resolve-data-schema.js`). It refuses nothing: what a register of a
|
|
11
|
+
* changed definition does is the registry's to judge.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import { existsSync, readFileSync, realpathSync } from 'node:fs'
|
|
15
|
+
import { join, resolve } from 'node:path'
|
|
16
|
+
import { readFoundationName } from '../schema.js'
|
|
17
|
+
import { splitFoundationName } from '../foundation-name.js'
|
|
18
|
+
import { ownSchemaFiles, resolveSchemaRef } from '../resolve-data-schema.js'
|
|
19
|
+
import { resolveFoundationSrcDir } from '../utils/foundation-source-root.js'
|
|
20
|
+
import { canonicalJson } from '../uwx/same-content.js'
|
|
21
|
+
|
|
22
|
+
const real = (path) => {
|
|
23
|
+
try {
|
|
24
|
+
return realpathSync(path)
|
|
25
|
+
} catch {
|
|
26
|
+
return resolve(path)
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** `acme`, `@acme` or `@acme/x` → `@acme`; anything else → null. */
|
|
31
|
+
function asScope(value) {
|
|
32
|
+
const handle = typeof value === 'string' ? value.trim().replace(/^@/, '').replace(/\/.*$/, '') : ''
|
|
33
|
+
return handle ? `@${handle}` : null
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The scope a package's types register under, where it already says one: a foundation's is the one in
|
|
38
|
+
* its name (`main.js`), a schemas package's its `package.json`'s `uniweb.scope`, else the `@org` of a
|
|
39
|
+
* package named `@org/schemas`. Null for a name with no scope yet, which `register` settles first.
|
|
40
|
+
*
|
|
41
|
+
* @param {string} dir - the package's folder
|
|
42
|
+
* @param {'foundation'|'schemas'} kind
|
|
43
|
+
* @returns {Promise<string|null>}
|
|
44
|
+
*/
|
|
45
|
+
export async function packageTypeScope(dir, kind) {
|
|
46
|
+
if (kind === 'foundation') {
|
|
47
|
+
try {
|
|
48
|
+
const { name } = await readFoundationName(dir)
|
|
49
|
+
return splitFoundationName(name).scope || null
|
|
50
|
+
} catch {
|
|
51
|
+
return null
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
try {
|
|
55
|
+
const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
|
|
56
|
+
const named = /^@([^/]+)\/schemas$/.exec(typeof pkg?.name === 'string' ? pkg.name : '')
|
|
57
|
+
return asScope(pkg?.uniweb?.scope) || (named ? `@${named[1]}` : null)
|
|
58
|
+
} catch {
|
|
59
|
+
return null
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// The folder a package's `schemas/` is in: a foundation's source root, a schemas package's own.
|
|
64
|
+
function typeRoot(dir, kind) {
|
|
65
|
+
return kind === 'foundation' ? join(dir, resolveFoundationSrcDir(dir)) : dir
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Each name of a scope that two or more of the packages define, with the files that define it and
|
|
70
|
+
* whether they say the same thing.
|
|
71
|
+
*
|
|
72
|
+
* @param {{ dir: string, kind: 'foundation'|'schemas', scope?: string|null }[]} packages - the
|
|
73
|
+
* workspace's foundations and schemas packages; a `scope` given is used over what the package says
|
|
74
|
+
* (a name `register` has just settled)
|
|
75
|
+
* @returns {Promise<{ ref: string, files: string[], differ: boolean }[]>} by name
|
|
76
|
+
*/
|
|
77
|
+
export async function typesDefinedTwice(packages) {
|
|
78
|
+
const byRef = new Map()
|
|
79
|
+
const seen = new Set()
|
|
80
|
+
for (const pkg of packages) {
|
|
81
|
+
const dir = real(pkg.dir)
|
|
82
|
+
if (seen.has(dir)) continue
|
|
83
|
+
seen.add(dir)
|
|
84
|
+
const scope = asScope(pkg.scope) || (await packageTypeScope(dir, pkg.kind))
|
|
85
|
+
if (!scope) continue
|
|
86
|
+
const root = typeRoot(dir, pkg.kind)
|
|
87
|
+
if (!existsSync(join(root, 'schemas'))) continue
|
|
88
|
+
for (const { name, file } of ownSchemaFiles(root)) {
|
|
89
|
+
const ref = `${scope}/${name}`
|
|
90
|
+
if (!byRef.has(ref)) byRef.set(ref, [])
|
|
91
|
+
byRef.get(ref).push({ root, name, file })
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
const out = []
|
|
95
|
+
for (const [ref, defs] of [...byRef].sort(([a], [b]) => a.localeCompare(b))) {
|
|
96
|
+
if (defs.length < 2) continue
|
|
97
|
+
const said = new Set()
|
|
98
|
+
for (const { root, name, file } of defs) {
|
|
99
|
+
try {
|
|
100
|
+
said.add(canonicalJson(await resolveSchemaRef(`@/${name}`, { srcDir: root, aliases: {} })))
|
|
101
|
+
} catch {
|
|
102
|
+
// One that does not read is not the same as one that does.
|
|
103
|
+
said.add(`unreadable:${file}`)
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
out.push({ ref, files: defs.map((d) => d.file), differ: said.size > 1 })
|
|
107
|
+
}
|
|
108
|
+
return out
|
|
109
|
+
}
|
package/src/index.js
CHANGED
|
@@ -93,5 +93,8 @@ export { classifyPackage, isExtensionPackage, isSchemasPackage } from './utils/c
|
|
|
93
93
|
// Standalone schemas-package discovery (the foundation-less register input)
|
|
94
94
|
export { collectStandaloneSchemas } from './resolve-data-schema.js'
|
|
95
95
|
|
|
96
|
+
// One name in a scope is one type: the names a workspace's packages define twice
|
|
97
|
+
export { typesDefinedTwice, packageTypeScope } from './foundation/shared-types.js'
|
|
98
|
+
|
|
96
99
|
// Default export is the combined Vite plugin
|
|
97
100
|
export { default } from './vite-foundation-plugin.js'
|
|
@@ -424,7 +424,19 @@ function schemaFilesIn(dir) {
|
|
|
424
424
|
* @returns {string[]}
|
|
425
425
|
*/
|
|
426
426
|
export function ownSchemaRefs(srcDir) {
|
|
427
|
-
return
|
|
427
|
+
return ownSchemaFiles(srcDir).map(({ name }) => `@/${name}`)
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
/**
|
|
431
|
+
* The files `ownSchemaRefs` reads its names from: each schema a foundation defines, by name, with the
|
|
432
|
+
* file that defines it.
|
|
433
|
+
*
|
|
434
|
+
* @param {string} srcDir - the foundation's source root (a schemas package's own folder)
|
|
435
|
+
* @returns {{ name: string, file: string }[]}
|
|
436
|
+
*/
|
|
437
|
+
export function ownSchemaFiles(srcDir) {
|
|
438
|
+
const dir = join(srcDir, 'schemas')
|
|
439
|
+
return schemaFilesIn(dir).map(({ name, file }) => ({ name, file: join(dir, file) }))
|
|
428
440
|
}
|
|
429
441
|
|
|
430
442
|
// Resolve a package's module entry FILE (absolute) from its package.json —
|
|
@@ -50,6 +50,7 @@ import { runtimeServicesConfig, refuseRetiredServiceKeys, refuseUnreadableServic
|
|
|
50
50
|
import { refuseUnreadableAddress } from './site-address.js'
|
|
51
51
|
import { warnOutsideVocabulary } from './vocabulary-warnings.js'
|
|
52
52
|
import { warnPlacementsNotOffered } from './placement-warnings.js'
|
|
53
|
+
import { atomicPageConfig, isAtomicPageKey, warnPageKeysNamingParams } from './page-settings.js'
|
|
53
54
|
import { markdownToProseMirror } from '@uniweb/content-reader'
|
|
54
55
|
|
|
55
56
|
/**
|
|
@@ -922,6 +923,56 @@ function resolveDisplayTitle(declaredTitle, segment, sections) {
|
|
|
922
923
|
return extractH1(first?.content) || prettifySlug(segment)
|
|
923
924
|
}
|
|
924
925
|
|
|
926
|
+
/**
|
|
927
|
+
* ⭐ A PAGE'S SETTINGS, read from its config by one rule: a `page.yml` or `folder.yml`, or the
|
|
928
|
+
* frontmatter of a page that is one `.md` file (`page-settings.js`). Its title is the caller's,
|
|
929
|
+
* worked out from what the page holds.
|
|
930
|
+
*
|
|
931
|
+
* ⛔ Until 2026-11-08 a page's `keywords:` was read by nothing here: a push sent it and a backend's
|
|
932
|
+
* page stated it, while a static build left it out of the page, and so out of its head.
|
|
933
|
+
*
|
|
934
|
+
* @param {object} config - the page's settings as written
|
|
935
|
+
* @param {string} title - the page's title
|
|
936
|
+
* @returns {object} the page's setting fields, as the page payload carries them
|
|
937
|
+
*/
|
|
938
|
+
function pageSettingFields(config, title) {
|
|
939
|
+
const seo = config.seo && typeof config.seo === 'object' && !Array.isArray(config.seo) ? config.seo : {}
|
|
940
|
+
const keywords = Array.isArray(config.keywords) ? config.keywords.filter((k) => typeof k === 'string' && k) : config.keywords
|
|
941
|
+
return {
|
|
942
|
+
id: authoredId(config.id), // Stable page ID for page: links (survives reorganization)
|
|
943
|
+
title,
|
|
944
|
+
description: config.description || '',
|
|
945
|
+
label: config.label || null, // Short label for navigation (defaults to title)
|
|
946
|
+
...((Array.isArray(keywords) ? keywords.length > 0 : typeof keywords === 'string' && keywords) ? { keywords } : {}),
|
|
947
|
+
// Localized URL slug overrides: { <locale>: <segment> }. Compiled into
|
|
948
|
+
// config.i18n.routeTranslations by collectSiteContent, then stripped from
|
|
949
|
+
// the page payload (build is authoritative; runtime hydrates the map).
|
|
950
|
+
...(config.slug && typeof config.slug === 'object' && !Array.isArray(config.slug) ? { slug: config.slug } : {}),
|
|
951
|
+
hidden: config.hidden || false, // Hide from all navigation
|
|
952
|
+
hideIn: normalizeHideIn(config), // Named nav areas to suppress this page from
|
|
953
|
+
// Knowledge page — content feeds AI pipeline instead of (or in addition to) rendering
|
|
954
|
+
...(config.knowledge != null ? { knowledge: config.knowledge } : {}),
|
|
955
|
+
// Per-page section instrumentation opt-in. ⛔ PAGE-LEVEL ONLY, and it must
|
|
956
|
+
// stay that way: a site-wide form would emit one event per section on every
|
|
957
|
+
// page, whose cardinality a counter-based collector cannot store (measured:
|
|
958
|
+
// ~160 distinct values against a 50-value cap folds ~70% into `(other)`).
|
|
959
|
+
// Deliberately NOT part of the site → page → section cascade that
|
|
960
|
+
// `prerender:` uses, even though that is the local convention — following it
|
|
961
|
+
// would re-create the unscoped mode through the front door.
|
|
962
|
+
// the tracking design, §10b.
|
|
963
|
+
...(config.trackSections != null ? { trackSections: config.trackSections } : {}),
|
|
964
|
+
seo: {
|
|
965
|
+
noindex: seo.noindex || false,
|
|
966
|
+
image: seo.image || null,
|
|
967
|
+
ogTitle: seo.ogTitle || null,
|
|
968
|
+
ogDescription: seo.ogDescription || null,
|
|
969
|
+
canonical: seo.canonical || null,
|
|
970
|
+
changefreq: seo.changefreq || null,
|
|
971
|
+
priority: seo.priority || null
|
|
972
|
+
}
|
|
973
|
+
}
|
|
974
|
+
}
|
|
975
|
+
|
|
925
976
|
// ⭐ The rule now lives in `utils/numeric-prefix.js` — `records/folder.yml` needs the
|
|
926
977
|
// identical one, and a records reader cannot import this module without closing
|
|
927
978
|
// a cycle. Imported at the top; still re-exported below for existing callers.
|
|
@@ -1103,14 +1154,21 @@ function getDirectChildName(route, parentRoute) {
|
|
|
1103
1154
|
}
|
|
1104
1155
|
|
|
1105
1156
|
/**
|
|
1106
|
-
* Process a markdown file as a
|
|
1107
|
-
*
|
|
1157
|
+
* Process a markdown file as a page of its own (folder mode): an atomic page, whose one section is
|
|
1158
|
+
* the file.
|
|
1159
|
+
*
|
|
1160
|
+
* ⭐ Its frontmatter holds the page's settings beside the section's type and params
|
|
1161
|
+
* (`page-settings.js`): a `title:`, else the file's first heading, else its name prettified; a
|
|
1162
|
+
* `description:`, a `label:`, `seo:` and the rest a `page.yml` gives a page. They are the page's, not
|
|
1163
|
+
* the section's params. `pageConfig` is them as written, which the push sends as the page's
|
|
1164
|
+
* (`uwx/site.js::folderModePageRecords`). ⛔ Until 2026-11-08 the page took only its title from the
|
|
1165
|
+
* file, and every one of those keys reached the section as a param.
|
|
1108
1166
|
*
|
|
1109
1167
|
* @param {string} filePath - Path to markdown file
|
|
1110
1168
|
* @param {string} fileName - Filename (e.g., "getting-started.md")
|
|
1111
1169
|
* @param {string} siteRoot - Site root directory for asset resolution
|
|
1112
1170
|
* @param {string} parentRoute - Parent route (e.g., '/docs')
|
|
1113
|
-
* @returns {Promise<Object>} Page data with assets manifest
|
|
1171
|
+
* @returns {Promise<Object>} Page data with assets manifest, and the page's settings as written
|
|
1114
1172
|
*/
|
|
1115
1173
|
async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
|
|
1116
1174
|
const { name } = parse(fileName)
|
|
@@ -1118,41 +1176,36 @@ async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
|
|
|
1118
1176
|
const pageName = stableName || name
|
|
1119
1177
|
const route = parentRoute === '/' ? `/${pageName}` : `${parentRoute}/${pageName}`
|
|
1120
1178
|
|
|
1121
|
-
// Process the markdown as a single section
|
|
1122
|
-
const { section, assetCollection, iconCollection } = await processMarkdownFile(
|
|
1123
|
-
filePath, '1', siteRoot, pageName
|
|
1179
|
+
// Process the markdown as a single section — the page's own settings taken out of its params
|
|
1180
|
+
const { section, assetCollection, iconCollection, pageConfig } = await processMarkdownFile(
|
|
1181
|
+
filePath, '1', siteRoot, pageName, { atomic: true }
|
|
1124
1182
|
)
|
|
1125
1183
|
|
|
1126
1184
|
const fileStat = await stat(filePath)
|
|
1185
|
+
const settings = pageSettingFields(pageConfig, pageConfig.title || extractH1(section.content) || prettifySlug(pageName))
|
|
1127
1186
|
|
|
1128
1187
|
return {
|
|
1129
1188
|
page: {
|
|
1130
1189
|
route,
|
|
1131
1190
|
sourcePath: null,
|
|
1132
|
-
id: null,
|
|
1133
1191
|
isIndex: false,
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1192
|
+
...settings,
|
|
1193
|
+
// ⭐ Its id is its section's (`page-settings.js`): a page in an atomic-parent is known by its file.
|
|
1194
|
+
id: null,
|
|
1137
1195
|
lastModified: fileStat.mtime?.toISOString() || null,
|
|
1138
1196
|
isDynamic: false,
|
|
1139
1197
|
paramName: null,
|
|
1140
1198
|
// The file IS the page, so its `hidden: true` drafts the page — left out of a published
|
|
1141
1199
|
// build, kept in dev — rather than leaving a page with no section (2026-09-28).
|
|
1142
1200
|
hidden: section.hidden === true,
|
|
1143
|
-
|
|
1144
|
-
layout: {},
|
|
1145
|
-
seo: {
|
|
1146
|
-
noindex: false,
|
|
1147
|
-
image: null,
|
|
1148
|
-
changefreq: null,
|
|
1149
|
-
priority: null
|
|
1150
|
-
},
|
|
1201
|
+
// As written: the caller lays the folder's and the site's under it (`mergeLayoutConfig`).
|
|
1202
|
+
layout: pageConfig.layout ?? {},
|
|
1151
1203
|
fetch: null,
|
|
1152
1204
|
hasContent: true,
|
|
1153
1205
|
sections: [section],
|
|
1154
1206
|
order: prefix ? parseFloat(prefix) : undefined
|
|
1155
1207
|
},
|
|
1208
|
+
pageConfig,
|
|
1156
1209
|
assetCollection,
|
|
1157
1210
|
iconCollection
|
|
1158
1211
|
}
|
|
@@ -1165,9 +1218,13 @@ async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
|
|
|
1165
1218
|
* @param {string} id - Section ID (numeric/positional)
|
|
1166
1219
|
* @param {string} siteRoot - Site root directory for asset resolution
|
|
1167
1220
|
* @param {string} defaultStableId - Default stable ID from filename (can be overridden in frontmatter)
|
|
1168
|
-
* @
|
|
1221
|
+
* @param {Object} [options]
|
|
1222
|
+
* @param {boolean} [options.atomic] - the file is a page of its own (`processFileAsPage`): its
|
|
1223
|
+
* frontmatter's page keys are the page's settings, not params (`page-settings.js`)
|
|
1224
|
+
* @returns {Object} Section data with assets manifest, and for an atomic page its page's settings
|
|
1225
|
+
* as written (`pageConfig`)
|
|
1169
1226
|
*/
|
|
1170
|
-
async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = null) {
|
|
1227
|
+
async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = null, { atomic = false } = {}) {
|
|
1171
1228
|
const content = await readFile(filePath, 'utf8')
|
|
1172
1229
|
let frontMatter = {}
|
|
1173
1230
|
let markdown = content
|
|
@@ -1194,10 +1251,12 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
|
|
|
1194
1251
|
// ⭐ WHAT IS NOT A PARAM is `SECTION_KEYS` (`@uniweb/schemas/section`) — the list the build's
|
|
1195
1252
|
// warning on a component's `params:` reads too — and `fetch`, one of the section's settings,
|
|
1196
1253
|
// kept on the section as a field of its own. `query:` / `fetch:` declare the section's own
|
|
1197
|
-
// data, and a leftover `data:` is refused (`declaredFetch`).
|
|
1254
|
+
// data, and a leftover `data:` is refused (`declaredFetch`). ⭐ In a page that is one file, nor are
|
|
1255
|
+
// its page's settings (`page-settings.js`): a param of one of those names is written under `props:`.
|
|
1198
1256
|
const { type, hidden, preset, input, props, fetch, query, data, id: frontmatterId } = frontMatter
|
|
1257
|
+
const pageConfig = atomic ? atomicPageConfig(frontMatter) : null
|
|
1199
1258
|
const params = Object.fromEntries(
|
|
1200
|
-
Object.entries(frontMatter).filter(([key]) => !isSectionKey(key) && key !== 'fetch')
|
|
1259
|
+
Object.entries(frontMatter).filter(([key]) => !isSectionKey(key) && key !== 'fetch' && !(atomic && isAtomicPageKey(key)))
|
|
1201
1260
|
)
|
|
1202
1261
|
// ⭐ `hidden: true` — a draft section, the page's meaning one level down: left out of a
|
|
1203
1262
|
// published build, kept by `uniweb dev`, and synced as the section's own `hidden`
|
|
@@ -1247,6 +1306,7 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
|
|
|
1247
1306
|
const proseMirrorContent = markdownToProseMirror(markdown, { onWarning: warnHere })
|
|
1248
1307
|
warnOutsideVocabulary(proseMirrorContent, warnHere)
|
|
1249
1308
|
warnPlacementsNotOffered(proseMirrorContent, type || null, sectionTypes, warnHere)
|
|
1309
|
+
if (pageConfig) warnPageKeysNamingParams(pageConfig, type || null, sectionTypes, warnHere)
|
|
1250
1310
|
|
|
1251
1311
|
// `query: team` → `fetch: { query: team }`; a list, one config per name, each under
|
|
1252
1312
|
// its own `as` — the one helper every level uses. Unrelated to a section type's
|
|
@@ -1277,7 +1337,7 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
|
|
|
1277
1337
|
const iconCollection = collectSectionIcons(section)
|
|
1278
1338
|
|
|
1279
1339
|
noteSectionFile(section, filePath)
|
|
1280
|
-
return { section, assetCollection, iconCollection }
|
|
1340
|
+
return { section, assetCollection, iconCollection, pageConfig }
|
|
1281
1341
|
}
|
|
1282
1342
|
|
|
1283
1343
|
/**
|
|
@@ -1796,7 +1856,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
|
|
|
1796
1856
|
const sourcePath = isIndex ? folderRoute : null
|
|
1797
1857
|
|
|
1798
1858
|
// Extract configuration
|
|
1799
|
-
const {
|
|
1859
|
+
const { layout: layoutConfig } = pageConfig
|
|
1800
1860
|
|
|
1801
1861
|
// Resolve the effective layout by cascading site → folder → page, per field.
|
|
1802
1862
|
// ⛔ Until 2026-09-09 only `name` cascaded and `hide` / `params` were read from
|
|
@@ -1818,40 +1878,15 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
|
|
|
1818
1878
|
page: {
|
|
1819
1879
|
route,
|
|
1820
1880
|
sourcePath, // Original folder-based path (for ancestor checking in navigation)
|
|
1821
|
-
id: authoredId(pageConfig.id), // Stable page ID for page: links (survives reorganization)
|
|
1822
1881
|
isIndex, // Marks this page as the index for its parent route
|
|
1823
|
-
|
|
1824
|
-
|
|
1825
|
-
label: pageConfig.label || null, // Short label for navigation (defaults to title)
|
|
1826
|
-
// Localized URL slug overrides: { <locale>: <segment> }. Compiled into
|
|
1827
|
-
// config.i18n.routeTranslations by collectSiteContent, then stripped from
|
|
1828
|
-
// the page payload (build is authoritative; runtime hydrates the map).
|
|
1829
|
-
...(pageConfig.slug && typeof pageConfig.slug === 'object' && !Array.isArray(pageConfig.slug)
|
|
1830
|
-
? { slug: pageConfig.slug }
|
|
1831
|
-
: {}),
|
|
1882
|
+
// Its settings, by the one rule a page of one `.md` file is read by too (`pageSettingFields`)
|
|
1883
|
+
...pageSettingFields(pageConfig, resolveDisplayTitle(pageConfig.title, pageName, hierarchicalSections)),
|
|
1832
1884
|
lastModified: lastModified?.toISOString(),
|
|
1833
1885
|
|
|
1834
1886
|
// Parametric route metadata
|
|
1835
1887
|
isDynamic,
|
|
1836
1888
|
paramName, // e.g., "slug" from [slug]; a nested page's ancestor's
|
|
1837
1889
|
|
|
1838
|
-
// Navigation options
|
|
1839
|
-
hidden: pageConfig.hidden || false, // Hide from all navigation
|
|
1840
|
-
hideIn: normalizeHideIn(pageConfig), // Named nav areas to suppress this page from
|
|
1841
|
-
|
|
1842
|
-
// Knowledge page — content feeds AI pipeline instead of (or in addition to) rendering
|
|
1843
|
-
...(pageConfig.knowledge != null ? { knowledge: pageConfig.knowledge } : {}),
|
|
1844
|
-
|
|
1845
|
-
// Per-page section instrumentation opt-in. ⛔ PAGE-LEVEL ONLY, and it must
|
|
1846
|
-
// stay that way: a site-wide form would emit one event per section on every
|
|
1847
|
-
// page, whose cardinality a counter-based collector cannot store (measured:
|
|
1848
|
-
// ~160 distinct values against a 50-value cap folds ~70% into `(other)`).
|
|
1849
|
-
// Deliberately NOT part of the site → page → section cascade that
|
|
1850
|
-
// `prerender:` uses, even though that is the local convention — following it
|
|
1851
|
-
// would re-create the unscoped mode through the front door.
|
|
1852
|
-
// the tracking design, §10b.
|
|
1853
|
-
...(pageConfig.trackSections != null ? { trackSections: pageConfig.trackSections } : {}),
|
|
1854
|
-
|
|
1855
1890
|
// Layout options (named layout + per-page overrides)
|
|
1856
1891
|
layout: {
|
|
1857
1892
|
...(resolvedLayoutName ? { name: resolvedLayoutName } : {}),
|
|
@@ -1859,16 +1894,6 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
|
|
|
1859
1894
|
...(layoutObj.params ? { params: layoutObj.params } : {}),
|
|
1860
1895
|
},
|
|
1861
1896
|
|
|
1862
|
-
seo: {
|
|
1863
|
-
noindex: seo.noindex || false,
|
|
1864
|
-
image: seo.image || null,
|
|
1865
|
-
ogTitle: seo.ogTitle || null,
|
|
1866
|
-
ogDescription: seo.ogDescription || null,
|
|
1867
|
-
canonical: seo.canonical || null,
|
|
1868
|
-
changefreq: seo.changefreq || null,
|
|
1869
|
-
priority: seo.priority || null
|
|
1870
|
-
},
|
|
1871
|
-
|
|
1872
1897
|
// Data fetching — `fetch:`, or the `query:` shorthand (`declaredFetch`)
|
|
1873
1898
|
fetch: parseFetchConfig(...fetchIn(pageConfig, relative(siteRoot, join(pagePath, 'page.yml')), 'page')),
|
|
1874
1899
|
|
|
@@ -2223,27 +2248,18 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
|
|
|
2223
2248
|
const containerPage = {
|
|
2224
2249
|
route: containerRoute,
|
|
2225
2250
|
sourcePath: isIndex ? (parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`) : null,
|
|
2226
|
-
id: dirConfig.id || null,
|
|
2227
2251
|
isIndex,
|
|
2228
|
-
|
|
2229
|
-
|
|
2230
|
-
|
|
2252
|
+
// ⭐ Its settings by the one rule every page is read by (`pageSettingFields`). ⛔ Until
|
|
2253
|
+
// 2026-11-08 this read its own few: a `folder.yml`'s `keywords`, `slug`, `trackSections`
|
|
2254
|
+
// and Open Graph title and description reached a backend on a push, and no static build.
|
|
2255
|
+
...pageSettingFields(dirConfig, resolveDisplayTitle(dirConfig.title, entry, null)),
|
|
2231
2256
|
lastModified: null,
|
|
2232
2257
|
isDynamic: false,
|
|
2233
2258
|
paramName: null,
|
|
2234
|
-
hidden: dirConfig.hidden || false,
|
|
2235
|
-
hideIn: normalizeHideIn(dirConfig),
|
|
2236
|
-
...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
|
|
2237
2259
|
// `effectiveLayout` is ALREADY this container's resolved layout —
|
|
2238
2260
|
// `mergeLayoutConfig(parentLayout, normalizeLayoutConfig(dirConfig.layout))`
|
|
2239
2261
|
// — so re-reading `dirConfig.layout` here would drop the inherited half.
|
|
2240
2262
|
layout: effectiveLayout,
|
|
2241
|
-
seo: {
|
|
2242
|
-
noindex: dirConfig.seo?.noindex || false,
|
|
2243
|
-
image: dirConfig.seo?.image || null,
|
|
2244
|
-
changefreq: dirConfig.seo?.changefreq || null,
|
|
2245
|
-
priority: dirConfig.seo?.priority || null
|
|
2246
|
-
},
|
|
2247
2263
|
// ⭐ `declaredFetch`, as every other level: this read `dirConfig.fetch`
|
|
2248
2264
|
// alone until 2026-09-11, so a container's `folder.yml` shorthand reached
|
|
2249
2265
|
// a backend on `push` and was dropped from a static build.
|
|
@@ -2315,25 +2331,15 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
|
|
|
2315
2331
|
const containerPage = {
|
|
2316
2332
|
route: containerRoute,
|
|
2317
2333
|
sourcePath: isIndex ? (parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`) : null,
|
|
2318
|
-
id: dirConfig.id || null,
|
|
2319
2334
|
isIndex,
|
|
2320
|
-
|
|
2321
|
-
|
|
2322
|
-
|
|
2335
|
+
// Its settings by the one rule every page is read by (`pageSettingFields`) — see the note
|
|
2336
|
+
// on the sibling container above.
|
|
2337
|
+
...pageSettingFields(dirConfig, resolveDisplayTitle(dirConfig.title, entry, null)),
|
|
2323
2338
|
lastModified: null,
|
|
2324
2339
|
isDynamic: false,
|
|
2325
2340
|
paramName: null,
|
|
2326
|
-
hidden: dirConfig.hidden || false,
|
|
2327
|
-
hideIn: normalizeHideIn(dirConfig),
|
|
2328
|
-
...(dirConfig.knowledge != null ? { knowledge: dirConfig.knowledge } : {}),
|
|
2329
2341
|
// Already resolved — see the note on the sibling container above.
|
|
2330
2342
|
layout: effectiveLayout,
|
|
2331
|
-
seo: {
|
|
2332
|
-
noindex: dirConfig.seo?.noindex || false,
|
|
2333
|
-
image: dirConfig.seo?.image || null,
|
|
2334
|
-
changefreq: dirConfig.seo?.changefreq || null,
|
|
2335
|
-
priority: dirConfig.seo?.priority || null
|
|
2336
|
-
},
|
|
2337
2343
|
// ⭐ The folder's own declaration, as the folder-mode container above and
|
|
2338
2344
|
// every other level read it. ⛔ This was `fetch: null` until 2026-09-11:
|
|
2339
2345
|
// a `folder.yml` here lost its `fetch:` (and its shorthand) on a static
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ⭐ A PAGE THAT IS ONE `.md` FILE HOLDS ITS PAGE'S SETTINGS IN ITS FRONTMATTER — an atomic page, one
|
|
3
|
+
* file in folder mode, beside its section's `type` and params. The file is the page and its one
|
|
4
|
+
* section, so a key a `page.yml` would give the page is the page's, and a param of the same name is
|
|
5
|
+
* written under `props:`, which merges into the params (`SECTION_KEYS.props`, `@uniweb/schemas/section`).
|
|
6
|
+
*
|
|
7
|
+
* One list, for every lane that reads or writes such a page: the build
|
|
8
|
+
* (`content-collector.js::processFileAsPage`), the push (`uwx/site.js::folderModePageRecords`) and the
|
|
9
|
+
* pull (`uwx/page-files.js::mdPageCannotHold`, `uwx/site-project.js::writeMdPage`).
|
|
10
|
+
*
|
|
11
|
+
* ⛔ NOT IN IT, each for a reason:
|
|
12
|
+
* - `id` — a section key, the section's id, as it has always been. A page's identity in an atomic-parent
|
|
13
|
+
* is its file's name, so a page renamed in the app keeps its section's id without the page taking a
|
|
14
|
+
* new one. A page id its file name does not give is held by a pull.
|
|
15
|
+
* - `hidden` — a section key too, already the page's: the file IS the page, so it drafts the page.
|
|
16
|
+
* - `query`, `fetch` — the section's own data. For a page of one section with no child page, the page's
|
|
17
|
+
* data and its section's reach the same section.
|
|
18
|
+
* - `redirect`, `rewrite` — they make a page that holds no section, which an atomic page is not.
|
|
19
|
+
* - `index`, `pages`, `sections`, `nest`, `mount` — they shape or order pages and sections, which a page
|
|
20
|
+
* of one file has none of.
|
|
21
|
+
*
|
|
22
|
+
* Until 2026-11-08 every one of these keys was a section param: the build gave the page its first
|
|
23
|
+
* heading as its title and nothing else, the push sent only that title, and a pull held any page the
|
|
24
|
+
* app gave a description, a label or any other setting.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
/** The keys of an atomic page's frontmatter that are its page's settings, as a `page.yml` spells them. */
|
|
28
|
+
export const ATOMIC_PAGE_KEYS = Object.freeze([
|
|
29
|
+
'title',
|
|
30
|
+
'description',
|
|
31
|
+
'label',
|
|
32
|
+
'keywords',
|
|
33
|
+
'slug',
|
|
34
|
+
'hideIn',
|
|
35
|
+
'layout',
|
|
36
|
+
'seo',
|
|
37
|
+
'knowledge',
|
|
38
|
+
'trackSections',
|
|
39
|
+
])
|
|
40
|
+
|
|
41
|
+
const KEYS = new Set(ATOMIC_PAGE_KEYS)
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Whether `name` is one of an atomic page's settings in its frontmatter.
|
|
45
|
+
*
|
|
46
|
+
* @param {string} name
|
|
47
|
+
* @returns {boolean}
|
|
48
|
+
*/
|
|
49
|
+
export function isAtomicPageKey(name) {
|
|
50
|
+
return KEYS.has(name)
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* The page's settings an atomic page's frontmatter holds, as written.
|
|
55
|
+
*
|
|
56
|
+
* @param {object} frontmatter - the file's frontmatter
|
|
57
|
+
* @returns {object} each page key the frontmatter gives, and no other
|
|
58
|
+
*/
|
|
59
|
+
export function atomicPageConfig(frontmatter) {
|
|
60
|
+
const out = {}
|
|
61
|
+
if (!frontmatter || typeof frontmatter !== 'object') return out
|
|
62
|
+
for (const key of ATOMIC_PAGE_KEYS) if (frontmatter[key] !== undefined) out[key] = frontmatter[key]
|
|
63
|
+
return out
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Say, with the file in hand, each page key of an atomic page's frontmatter that its section type
|
|
68
|
+
* also declares as a param: the page takes the value, and the section receives none. A warning, since
|
|
69
|
+
* the page renders; writing the param under `props:` gives it to the section.
|
|
70
|
+
*
|
|
71
|
+
* @param {object} pageConfig - the page's settings as written (`atomicPageConfig`)
|
|
72
|
+
* @param {string|null} type - the section's `type:`; with none, the foundation's `defaultSection`
|
|
73
|
+
* @param {Object|null} sectionTypes - the foundation's schema, each section type's entry by name;
|
|
74
|
+
* null when it is not at hand
|
|
75
|
+
* @param {(message: string) => void} warn - prints one message, prefixed with the file
|
|
76
|
+
*/
|
|
77
|
+
export function warnPageKeysNamingParams(pageConfig, type, sectionTypes, warn) {
|
|
78
|
+
const name = type || sectionTypes?._self?.defaultSection || null
|
|
79
|
+
const entry = name && !name.startsWith('_') ? sectionTypes?.[name] : null
|
|
80
|
+
const params = entry && typeof entry === 'object' ? entry.params : null
|
|
81
|
+
if (!params || typeof params !== 'object') return
|
|
82
|
+
for (const key of Object.keys(pageConfig)) {
|
|
83
|
+
if (!Object.prototype.hasOwnProperty.call(params, key)) continue
|
|
84
|
+
warn(
|
|
85
|
+
`\`${key}:\` is the page's ${key}, since the page is this one file. ${name} has a \`${key}\` param too, ` +
|
|
86
|
+
`which receives nothing: write it under \`props:\` to give it to the section (\`props: { ${key}: … }\`).`
|
|
87
|
+
)
|
|
88
|
+
}
|
|
89
|
+
}
|
package/src/uwx/page-files.js
CHANGED
|
@@ -204,10 +204,13 @@ export function sitePageFiles(siteYml, pagesDir, { seen = null, siteRoot = null,
|
|
|
204
204
|
}
|
|
205
205
|
}
|
|
206
206
|
|
|
207
|
-
//
|
|
208
|
-
//
|
|
209
|
-
//
|
|
210
|
-
|
|
207
|
+
// ⭐ A folder-mode `.md` page's frontmatter holds its page's settings (`site/page-settings.js`): its title,
|
|
208
|
+
// description, label, keywords, `hideIn`, `knowledge`, `trackSections`, layout and `seo` with its Open
|
|
209
|
+
// Graph title and description, sent as a `page.yml`'s are (`folderModePageRecords`, `site.js`). These page
|
|
210
|
+
// fields have no place in one: a redirect or a rewrite makes a page that holds no section, and the page's
|
|
211
|
+
// own data is its one section's (`query:` in its frontmatter). ⛔ Until 2026-11-08 every page setting was
|
|
212
|
+
// here but its title and `hidden`, and a page the app gave a description was held.
|
|
213
|
+
const NOT_IN_AN_MD_PAGE = ['redirect', 'rewrite', 'fetch']
|
|
211
214
|
|
|
212
215
|
const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
|
|
213
216
|
|
|
@@ -224,12 +227,10 @@ function holdsValue(value, sourceLocale) {
|
|
|
224
227
|
|
|
225
228
|
/**
|
|
226
229
|
* What of a page a folder-mode `.md` file cannot hold — none, when it can be written as one. The file is
|
|
227
|
-
* the page and its one section: its
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
231
|
-
* ⚖️ A setting such a page might hold in its frontmatter is project-file-organization's §10 decision 1,
|
|
232
|
-
* not settled; until it is, a pull writes none.
|
|
230
|
+
* the page and its one section: its frontmatter holds the page's settings, a `title:` among them where
|
|
231
|
+
* its first heading, else its name prettified, does not give it, and its `hidden:` drafts the page. A
|
|
232
|
+
* second section, pages below it, a route parameter, an id its file name does not give, a redirect, a
|
|
233
|
+
* rewrite or data of the page's own, it cannot say.
|
|
233
234
|
*
|
|
234
235
|
* @param {object} record - the page's record
|
|
235
236
|
* @param {{ name: string, sourceLocale: string }} opts - `name`, the file's page name (`1-install.md` → `install`)
|
|
@@ -241,15 +242,24 @@ export function mdPageCannotHold(record, { name, sourceLocale }) {
|
|
|
241
242
|
if (sections.length !== 1) out.push(sections.length ? 'more than one section' : 'no section')
|
|
242
243
|
if (Array.isArray(record?.$children) && record.$children.length) out.push('pages below it')
|
|
243
244
|
if (record?.is_dynamic) out.push('a route parameter')
|
|
244
|
-
// Its id is its file's name
|
|
245
|
+
// Its id is its file's name, and the file's `id:` is its section's (`site/page-settings.js`); one the
|
|
246
|
+
// name does not give needs a page folder's `id:`.
|
|
245
247
|
if (typeof record?.stable_id === 'string' && record.stable_id && record.stable_id !== name) out.push('an id its file name does not give')
|
|
246
248
|
for (const key of NOT_IN_AN_MD_PAGE) if (holdsValue(record?.[key], sourceLocale)) out.push(key)
|
|
247
|
-
if (sections.length === 1) {
|
|
248
|
-
const content = sections[0]?.content
|
|
249
|
-
const doc = isProseMirrorDoc(content) ? content : unwrapLocalized(content, sourceLocale)
|
|
250
|
-
const given = extractH1(doc) || prettifySlug(name)
|
|
251
|
-
const title = unwrapLocalized(record?.title, sourceLocale)
|
|
252
|
-
if (typeof title === 'string' && title && title !== given) out.push('a title its first heading does not give')
|
|
253
|
-
}
|
|
254
249
|
return out
|
|
255
250
|
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* The title a folder-mode `.md` page has without a `title:` — its first heading, else its name
|
|
254
|
+
* prettified, as the build gives it (`processFileAsPage`). A pull writes `title:` only where the
|
|
255
|
+
* page's differs.
|
|
256
|
+
*
|
|
257
|
+
* @param {object} record - the page's record
|
|
258
|
+
* @param {{ name: string, sourceLocale: string }} opts
|
|
259
|
+
* @returns {string}
|
|
260
|
+
*/
|
|
261
|
+
export function mdPageImpliedTitle(record, { name, sourceLocale }) {
|
|
262
|
+
const content = (Array.isArray(record?.page_sections) ? record.page_sections : [])[0]?.content
|
|
263
|
+
const doc = isProseMirrorDoc(content) ? content : unwrapLocalized(content, sourceLocale)
|
|
264
|
+
return extractH1(doc) || prettifySlug(name)
|
|
265
|
+
}
|
package/src/uwx/site-project.js
CHANGED
|
@@ -62,7 +62,9 @@ import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
|
|
|
62
62
|
import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
|
|
63
63
|
import { documentLanguages, documentSourceLocale } from './source-locale.js'
|
|
64
64
|
import { siteContentDirs } from './site-dirs.js'
|
|
65
|
-
import { sitePageFiles, mdPageCannotHold, folderModeOf } from './page-files.js'
|
|
65
|
+
import { sitePageFiles, mdPageCannotHold, mdPageImpliedTitle, folderModeOf } from './page-files.js'
|
|
66
|
+
import { ATOMIC_PAGE_KEYS, isAtomicPageKey } from '../site/page-settings.js'
|
|
67
|
+
import { isSectionKey } from '@uniweb/schemas/section'
|
|
66
68
|
import { layoutAreaRoute, readLayoutFolderSync, DEFAULT_LAYOUT } from '../site/layout-folder.js'
|
|
67
69
|
import { layoutNameKey } from '@uniweb/core/layout-name'
|
|
68
70
|
import { orderFolders, rootOrderConfig, parseNumericPrefix, parseWildcardArray, composeLocalizedRoute, stripAtPrefix, compareFilenames, folderModePageFiles, folderModeChildren } from '../site/content-collector.js'
|
|
@@ -415,9 +417,11 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
|
|
|
415
417
|
* structural maps on a localized `content` field are captured into it
|
|
416
418
|
* @param {string} [params.impliedType] - the type a section that names none renders with on this
|
|
417
419
|
* site (`siteDefaultSectionType`), which a file leaves out
|
|
420
|
+
* @param {object} [params.page] - for a page that is this one file, its settings as its frontmatter
|
|
421
|
+
* says them (`atomicPageSettings`): each page key, `undefined` for one the page does not have
|
|
418
422
|
* @returns {'updated'|'unchanged'}
|
|
419
423
|
*/
|
|
420
|
-
export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE, media = null, fileLinks = null, sameFile = null }) {
|
|
424
|
+
export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, collector, freeformRelPath, freeformCandidates = null, writeId = true, context = null, dataModel = null, impliedType = DEFAULT_SECTION_TYPE, media = null, fileLinks = null, sameFile = null, page = null }) {
|
|
421
425
|
// ⛔ A stored `preset` or `input` is not written back: neither has an effect, and the build
|
|
422
426
|
// would only warn about it (2026-09-27).
|
|
423
427
|
// ⛔ No `background` / `theme_override` / `insets` / `fetch`: the site-content Model dropped all
|
|
@@ -438,14 +442,26 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
|
|
|
438
442
|
const sourceContent = unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath, freeformCandidates, context, (tag) => dataModel?.(type, tag) ?? null)
|
|
439
443
|
|
|
440
444
|
const { hidden: paramHidden, fetch: paramFetch, ...paramsRest } = params && typeof params === 'object' ? params : {}
|
|
441
|
-
|
|
445
|
+
// ⭐ A PARAM WHOSE NAME THE FILE GIVES SOMETHING ELSE IS WRITTEN UNDER `props:`, which the build merges
|
|
446
|
+
// into the params (`SECTION_KEYS.props`): a section key's name, and in a page that is this one file a
|
|
447
|
+
// page setting's (`site/page-settings.js`). So is a param the file already keeps there. ⛔ Until
|
|
448
|
+
// 2026-11-08 every param went at the top, so one named `type` or `id` replaced the section's own.
|
|
449
|
+
const kept = readFrontmatterQuietly(filePath)?.props
|
|
450
|
+
const inProps = (key) =>
|
|
451
|
+
isSectionKey(key) || (page !== null && isAtomicPageKey(key)) || (isPlainRecord(kept) && Object.prototype.hasOwnProperty.call(kept, key))
|
|
452
|
+
const top = {}
|
|
453
|
+
const props = {}
|
|
454
|
+
for (const [key, value] of Object.entries(paramsRest)) (inProps(key) ? props : top)[key] = value
|
|
455
|
+
// The page's settings first, where the file is the page (`writeMdPage`).
|
|
456
|
+
const frontmatter = page ? { ...page } : {}
|
|
442
457
|
if (type !== undefined) frontmatter.type = type
|
|
443
458
|
// ⭐ `hidden:` says what the store says: written for a hidden section, and removed from the
|
|
444
459
|
// file of a visible one — an editor toggles it [2026-09-28]. ⛔ Until then a pull dropped it,
|
|
445
460
|
// and the next push un-hid the section. A push before that day sent a file's `hidden:` inside
|
|
446
461
|
// `params`, so one stored there counts when the field is absent.
|
|
447
462
|
frontmatter.hidden = (typeof hidden === 'boolean' ? hidden : paramHidden === true) ? true : undefined
|
|
448
|
-
Object.assign(frontmatter,
|
|
463
|
+
Object.assign(frontmatter, top)
|
|
464
|
+
frontmatter.props = Object.keys(props).length ? props : undefined
|
|
449
465
|
// `id:` only where the file's name does not already give it (`writeId`, `pageSectionsToFiles`).
|
|
450
466
|
if (stable_id !== undefined && writeId) frontmatter.id = stable_id
|
|
451
467
|
|
|
@@ -470,6 +486,15 @@ export function sectionRecordToFile({ filePath, record, sourceLocale = LOCALIZED
|
|
|
470
486
|
})
|
|
471
487
|
}
|
|
472
488
|
|
|
489
|
+
// A file's frontmatter as written, or null where there is no file or it cannot be read.
|
|
490
|
+
function readFrontmatterQuietly(filePath) {
|
|
491
|
+
try {
|
|
492
|
+
return parseFrontmatter(readFileSync(filePath, 'utf8'), filePath).frontmatter || null
|
|
493
|
+
} catch {
|
|
494
|
+
return null
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
|
|
473
498
|
// ---------------------------------------------------------------------------
|
|
474
499
|
// Pages tree → pages/** (+ layout_sections → layout/**)
|
|
475
500
|
// ---------------------------------------------------------------------------
|
|
@@ -1057,9 +1082,11 @@ function isEmptyPage(record, dir) {
|
|
|
1057
1082
|
|
|
1058
1083
|
// ⭐ A FOLDER-MODE `.md` PAGE, WRITTEN BACK IN PLACE: the file is the page and its one section, so the
|
|
1059
1084
|
// section is written into it as any section file is (`sectionRecordToFile`) — its text, its params —
|
|
1060
|
-
// and its frontmatter
|
|
1061
|
-
// left as written, and said. ⛔ Until 2026-11-
|
|
1062
|
-
//
|
|
1085
|
+
// and its frontmatter says the page's settings (`atomicPageSettings`), `hidden:` among them. One the
|
|
1086
|
+
// file cannot hold (`mdPageCannotHold`) is left as written, and said. ⛔ Until 2026-11-08 a page the app
|
|
1087
|
+
// gave a description, a label or a title of its own was held. Until 2026-11-04 a pull left every such
|
|
1088
|
+
// page alone, so an edit made to one in the app was undone by the next push. Returns whether it was
|
|
1089
|
+
// written.
|
|
1063
1090
|
function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLocale }) {
|
|
1064
1091
|
const own = parse(place.file).name
|
|
1065
1092
|
const name = parseNumericPrefix(own).name || own
|
|
@@ -1073,7 +1100,9 @@ function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLoc
|
|
|
1073
1100
|
const stableId = recordStableId(section) || name
|
|
1074
1101
|
// A page renamed in the app moves its file, as a page folder moves (`placeByUuid`).
|
|
1075
1102
|
placeByUuid(ctx, record.$uuid, place.file)
|
|
1103
|
+
const page = atomicPageSettings(record, { name, sourceLocale, existing: readFrontmatterQuietly(place.file), canon: pageContext.route, ctx })
|
|
1076
1104
|
sectionRecordToFile({
|
|
1105
|
+
page,
|
|
1077
1106
|
filePath: place.file,
|
|
1078
1107
|
record: { ...section, hidden: record.hidden === true },
|
|
1079
1108
|
sourceLocale: ctx?.sourceLocale,
|
|
@@ -1092,6 +1121,25 @@ function writeMdPage({ record, place, route, ctx, report, pageContext, sourceLoc
|
|
|
1092
1121
|
return true
|
|
1093
1122
|
}
|
|
1094
1123
|
|
|
1124
|
+
/**
|
|
1125
|
+
* An atomic page's settings as its frontmatter says them (`site/page-settings.js`), by the inverse a
|
|
1126
|
+
* `page.yml` is written by (`pageRecordToYml`): each page key, `undefined` for one the page does not
|
|
1127
|
+
* have, so the file's is removed. Its `title:` only where its first heading, else its name, does not
|
|
1128
|
+
* give it, and its localized URL segments added and never removed, as a `page.yml`'s are
|
|
1129
|
+
* (`pageSlugToYml`).
|
|
1130
|
+
*
|
|
1131
|
+
* @returns {object}
|
|
1132
|
+
*/
|
|
1133
|
+
function atomicPageSettings(record, { name, sourceLocale, existing, canon, ctx }) {
|
|
1134
|
+
const slug = pageSlugToYml(record, canon, existing, sourceLocale, ctx)
|
|
1135
|
+
const yml = pageRecordToYml(record, null, sourceLocale, existing, { slug })
|
|
1136
|
+
const out = {}
|
|
1137
|
+
for (const key of ATOMIC_PAGE_KEYS) out[key] = yml[key]
|
|
1138
|
+
if (out.title === mdPageImpliedTitle(record, { name, sourceLocale })) out.title = undefined
|
|
1139
|
+
if (out.slug === undefined && existing?.slug !== undefined) out.slug = existing.slug
|
|
1140
|
+
return out
|
|
1141
|
+
}
|
|
1142
|
+
|
|
1095
1143
|
// The directory name for a page record (slug, or `[param]/` for a dynamic page).
|
|
1096
1144
|
// `slug` is a localized `{lang: value}` map on the wire (a page route stays
|
|
1097
1145
|
// localized); the directory uses the canonical SOURCE-locale slug. `param_name`
|
package/src/uwx/site.js
CHANGED
|
@@ -792,10 +792,13 @@ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig, media =
|
|
|
792
792
|
}
|
|
793
793
|
|
|
794
794
|
// A folder-mode folder's `.md` files, as the pages the build makes of them (`processFileAsPage`):
|
|
795
|
-
// each a page whose one section is the file,
|
|
796
|
-
//
|
|
797
|
-
//
|
|
798
|
-
//
|
|
795
|
+
// each a page whose one section is the file, a draft when the file says `hidden: true`, slugged by
|
|
796
|
+
// the filename without its numeric prefix — and in the build's order (`folderModePageFiles`).
|
|
797
|
+
// ⭐ The page's settings are what its frontmatter gives the page (`page-settings.js`) — a `title:`
|
|
798
|
+
// else its first heading, a `description:`, a `label:` and the rest — sent as a `page.yml`'s are.
|
|
799
|
+
// ⛔ Until 2026-11-08 it sent the title alone, and those keys went as the section's params. Until
|
|
800
|
+
// 2026-10-23 this lane sent none of these pages and warned instead; a documentation site —
|
|
801
|
+
// folder-mode pages in a mounted repo — published 2 of its 49 pages.
|
|
799
802
|
//
|
|
800
803
|
// Each comes with the name a `pages:` list knows it by.
|
|
801
804
|
async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
|
|
@@ -804,9 +807,9 @@ async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
|
|
|
804
807
|
const records = []
|
|
805
808
|
for (const { file, name } of files) {
|
|
806
809
|
const filePath = join(dirPath, file)
|
|
807
|
-
const { page, assetCollection } = await processFileAsPage(filePath, file, siteRoot, '/')
|
|
810
|
+
const { page, pageConfig, assetCollection } = await processFileAsPage(filePath, file, siteRoot, '/')
|
|
808
811
|
locateSectionMedia(assetCollection, { siteRoot, filePath, sink: ctx.media })
|
|
809
|
-
const config = { title: page.title }
|
|
812
|
+
const config = { ...pageConfig, title: page.title }
|
|
810
813
|
if (page.hidden) config.hidden = true
|
|
811
814
|
const data = buildPageData(config, {
|
|
812
815
|
where: relative(siteRoot, filePath),
|
|
@@ -821,6 +824,8 @@ async function folderModePageRecords(ctx, dirPath, orderConfig, isRoot) {
|
|
|
821
824
|
pageFields,
|
|
822
825
|
})
|
|
823
826
|
const record = withIdentity(data.stable_id || name, data)
|
|
827
|
+
// Its localized URL segments, as a folder's `slug:` gives them (`localizeRouteSlugs`).
|
|
828
|
+
if (isPlainRecord(pageConfig.slug)) record[AUTHORED_SLUG] = pageConfig.slug
|
|
824
829
|
record.page_sections = page.sections.map((s, i) => sectionToRecord(s, i))
|
|
825
830
|
records.push({ name, record })
|
|
826
831
|
}
|