@opentf/afw-docs 0.35.0 → 0.37.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.
@@ -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, highlightCodeFences } from "./highlight.js";
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
- const out = await highlightCodeFences(code);
18
- return out === code ? null : { code: out, type: "js" };
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
  };
@@ -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). At the docs root (`withIndex`), the root's own
138
- * `page.*` is emitted as a standalone "Overview"-style entry; in nested groups the
139
- * folder's own page is the group node's link (added by `buildNode`), so it is not
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
- const node = await buildNode(join(dir, key), `${route}/${key}`, key, meta, ctx, exclude);
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
- /** Build a single subdirectory node: its own link (if it has a page) + children. */
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
  });
@@ -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 `highlightCodeFences`.
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
- if (!code.includes("afw-code-pre")) return code;
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 code;
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
- blocks.forEach((match, i) => {
80
- out += code.slice(last, match.index) + highlighted[i];
81
- last = match.index + match[0].length;
82
- });
83
- return out + code.slice(last);
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), `${route}/${entry.name}`, exclude, onPage);
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, highlightCodeFences } from "./highlight.js";
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. The swap stays inside string
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
- if (!FENCE_SOURCE.test(id.split("?")[0])) return null;
129
- const out = await highlightCodeFences(code);
130
- return out === code ? null : { code: out, map: null };
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.35.0",
3
+ "version": "0.37.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.37.0"
72
+ "@opentf/afw": "0.39.0"
73
73
  },
74
74
  "publishConfig": {
75
75
  "access": "public"
76
76
  },
77
77
  "dependencies": {
78
- "@opentf/afw-compiler": "0.24.0",
78
+ "@opentf/afw-compiler": "0.26.0",
79
79
  "@opentf/syntax-highlighter": "0.5.0"
80
80
  },
81
81
  "devDependencies": {
82
- "@opentf/afw": "0.37.0",
83
- "@opentf/afw-test": "1.32.0",
84
- "@opentf/vite-plugin-afw": "0.5.0",
82
+ "@opentf/afw": "0.39.0",
83
+ "@opentf/afw-test": "1.34.0",
84
+ "@opentf/vite-plugin-afw": "0.7.0",
85
85
  "vite": "8.3.5"
86
86
  },
87
87
  "types": "./types/index.d.ts"