@opentf/afw-docs 0.35.0 → 0.36.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/build/blog-posts-plugin.js +6 -0
- package/build/code-highlight-plugin.js +5 -3
- package/build/docs-nav-plugin.js +18 -9
- package/build/highlight.js +87 -8
- package/build/last-updated-plugin.js +2 -1
- package/build/llms.js +2 -1
- package/build/route-url.js +9 -0
- package/build/vite.js +5 -6
- package/package.json +6 -6
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
// overrides. Drafts and future-dated posts are left out except under `esdev start`
|
|
10
10
|
// (see publish.js).
|
|
11
11
|
|
|
12
|
+
import { isGroupSegment } from "./route-url.js";
|
|
12
13
|
import { exists, join, readEntries, readNames, readText } from "./host.js";
|
|
13
14
|
|
|
14
15
|
import { readFrontmatter } from "./frontmatter.js";
|
|
@@ -95,6 +96,11 @@ async function collectPosts(root, base, exclude, watch, drafts) {
|
|
|
95
96
|
continue;
|
|
96
97
|
}
|
|
97
98
|
const dir = join(root, entry.name);
|
|
99
|
+
// A route group `(2024)` holds posts without being part of their URL.
|
|
100
|
+
if (isGroupSegment(entry.name)) {
|
|
101
|
+
posts.push(...(await collectPosts(dir, base, exclude, watch, drafts)));
|
|
102
|
+
continue;
|
|
103
|
+
}
|
|
98
104
|
const page = (await readNames(dir)).find((n) => PAGE_RE.test(n));
|
|
99
105
|
if (!page) continue;
|
|
100
106
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// A `post` transform, so it sees each `.md`/`.mdx` module after the afw plugin has
|
|
3
3
|
// compiled it to JS, whatever order the plugins are listed in.
|
|
4
4
|
|
|
5
|
-
import { FENCE_SOURCE,
|
|
5
|
+
import { FENCE_SOURCE, highlightModule } from "./highlight.js";
|
|
6
6
|
|
|
7
7
|
/** esdev plugin: highlight the code fences of compiled `.md`/`.mdx` pages. */
|
|
8
8
|
export function codeHighlightPlugin() {
|
|
@@ -14,8 +14,10 @@ export function codeHighlightPlugin() {
|
|
|
14
14
|
async handler(code, id, ctx) {
|
|
15
15
|
// Still Markdown means the afw plugin has not compiled it: not ours to touch.
|
|
16
16
|
if (ctx?.type && ctx.type !== "js") return null;
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
// With a source map for the swap, so the bundler's map chain stays exact (and
|
|
18
|
+
// esdev does not warn SOURCEMAP_BROKEN).
|
|
19
|
+
const out = await highlightModule(code, id);
|
|
20
|
+
return out && { code: out.code, map: out.map, type: "js" };
|
|
19
21
|
},
|
|
20
22
|
},
|
|
21
23
|
};
|
package/build/docs-nav-plugin.js
CHANGED
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
// Tree node shape: `{ title, path?, order?, items?: Node[] }`. A node with `path`
|
|
11
11
|
// is a link; a node with `items` is a (possibly also linked) group.
|
|
12
12
|
|
|
13
|
+
import { childRoute } from "./route-url.js";
|
|
13
14
|
import { exists, join, readEntries, readNames, readText, toFileUrl } from "./host.js";
|
|
14
15
|
import { readFrontmatter } from "./frontmatter.js";
|
|
15
16
|
import { isUnpublished, showsUnpublished } from "./publish.js";
|
|
@@ -111,7 +112,7 @@ async function pageFile(dir) {
|
|
|
111
112
|
}
|
|
112
113
|
|
|
113
114
|
function humanize(seg) {
|
|
114
|
-
return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
|
|
115
|
+
return seg.replace(/^\((.+)\)$/, "$1").replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
|
|
115
116
|
}
|
|
116
117
|
|
|
117
118
|
/** Order child keys: those named in `_meta` first (in declared order), rest A→Z. */
|
|
@@ -134,10 +135,10 @@ function metaLabel(meta, key) {
|
|
|
134
135
|
|
|
135
136
|
/**
|
|
136
137
|
* Build the ordered items of a section directory. Each subdirectory becomes a child
|
|
137
|
-
* node (a link and/or a group).
|
|
138
|
-
* `page.*` is emitted as a standalone
|
|
139
|
-
* folder's
|
|
140
|
-
* repeated here. Order + labels come from `_meta`.
|
|
138
|
+
* node (a link and/or a group). With `withIndex` (the docs root, or a group whose
|
|
139
|
+
* `_meta` lists `index`), the folder's own `page.*` is emitted as a standalone
|
|
140
|
+
* "Overview"-style entry; otherwise a nested folder's page is the group node's link
|
|
141
|
+
* (added by `buildNode`), so it is not repeated here. Order + labels come from `_meta`.
|
|
141
142
|
*/
|
|
142
143
|
async function buildSection(dir, route, ctx, withIndex = false, exclude = new Set()) {
|
|
143
144
|
const meta = await loadMeta(dir, ctx);
|
|
@@ -173,13 +174,19 @@ async function buildSection(dir, route, ctx, withIndex = false, exclude = new Se
|
|
|
173
174
|
);
|
|
174
175
|
continue;
|
|
175
176
|
}
|
|
176
|
-
|
|
177
|
+
// A route-group folder `(guides)` is a sidebar group, but not part of the URL.
|
|
178
|
+
const node = await buildNode(join(dir, key), childRoute(route, key), key, meta, ctx, exclude);
|
|
177
179
|
if (node) items.push(node);
|
|
178
180
|
}
|
|
179
181
|
return items;
|
|
180
182
|
}
|
|
181
183
|
|
|
182
|
-
/**
|
|
184
|
+
/**
|
|
185
|
+
* Build a single subdirectory node: its own link (if it has a page) + children.
|
|
186
|
+
*
|
|
187
|
+
* A folder whose `_meta` lists `index` keeps its heading a plain label: its own page
|
|
188
|
+
* becomes a child entry under that label (`index: "Overview"`), at the same URL.
|
|
189
|
+
*/
|
|
183
190
|
async function buildNode(dir, route, key, parentMeta, ctx, exclude) {
|
|
184
191
|
const pf = await pageFile(dir);
|
|
185
192
|
let fm = {};
|
|
@@ -187,16 +194,18 @@ async function buildNode(dir, route, key, parentMeta, ctx, exclude) {
|
|
|
187
194
|
ctx.watch.push(pf);
|
|
188
195
|
if (MD_RE.test(pf)) fm = await readFrontmatter(pf);
|
|
189
196
|
}
|
|
190
|
-
const children = await buildSection(dir, route, ctx, false, exclude);
|
|
191
197
|
// An unpublished page is left out of the production nav; its children still show.
|
|
192
198
|
const page = pf && (ctx.drafts || !isUnpublished(fm)) ? pf : null;
|
|
199
|
+
const meta = page ? await loadMeta(dir, ctx) : null;
|
|
200
|
+
const ownIndex = Boolean(meta && !Array.isArray(meta) && "index" in meta);
|
|
201
|
+
const children = await buildSection(dir, route, ctx, ownIndex, exclude);
|
|
193
202
|
// A directory that has neither a page nor children contributes nothing.
|
|
194
203
|
if (!page && children.length === 0) return null;
|
|
195
204
|
|
|
196
205
|
const title = metaLabel(parentMeta, key) ?? fm.sidebar_label ?? fm.title ?? humanize(key);
|
|
197
206
|
return clean({
|
|
198
207
|
title,
|
|
199
|
-
path: page ? route : undefined,
|
|
208
|
+
path: page && !ownIndex ? route : undefined,
|
|
200
209
|
order: fm.order,
|
|
201
210
|
items: children.length ? children : undefined,
|
|
202
211
|
});
|
package/build/highlight.js
CHANGED
|
@@ -9,7 +9,8 @@
|
|
|
9
9
|
// hydration adopts the same HTML), with no highlighter shipped to the browser.
|
|
10
10
|
//
|
|
11
11
|
// Toolchain-neutral: no `runtime:`/`node:` imports. `codeHighlightPlugin` (esdev,
|
|
12
|
-
// build/index.js) and the Vite plugin (build/vite.js) both call `
|
|
12
|
+
// build/index.js) and the Vite plugin (build/vite.js) both call `highlightModule`, which
|
|
13
|
+
// also returns a source map for the swap.
|
|
13
14
|
|
|
14
15
|
import { highlightCode } from "@opentf/syntax-highlighter";
|
|
15
16
|
|
|
@@ -63,9 +64,24 @@ export function encodeJsString(text) {
|
|
|
63
64
|
* there was nothing to highlight).
|
|
64
65
|
*/
|
|
65
66
|
export async function highlightCodeFences(code) {
|
|
66
|
-
|
|
67
|
+
return (await highlightModule(code, "module.js"))?.code ?? code;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* `highlightCodeFences` for a bundler transform: the highlighted module and a source
|
|
72
|
+
* map from it back to `code`, or `null` when nothing changed. The swaps stay inside
|
|
73
|
+
* string literals on their own lines (escaped text has no raw newline), so the map is
|
|
74
|
+
* an identity map whose columns shift after each swapped block — written per token, so
|
|
75
|
+
* positions in the rest of the line stay exact through the bundler's map chain.
|
|
76
|
+
*
|
|
77
|
+
* @param {string} code The compiled JS of a `.md`/`.mdx` module.
|
|
78
|
+
* @param {string} id The module id (the map's source).
|
|
79
|
+
* @returns {Promise<{ code: string, map: object } | null>}
|
|
80
|
+
*/
|
|
81
|
+
export async function highlightModule(code, id) {
|
|
82
|
+
if (!code.includes("afw-code-pre")) return null;
|
|
67
83
|
const blocks = [...code.matchAll(FENCE)];
|
|
68
|
-
if (blocks.length === 0) return
|
|
84
|
+
if (blocks.length === 0) return null;
|
|
69
85
|
// The hydrating build carries each page's HTML twice; highlight each block once.
|
|
70
86
|
const cache = new Map();
|
|
71
87
|
const highlighted = await Promise.all(
|
|
@@ -74,13 +90,76 @@ export async function highlightCodeFences(code) {
|
|
|
74
90
|
return cache.get(block);
|
|
75
91
|
}),
|
|
76
92
|
);
|
|
93
|
+
const edits = blocks
|
|
94
|
+
.map((match, i) => ({ start: match.index, end: match.index + match[0].length, text: highlighted[i] }))
|
|
95
|
+
.filter((edit) => edit.text !== code.slice(edit.start, edit.end));
|
|
96
|
+
if (edits.length === 0) return null;
|
|
97
|
+
return applyEdits(code, edits, id);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Splice single-line `edits` (sorted, non-overlapping) into `code`, with a source map. */
|
|
101
|
+
function applyEdits(code, edits, source) {
|
|
102
|
+
const VLQ = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
|
|
103
|
+
const vlq = (value) => {
|
|
104
|
+
let n = value < 0 ? (-value << 1) | 1 : value << 1;
|
|
105
|
+
let out = "";
|
|
106
|
+
do {
|
|
107
|
+
let digit = n & 31;
|
|
108
|
+
n >>>= 5;
|
|
109
|
+
if (n > 0) digit |= 32;
|
|
110
|
+
out += VLQ[digit];
|
|
111
|
+
} while (n > 0);
|
|
112
|
+
return out;
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
const lines = [];
|
|
116
|
+
let segments = [];
|
|
117
|
+
let genCol = 0;
|
|
118
|
+
let prevGenCol = 0;
|
|
119
|
+
let prevLine = 0;
|
|
120
|
+
let prevCol = 0;
|
|
121
|
+
let line = 0;
|
|
122
|
+
let col = 0;
|
|
123
|
+
const mark = () => {
|
|
124
|
+
segments.push(vlq(genCol - prevGenCol) + "A" + vlq(line - prevLine) + vlq(col - prevCol));
|
|
125
|
+
prevGenCol = genCol;
|
|
126
|
+
prevLine = line;
|
|
127
|
+
prevCol = col;
|
|
128
|
+
};
|
|
129
|
+
// Copy original text, marking each token's start so every column maps exactly.
|
|
130
|
+
const copy = (text) => {
|
|
131
|
+
for (const [token] of text.matchAll(/\n|[^\S\n]+|\w+|[^\w\s]/g)) {
|
|
132
|
+
if (token === "\n") {
|
|
133
|
+
lines.push(segments.join(","));
|
|
134
|
+
segments = [];
|
|
135
|
+
genCol = prevGenCol = 0;
|
|
136
|
+
line++;
|
|
137
|
+
col = 0;
|
|
138
|
+
continue;
|
|
139
|
+
}
|
|
140
|
+
if (!/^\s/.test(token)) mark();
|
|
141
|
+
genCol += token.length;
|
|
142
|
+
col += token.length;
|
|
143
|
+
}
|
|
144
|
+
};
|
|
145
|
+
|
|
77
146
|
let out = "";
|
|
78
147
|
let last = 0;
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
148
|
+
for (const edit of edits) {
|
|
149
|
+
copy(code.slice(last, edit.start));
|
|
150
|
+
mark(); // the swapped block starts where the original one did
|
|
151
|
+
out += code.slice(last, edit.start) + edit.text;
|
|
152
|
+
genCol += edit.text.length;
|
|
153
|
+
col += edit.end - edit.start;
|
|
154
|
+
last = edit.end;
|
|
155
|
+
}
|
|
156
|
+
copy(code.slice(last));
|
|
157
|
+
out += code.slice(last);
|
|
158
|
+
lines.push(segments.join(","));
|
|
159
|
+
return {
|
|
160
|
+
code: out,
|
|
161
|
+
map: { version: 3, sources: [source], sourcesContent: [code], names: [], mappings: lines.join(";") },
|
|
162
|
+
};
|
|
84
163
|
}
|
|
85
164
|
|
|
86
165
|
async function highlightBlock(block, lang, body) {
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
// The same map is needed by the SSG step for the `article:modified_time` SEO tag, so
|
|
9
9
|
// the scan is exposed as a callable (`loadLastUpdated`) too.
|
|
10
10
|
|
|
11
|
+
import { childRoute } from "./route-url.js";
|
|
11
12
|
import { cwd, join, readEntries, relative, resolve, runOut } from "./host.js";
|
|
12
13
|
import { readFrontmatter } from "./frontmatter.js";
|
|
13
14
|
import { resolveLastUpdated } from "./last-updated.js";
|
|
@@ -105,7 +106,7 @@ async function walk(dir, route, exclude, onPage) {
|
|
|
105
106
|
if (entry.name.startsWith(".") || entry.name.startsWith("_") || exclude.has(entry.name)) {
|
|
106
107
|
continue;
|
|
107
108
|
}
|
|
108
|
-
await walk(join(dir, entry.name),
|
|
109
|
+
await walk(join(dir, entry.name), childRoute(route, entry.name), exclude, onPage);
|
|
109
110
|
} else if (PAGE_RE.test(entry.name)) {
|
|
110
111
|
await onPage(join(dir, entry.name), route || "/");
|
|
111
112
|
}
|
package/build/llms.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { isGroupSegment } from "./route-url.js";
|
|
1
2
|
import { dirname, relative } from "./host.js";
|
|
2
3
|
|
|
3
4
|
import { exists, readText } from "./host.js";
|
|
@@ -20,7 +21,7 @@ function routePath(appDir, file) {
|
|
|
20
21
|
if (segments.some((seg) => seg.startsWith("_") || seg.startsWith(".") || seg.includes("["))) {
|
|
21
22
|
return null;
|
|
22
23
|
}
|
|
23
|
-
return "/" + segments.join("/");
|
|
24
|
+
return "/" + segments.filter((seg) => !isGroupSegment(seg)).join("/");
|
|
24
25
|
}
|
|
25
26
|
|
|
26
27
|
function humanize(seg) {
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// Route groups — folders in parentheses, `(guides)` — organize pages without being
|
|
2
|
+
// part of the URL. Every docs plugin that turns a folder into a URL drops them here,
|
|
3
|
+
// matching the framework router.
|
|
4
|
+
|
|
5
|
+
/** Is `name` a route-group folder? */
|
|
6
|
+
export const isGroupSegment = (name) => /^\(.+\)$/.test(name);
|
|
7
|
+
|
|
8
|
+
/** Append folder `name` to URL `route`, unless it is a route group. */
|
|
9
|
+
export const childRoute = (route, name) => (isGroupSegment(name) ? route : `${route}/${name}`);
|
package/build/vite.js
CHANGED
|
@@ -19,7 +19,7 @@ import { nodeHost } from "./hosts/node.js";
|
|
|
19
19
|
import { blogPostsModule } from "./blog-posts-plugin.js";
|
|
20
20
|
import { docsNavModule } from "./docs-nav-plugin.js";
|
|
21
21
|
import { blogDir, finishSite, wantsLastUpdated } from "./finish.js";
|
|
22
|
-
import { FENCE_SOURCE,
|
|
22
|
+
import { FENCE_SOURCE, highlightModule } from "./highlight.js";
|
|
23
23
|
import { lastUpdatedModule, loadLastUpdated } from "./last-updated-plugin.js";
|
|
24
24
|
|
|
25
25
|
useHost(nodeHost);
|
|
@@ -120,14 +120,13 @@ export default function afwDocs({ config: given, appDir: appDirOption = "app", e
|
|
|
120
120
|
},
|
|
121
121
|
|
|
122
122
|
// Code-fence highlighting (highlight.js): `post`, so it runs on each `.md`/`.mdx`
|
|
123
|
-
// page after @opentf/vite-plugin-afw has compiled it
|
|
124
|
-
// literals and adds no lines.
|
|
123
|
+
// page after @opentf/vite-plugin-afw has compiled it, with a source map for the swap.
|
|
125
124
|
transform: {
|
|
126
125
|
order: "post",
|
|
127
126
|
async handler(code, id) {
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
return
|
|
127
|
+
const file = id.split("?")[0];
|
|
128
|
+
if (!FENCE_SOURCE.test(file)) return null;
|
|
129
|
+
return highlightModule(code, file);
|
|
131
130
|
},
|
|
132
131
|
},
|
|
133
132
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@opentf/afw-docs",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.36.0",
|
|
4
4
|
"description": "Documentation and blog sites built as ordinary AFW apps.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -69,19 +69,19 @@
|
|
|
69
69
|
"bugs": "https://github.com/Open-Tech-Foundation/afw/issues",
|
|
70
70
|
"license": "MIT",
|
|
71
71
|
"peerDependencies": {
|
|
72
|
-
"@opentf/afw": "0.
|
|
72
|
+
"@opentf/afw": "0.38.0"
|
|
73
73
|
},
|
|
74
74
|
"publishConfig": {
|
|
75
75
|
"access": "public"
|
|
76
76
|
},
|
|
77
77
|
"dependencies": {
|
|
78
|
-
"@opentf/afw-compiler": "0.
|
|
78
|
+
"@opentf/afw-compiler": "0.25.0",
|
|
79
79
|
"@opentf/syntax-highlighter": "0.5.0"
|
|
80
80
|
},
|
|
81
81
|
"devDependencies": {
|
|
82
|
-
"@opentf/afw": "0.
|
|
83
|
-
"@opentf/afw-test": "1.
|
|
84
|
-
"@opentf/vite-plugin-afw": "0.
|
|
82
|
+
"@opentf/afw": "0.38.0",
|
|
83
|
+
"@opentf/afw-test": "1.33.0",
|
|
84
|
+
"@opentf/vite-plugin-afw": "0.6.0",
|
|
85
85
|
"vite": "8.3.5"
|
|
86
86
|
},
|
|
87
87
|
"types": "./types/index.d.ts"
|