@opentf/afw-docs 0.34.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/README.md CHANGED
@@ -80,14 +80,30 @@ to an existing project, import its stylesheet and register the build plugins:
80
80
  {
81
81
  "plugins": [
82
82
  { "module": "@opentf/esdev-plugin-afw", "options": { "mode": "ssg" } },
83
- { "module": "@opentf/afw-docs/build", "export": "docsNavPlugin", "options": { "appDir": "app" } },
84
- { "module": "@opentf/afw-docs/build", "export": "lastUpdatedPlugin", "options": { "appDir": "app" } },
85
- { "module": "@opentf/afw-docs/build", "export": "blogPostsPlugin", "options": { "appDir": "app", "contentDir": "blog" } }
83
+ { "module": "@opentf/afw-docs/build", "export": "afwDocsPlugin", "options": { "appDir": "app" } }
86
84
  ]
87
85
  }
88
86
  ```
89
87
 
90
- `appDir` is resolved from the directory esdev runs in.
88
+ `afwDocsPlugin` is the whole docs toolchain in one entry (esdev 0.27 or later). It reads
89
+ `afw.config.js` and enables what the config asks for:
90
+
91
+ - `docs` → the sidebar navigation (`@opentf/afw-docs/nav`).
92
+ - `blog` → the post list (`@opentf/afw-docs/posts`), from `blog.dir`.
93
+ - `lastUpdated` → the per-page dates and edit links (`@opentf/afw-docs/updated`).
94
+ - Always → code-fence highlighting with
95
+ [`@opentf/syntax-highlighter`](https://syntax-highlighter.opentechf.org), at build
96
+ time on each compiled `.md`/`.mdx` page. Prerendered and client-rendered pages carry
97
+ the same colors; nothing highlights in the browser. The theme colors tokens with
98
+ GitHub Light and GitHub Dark, following `data-theme`.
99
+
100
+ Options:
101
+
102
+ - `appDir` — the routes folder, resolved from the directory esdev runs in (default `"app"`).
103
+ - `exclude` — folders under it that hold no pages.
104
+
105
+ The individual plugins (`docsNavPlugin`, `blogPostsPlugin`, `lastUpdatedPlugin`,
106
+ `codeHighlightPlugin`) are still exported for custom setups.
91
107
 
92
108
  ### With Vite
93
109
 
@@ -148,7 +164,7 @@ export default defineDocsConfig({
148
164
  | `@opentf/afw-docs` | Every component above, plus `createSearch` |
149
165
  | `@opentf/afw-docs/theme` | The default light/dark stylesheet |
150
166
  | `@opentf/afw-docs/config` | `defineDocsConfig` and the config types |
151
- | `@opentf/afw-docs/build` | `docsNavPlugin`, `blogPostsPlugin`, `lastUpdatedPlugin`, feed and `llms.txt` renderers (esdev) |
167
+ | `@opentf/afw-docs/build` | `afwDocsPlugin` (all of the below as one entry), `docsNavPlugin`, `blogPostsPlugin`, `lastUpdatedPlugin`, `codeHighlightPlugin`, feed and `llms.txt` renderers (esdev) |
152
168
  | `@opentf/afw-docs/vite` | `afwDocs()`: the same generators as one Vite plugin |
153
169
  | `@opentf/afw-docs/nav`, `/posts`, `/updated` | Generated navigation, post list and last-updated map |
154
170
  | `@opentf/afw-docs/search` | Browser search: `createSearch`, `tokenize`, `excerptParts` |
@@ -0,0 +1,51 @@
1
+ // `afwDocsPlugin` — the whole docs toolchain for esdev as one `esdev.json` entry:
2
+ //
3
+ // { "module": "@opentf/afw-docs/build", "export": "afwDocsPlugin", "options": { "appDir": "app" } }
4
+ //
5
+ // It reads the project's afw.config and returns the plugins the config asks for — the
6
+ // same set `afwDocs()` serves on Vite:
7
+ // - `docs` → the sidebar navigation (`@opentf/afw-docs/nav`);
8
+ // - `blog` → the post list (`@opentf/afw-docs/posts`);
9
+ // - `lastUpdated` (docs or blog) → the per-page dates (`@opentf/afw-docs/updated`);
10
+ // - always → code-fence highlighting of compiled `.md`/`.mdx` pages.
11
+ // esdev (0.27+) takes a list from one entry, in the entry's place in `plugins`.
12
+ // Toolchain-neutral apart from the host it reads files through.
13
+
14
+ import { exists, join, readText, toFileUrl, cwd } from "./host.js";
15
+ import { blogPostsPlugin } from "./blog-posts-plugin.js";
16
+ import { codeHighlightPlugin } from "./code-highlight-plugin.js";
17
+ import { docsNavPlugin } from "./docs-nav-plugin.js";
18
+ import { blogDir, wantsLastUpdated } from "./finish.js";
19
+ import { lastUpdatedPlugin } from "./last-updated-plugin.js";
20
+
21
+ /** The project's afw.config (`.json`, `.js` or `.mjs`) in `root`, or `{}`. */
22
+ export async function loadDocsConfig(root) {
23
+ const json = join(root, "afw.config.json");
24
+ if (await exists(json)) return JSON.parse(await readText(json)) ?? {};
25
+ for (const name of ["afw.config.js", "afw.config.mjs"]) {
26
+ const file = join(root, name);
27
+ if (await exists(file)) return (await import(toFileUrl(file))).default ?? {};
28
+ }
29
+ return {};
30
+ }
31
+
32
+ /**
33
+ * esdev plugin factory: every docs build plugin the project's config enables.
34
+ *
35
+ * @param {{ appDir?: string, exclude?: string[], root?: string, config?: object }} [options]
36
+ * `appDir` — the routes folder (default `"app"`, resolved from where esdev runs).
37
+ * `exclude` — folders under it that hold no pages. `root` — where afw.config lives
38
+ * (default: where esdev runs). `config` — use this config instead of reading one.
39
+ * @returns {Promise<object[]>} The plugins, in order.
40
+ */
41
+ export async function afwDocsPlugin({ appDir = "app", exclude = [], root, config } = {}) {
42
+ const docsConfig = config ?? (await loadDocsConfig(root ?? cwd()));
43
+ const excluded = new Set(exclude);
44
+ const blog = blogDir(docsConfig);
45
+ return [
46
+ docsConfig.docs && docsNavPlugin({ appDir, exclude: excluded }),
47
+ blog && blogPostsPlugin({ appDir, contentDir: blog, exclude: excluded }),
48
+ wantsLastUpdated(docsConfig) && lastUpdatedPlugin({ appDir, exclude: excluded, blogDir: blog }),
49
+ codeHighlightPlugin(),
50
+ ].filter(Boolean);
51
+ }
@@ -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
 
@@ -0,0 +1,24 @@
1
+ // `codeHighlightPlugin` — the esdev half of docs code highlighting (see highlight.js).
2
+ // A `post` transform, so it sees each `.md`/`.mdx` module after the afw plugin has
3
+ // compiled it to JS, whatever order the plugins are listed in.
4
+
5
+ import { FENCE_SOURCE, highlightModule } from "./highlight.js";
6
+
7
+ /** esdev plugin: highlight the code fences of compiled `.md`/`.mdx` pages. */
8
+ export function codeHighlightPlugin() {
9
+ return {
10
+ name: "afw-docs-highlight",
11
+ transform: {
12
+ order: "post",
13
+ filter: { id: FENCE_SOURCE },
14
+ async handler(code, id, ctx) {
15
+ // Still Markdown means the afw plugin has not compiled it: not ours to touch.
16
+ if (ctx?.type && ctx.type !== "js") return null;
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" };
21
+ },
22
+ },
23
+ };
24
+ }
@@ -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
  });
@@ -0,0 +1,174 @@
1
+ // Code-fence highlighting for docs and blog pages, with @opentf/syntax-highlighter.
2
+ //
3
+ // afwc lowers a Markdown fence to a plain, escaped block —
4
+ // `<pre class="afw-code-pre"><code class="language-js">…</code></pre>` — inside the
5
+ // HTML string of the page's `CodeFence`. This pass runs on the *compiled* module,
6
+ // after afwc, and swaps each block's text for highlighted `<span class="sh-*">`
7
+ // markup. The module itself then carries the colors, so a prerendered page and a
8
+ // page rendered after client-side navigation show the same highlighted code (and
9
+ // hydration adopts the same HTML), with no highlighter shipped to the browser.
10
+ //
11
+ // Toolchain-neutral: no `runtime:`/`node:` imports. `codeHighlightPlugin` (esdev,
12
+ // build/index.js) and the Vite plugin (build/vite.js) both call `highlightModule`, which
13
+ // also returns a source map for the swap.
14
+
15
+ import { highlightCode } from "@opentf/syntax-highlighter";
16
+
17
+ /** Compiled `.md`/`.mdx` modules — the only ones afwc writes code fences into. */
18
+ export const FENCE_SOURCE = /\.mdx?$/;
19
+
20
+ // One fence's block as it sits inside a double-quoted JS string literal: the quotes
21
+ // around attribute values are escaped (`\"`). Its text holds no `<` (HTML-escaped),
22
+ // so the lazy match cannot run past its own `</code>`.
23
+ const FENCE = /<pre class=\\"afw-code-pre\\"><code class=\\"language-([^"\\<>]+)\\">([^<]*)<\/code><\/pre>/g;
24
+
25
+ const HTML_ENTITIES = { "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'", "&amp;": "&" };
26
+
27
+ /** Undo the HTML escaping afwc applied to the fence text. */
28
+ function htmlUnescape(text) {
29
+ return text.replace(/&(?:lt|gt|quot|#39|amp);/g, (entity) => HTML_ENTITIES[entity]);
30
+ }
31
+
32
+ const SIMPLE_ESCAPES = { n: "\n", r: "\r", t: "\t", b: "\b", f: "\f", v: "\v", 0: "\0" };
33
+
34
+ /** Decode the body of a JS string literal (the part between its quotes). */
35
+ export function decodeJsString(body) {
36
+ return body.replace(/\\(u\{([0-9a-fA-F]+)\}|u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2})|\r\n|[\s\S])/g, (_, esc, cp, u4, x2) => {
37
+ if (cp) return String.fromCodePoint(parseInt(cp, 16));
38
+ if (u4 || x2) return String.fromCharCode(parseInt(u4 ?? x2, 16));
39
+ if (esc === "\n" || esc === "\r\n" || esc === "\u2028" || esc === "\u2029") return ""; // line continuation
40
+ return SIMPLE_ESCAPES[esc] ?? esc;
41
+ });
42
+ }
43
+
44
+ /** Encode text as the body of a double-quoted JS string literal. */
45
+ export function encodeJsString(text) {
46
+ return text.replace(/[\\"\n\r\t\u2028\u2029]/g, (c) =>
47
+ c === "\\" ? "\\\\"
48
+ : c === '"' ? '\\"'
49
+ : c === "\n" ? "\\n"
50
+ : c === "\r" ? "\\r"
51
+ : c === "\t" ? "\\t"
52
+ : c === "\u2028" ? "\\u2028"
53
+ : "\\u2029",
54
+ );
55
+ }
56
+
57
+ /**
58
+ * Highlight every code fence in a compiled module. A fence in a language the
59
+ * highlighter does not know (or one that fails) keeps its plain text; a fence with
60
+ * no language has no `language-*` class and is never touched.
61
+ *
62
+ * @param {string} code The compiled JS of a `.md`/`.mdx` module.
63
+ * @returns {Promise<string>} The module with highlighted fences (`code` itself when
64
+ * there was nothing to highlight).
65
+ */
66
+ export async function highlightCodeFences(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;
83
+ const blocks = [...code.matchAll(FENCE)];
84
+ if (blocks.length === 0) return null;
85
+ // The hydrating build carries each page's HTML twice; highlight each block once.
86
+ const cache = new Map();
87
+ const highlighted = await Promise.all(
88
+ blocks.map(([block, lang, body]) => {
89
+ if (!cache.has(block)) cache.set(block, highlightBlock(block, lang, body));
90
+ return cache.get(block);
91
+ }),
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
+
146
+ let out = "";
147
+ let last = 0;
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
+ };
163
+ }
164
+
165
+ async function highlightBlock(block, lang, body) {
166
+ try {
167
+ const source = htmlUnescape(decodeJsString(body));
168
+ const { html, language } = await highlightCode(source, { language: htmlUnescape(lang) });
169
+ if (!language) return block;
170
+ return `<pre class=\\"afw-code-pre\\"><code class=\\"language-${lang}\\">${encodeJsString(html)}</code></pre>`;
171
+ } catch {
172
+ return block;
173
+ }
174
+ }
package/build/index.js CHANGED
@@ -10,7 +10,10 @@ import { esdevHost } from "./hosts/esdev.js";
10
10
 
11
11
  useHost(esdevHost);
12
12
 
13
+ export { afwDocsPlugin, loadDocsConfig } from "./afw-docs-plugin.js";
13
14
  export { docsNavPlugin } from "./docs-nav-plugin.js";
15
+ export { codeHighlightPlugin } from "./code-highlight-plugin.js";
16
+ export { highlightCodeFences } from "./highlight.js";
14
17
  export { blogPostsPlugin, loadPosts } from "./blog-posts-plugin.js";
15
18
  export { lastUpdatedPlugin, loadLastUpdated } from "./last-updated-plugin.js";
16
19
  export { isUnpublished } from "./publish.js";
@@ -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,6 +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, highlightModule } from "./highlight.js";
22
23
  import { lastUpdatedModule, loadLastUpdated } from "./last-updated-plugin.js";
23
24
 
24
25
  useHost(nodeHost);
@@ -118,6 +119,17 @@ export default function afwDocs({ config: given, appDir: appDirOption = "app", e
118
119
  return { code, map: null };
119
120
  },
120
121
 
122
+ // Code-fence highlighting (highlight.js): `post`, so it runs on each `.md`/`.mdx`
123
+ // page after @opentf/vite-plugin-afw has compiled it, with a source map for the swap.
124
+ transform: {
125
+ order: "post",
126
+ async handler(code, id) {
127
+ const file = id.split("?")[0];
128
+ if (!FENCE_SOURCE.test(file)) return null;
129
+ return highlightModule(code, file);
130
+ },
131
+ },
132
+
121
133
  // Read by @opentf/vite-plugin-afw around its SSG prerender.
122
134
  api: {
123
135
  /** Data the prerender needs: the site URL and per-page last-updated times. */
@@ -6,18 +6,19 @@ import { Link, RawHtml, router } from "@opentf/afw";
6
6
  // Emitted beside the nav (JSON-LD is discovered wherever it sits). `siteUrl`
7
7
  // (optional site origin) absolutizes the item URLs; without it they stay
8
8
  // route-relative. `<` is escaped so the payload can't break out of the script.
9
+ // Only crumbs with a page are listed: a sidebar group without its own page has no
10
+ // URL, and Google rejects a ListItem without `item` ("Missing field 'item'").
11
+ // Positions count the listed crumbs, so they stay 1, 2, 3…
9
12
  function breadcrumbJsonLd(trail, siteUrl) {
10
- if (!trail.length) return "";
13
+ const pages = trail.filter((it) => it.path);
14
+ if (!pages.length) return "";
11
15
  const base = (siteUrl || "").replace(/\/+$/, "");
12
- const items = trail.map((it, i) => {
13
- const entry = {
14
- "@type": "ListItem",
15
- position: i + 1,
16
- name: it.title,
17
- };
18
- if (it.path) entry.item = base + it.path;
19
- return entry;
20
- });
16
+ const items = pages.map((it, i) => ({
17
+ "@type": "ListItem",
18
+ position: i + 1,
19
+ name: it.title,
20
+ item: base + it.path,
21
+ }));
21
22
  const json = JSON.stringify({
22
23
  "@context": "https://schema.org",
23
24
  "@type": "BreadcrumbList",
@@ -2,7 +2,7 @@
2
2
  // an optional language/filename label and a copy button, above a `<pre>`). Use it for
3
3
  // code that doesn't come from a Markdown fence — e.g. a code panel inside `Tabs`:
4
4
  // `{ label, content: <CodeBlock code="…" /> }`. The text is NOT syntax-highlighted —
5
- // highlighting is a build-time (syntect) pass that only sees literal Markdown fences,
5
+ // highlighting is a build-time pass (build/highlight.js) over compiled Markdown fences,
6
6
  // not a runtime string prop; runtime highlighting here is deferred future work. The
7
7
  // copy button owns its own behavior via `onclick` (see `copyWithFeedback`), so it
8
8
  // works in any layout — not just the docs shell. The icon glyphs go through `RawHtml`
@@ -1,7 +1,9 @@
1
1
  // Search box trigger in the navbar. Calls the global opener that the AFW Search-backed
2
2
  // <Search> modal installs on `window` (the ⌘K / Ctrl+K shortcut opens it too). Shows
3
3
  // the shortcut as a hint; the modifier resolves to ⌘ on Apple platforms, Ctrl
4
- // elsewhere, on mount.
4
+ // elsewhere, on mount. The accessible name is the visible text ("Search Ctrl K"), so
5
+ // what a speech-input user reads on the button is what they can say to press it
6
+ // (WCAG 2.5.3, "Label in Name"); `aria-keyshortcuts` announces the shortcut itself.
5
7
 
6
8
  import { onMount } from "@opentf/afw";
7
9
 
@@ -20,12 +22,12 @@ export default function SearchTrigger() {
20
22
  };
21
23
 
22
24
  return (
23
- <button class="afwd-search-trigger" onclick={open} aria-label="Search docs">
24
- <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
25
+ <button type="button" class="afwd-search-trigger" onclick={open} aria-keyshortcuts="Control+K Meta+K">
26
+ <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">
25
27
  <circle cx="11" cy="11" r="7" />
26
28
  <line x1="21" y1="21" x2="16.65" y2="16.65" stroke-linecap="round" />
27
29
  </svg>
28
- <span class="afwd-search-label">Search</span>
30
+ <span class="afwd-search-label">Search</span>{" "}
29
31
  <kbd class="afwd-search-kbd">{() => `${mod} K`}</kbd>
30
32
  </button>
31
33
  );
package/index.js CHANGED
@@ -1,40 +1,10 @@
1
1
  // Public barrel for @opentf/afw-docs.
2
2
  //
3
3
  // Components are shipped as JSX source and compiled by the consuming app's pipeline
4
- // (the `@opentf/afw` Link.jsx model) — each becomes a `web-*` Custom Element with
5
- // CSR + SSG renderers for free. afwc compiles JSX tags to element *strings*
6
- // (`afw-callout`), so the JS import of a component would be tree-shaken; the bare
7
- // `import "./components/X.jsx"` retains its `customElements.define` side effect
8
- // (the compiled modules are marked side-effectful), and the re-export lets authors
9
- // pull a component in by name (`import { Callout } from "@opentf/afw-docs"`).
10
-
11
- import "./components/DocsLayout.jsx";
12
- import "./components/Navbar.jsx";
13
- import "./components/Sidebar.jsx";
14
- import "./components/SidebarNode.jsx";
15
- import "./components/Toc.jsx";
16
- import "./components/Footer.jsx";
17
- import "./components/Breadcrumbs.jsx";
18
- import "./components/Pagination.jsx";
19
- import "./components/LastUpdated.jsx";
20
- import "./components/ThemeToggle.jsx";
21
- import "./components/SearchTrigger.jsx";
22
- import "./components/Search.jsx";
23
- import "./components/Callout.jsx";
24
- import "./components/CodeBlock.jsx";
25
- import "./components/Tabs.jsx";
26
- import "./components/Steps.jsx";
27
- import "./components/Table.jsx";
28
- import "./components/Cards.jsx";
29
- import "./components/Card.jsx";
30
- import "./components/Tooltip.jsx";
31
- import "./components/BlogLayout.jsx";
32
- import "./components/PostList.jsx";
33
- import "./components/PostCard.jsx";
34
- import "./components/PostBanner.jsx";
35
- import "./components/PostMeta.jsx";
36
- import "./components/ReadingTime.jsx";
37
- import "./components/FeedLinks.jsx";
4
+ // (the `@opentf/afw` Link.jsx model) — each becomes a Custom Element with CSR + SSG
5
+ // renderers. Plain re-exports are enough: a component registers on the first read of
6
+ // its `.tag`, which every place that renders it does, so importing `{ Navbar }` pulls
7
+ // in the Navbar and what it uses — and a bundler drops every component you don't.
38
8
 
39
9
  export { createSearch } from "./search.js";
40
10
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opentf/afw-docs",
3
- "version": "0.34.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,18 +69,19 @@
69
69
  "bugs": "https://github.com/Open-Tech-Foundation/afw/issues",
70
70
  "license": "MIT",
71
71
  "peerDependencies": {
72
- "@opentf/afw": "0.36.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.23.0"
78
+ "@opentf/afw-compiler": "0.25.0",
79
+ "@opentf/syntax-highlighter": "0.5.0"
79
80
  },
80
81
  "devDependencies": {
81
- "@opentf/afw": "0.36.0",
82
- "@opentf/afw-test": "1.31.0",
83
- "@opentf/vite-plugin-afw": "0.4.0",
82
+ "@opentf/afw": "0.38.0",
83
+ "@opentf/afw-test": "1.33.0",
84
+ "@opentf/vite-plugin-afw": "0.6.0",
84
85
  "vite": "8.3.5"
85
86
  },
86
87
  "types": "./types/index.d.ts"
package/theme/index.css CHANGED
@@ -19,6 +19,11 @@
19
19
  * overrides the theme regardless of selector specificity — no `!important` or
20
20
  * doubled selectors needed. Imported after Tailwind, the layer still ranks above
21
21
  * Tailwind's own layers (preflight, utilities). */
22
+ /* Code-fence token colors: @opentf/syntax-highlighter's shared selectors (`.sh-*` →
23
+ * `--sh-*`), in the same layer. The `--sh-*` values below are its GitHub Light and
24
+ * GitHub Dark themes, switched with the site's `data-theme`. */
25
+ @import "@opentf/syntax-highlighter/themes/shared.css" layer(afw-docs);
26
+
22
27
  @layer afw-docs {
23
28
  :root {
24
29
  --afw-bg: #ffffff;
@@ -28,12 +33,67 @@
28
33
  --afw-text-muted: #64748b;
29
34
  --afw-border: #e2e8f0;
30
35
  --afw-accent: #ff851b;
36
+ /* The accent as text (links, active items): the brand orange is too light on
37
+ * white, so text takes a darker shade of it that meets WCAG AA (4.5:1) on the
38
+ * light backgrounds. Borders and fills keep --afw-accent. */
39
+ --afw-accent-text: #ad5100;
31
40
  --afw-accent-contrast: #ffffff;
32
41
  --afw-accent-soft: rgba(255, 133, 27, 0.12);
33
42
  --afw-code-bg: #f1f5f9;
34
- --afw-code-text: #be4f0c;
43
+ --afw-code-text: #b0480b;
35
44
  --afw-selection: rgba(255, 133, 27, 0.22);
36
45
 
46
+ /* Code blocks (fences, CodeBlock): chrome, then GitHub Light token colors. */
47
+ --afw-code-block-bg: #f6f8fa;
48
+ --afw-code-block-head-bg: #eaeef2;
49
+ --afw-code-block-head-border: rgba(31, 35, 40, 0.1);
50
+ --afw-code-block-text: #24292f;
51
+ --afw-code-block-muted: rgba(31, 35, 40, 0.55);
52
+ --afw-code-block-name: rgba(31, 35, 40, 0.85);
53
+ --afw-copy-border: rgba(31, 35, 40, 0.18);
54
+ --afw-copy-bg: rgba(255, 255, 255, 0.7);
55
+ --afw-copy-bg-hover: #ffffff;
56
+ --afw-copy-text: rgba(31, 35, 40, 0.75);
57
+ --afw-copy-text-hover: #1f2328;
58
+ --sh-comment: #6e7781;
59
+ --sh-keyword: #cf222e;
60
+ --sh-control: #af00db;
61
+ --sh-string: #0a3069;
62
+ --sh-number: #0550ae;
63
+ --sh-regex: #116329;
64
+ --sh-function: #8250df;
65
+ --sh-method: #9165e2;
66
+ --sh-class: #953800;
67
+ --sh-variable: #24292f;
68
+ --sh-identifier: #24292f;
69
+ --sh-constant: #0550ae;
70
+ --sh-property: #116329;
71
+ --sh-key: #953800;
72
+ --sh-parameter: #953800;
73
+ --sh-operator: #0550ae;
74
+ --sh-punctuation: #24292f;
75
+ --sh-decorator: #953800;
76
+ --sh-boolean: #0550ae;
77
+ --sh-null: #0550ae;
78
+ --sh-addition: #1a7f37;
79
+ --sh-deletion: #cf222e;
80
+ --sh-hunk: #0550ae;
81
+ --sh-header: #8250df;
82
+ --sh-text-bold: #cf222e;
83
+ --sh-text-italic: #cf222e;
84
+ --sh-text-underline: #cf222e;
85
+ --sh-text-strikethrough: #6e7781;
86
+ --sh-code-inline: #0a3069;
87
+ --sh-code-block: #0a3069;
88
+ --sh-markup-heading: #8250df;
89
+ --sh-markup-quote: #6e7781;
90
+ --sh-markup-list: #24292f;
91
+ --sh-markup-link: #0550ae;
92
+ --sh-markup-image: #0550ae;
93
+ --sh-syntax-delimiter: #24292f;
94
+ --sh-syntax-marker: #24292f;
95
+ --sh-syntax-escape: #0550ae;
96
+
37
97
  --afw-sidebar-width: 17rem;
38
98
  --afw-toc-width: 15rem;
39
99
  --afw-content-max: 48rem;
@@ -51,11 +111,63 @@
51
111
  --afw-text-muted: #94a3b8;
52
112
  --afw-border: #1e293b;
53
113
  --afw-accent: #ff943d;
114
+ --afw-accent-text: #ff943d;
54
115
  --afw-accent-contrast: #0b1220;
55
116
  --afw-accent-soft: rgba(255, 148, 61, 0.16);
56
117
  --afw-code-bg: #0f172a;
57
118
  --afw-code-text: #ffb784;
58
119
  --afw-selection: rgba(255, 148, 61, 0.3);
120
+
121
+ /* Code blocks: chrome, then GitHub Dark token colors. */
122
+ --afw-code-block-bg: #0d1117;
123
+ --afw-code-block-head-bg: #161b22;
124
+ --afw-code-block-head-border: rgba(255, 255, 255, 0.07);
125
+ --afw-code-block-text: #c9d1d9;
126
+ --afw-code-block-muted: rgba(255, 255, 255, 0.45);
127
+ --afw-code-block-name: rgba(255, 255, 255, 0.82);
128
+ --afw-copy-border: rgba(255, 255, 255, 0.16);
129
+ --afw-copy-bg: rgba(255, 255, 255, 0.06);
130
+ --afw-copy-bg-hover: rgba(255, 255, 255, 0.14);
131
+ --afw-copy-text: rgba(255, 255, 255, 0.78);
132
+ --afw-copy-text-hover: #ffffff;
133
+ --sh-comment: #8b949e;
134
+ --sh-keyword: #ff7b72;
135
+ --sh-control: #79c0ff;
136
+ --sh-string: #a5d6ff;
137
+ --sh-number: #79c0ff;
138
+ --sh-regex: #7ee787;
139
+ --sh-function: #d2a8ff;
140
+ --sh-method: #d7b2ff;
141
+ --sh-class: #ffa657;
142
+ --sh-variable: #c9d1d9;
143
+ --sh-identifier: #c9d1d9;
144
+ --sh-constant: #79c0ff;
145
+ --sh-property: #7ee787;
146
+ --sh-key: #79c0ff;
147
+ --sh-parameter: #ffa657;
148
+ --sh-operator: #ff7b72;
149
+ --sh-punctuation: #c9d1d9;
150
+ --sh-decorator: #ffa657;
151
+ --sh-boolean: #79c0ff;
152
+ --sh-null: #79c0ff;
153
+ --sh-addition: #3fb950;
154
+ --sh-deletion: #f85149;
155
+ --sh-hunk: #58a6ff;
156
+ --sh-header: #bc8cff;
157
+ --sh-text-bold: #ff7b72;
158
+ --sh-text-italic: #ff7b72;
159
+ --sh-text-underline: #ff7b72;
160
+ --sh-text-strikethrough: #8b949e;
161
+ --sh-code-inline: #a5d6ff;
162
+ --sh-code-block: #a5d6ff;
163
+ --sh-markup-heading: #ff7b72;
164
+ --sh-markup-quote: #8b949e;
165
+ --sh-markup-list: #c9d1d9;
166
+ --sh-markup-link: #79c0ff;
167
+ --sh-markup-image: #79c0ff;
168
+ --sh-syntax-delimiter: #c9d1d9;
169
+ --sh-syntax-marker: #c9d1d9;
170
+ --sh-syntax-escape: #79c0ff;
59
171
  }
60
172
 
61
173
  html {
@@ -410,7 +522,7 @@
410
522
  color: var(--afw-text);
411
523
  }
412
524
  .afwd-theme-item.is-active {
413
- color: var(--afw-accent);
525
+ color: var(--afw-accent-text);
414
526
  font-weight: 600;
415
527
  }
416
528
 
@@ -463,7 +575,7 @@
463
575
  font-size: 0.82rem;
464
576
  }
465
577
  .afwd-search-trigger:hover {
466
- color: var(--afw-accent);
578
+ color: var(--afw-accent-text);
467
579
  border-color: var(--afw-accent);
468
580
  }
469
581
  .afwd-search-kbd {
@@ -611,7 +723,7 @@
611
723
  }
612
724
  .afwd-search-result-section::before {
613
725
  content: "#";
614
- color: var(--afw-accent);
726
+ color: var(--afw-accent-text);
615
727
  font-weight: 700;
616
728
  }
617
729
  .afwd-search-result-excerpt {
@@ -623,7 +735,7 @@
623
735
  }
624
736
  .afwd-search-result-excerpt mark {
625
737
  background: var(--afw-accent-soft);
626
- color: var(--afw-accent);
738
+ color: var(--afw-accent-text);
627
739
  border-radius: 0.2rem;
628
740
  padding: 0 0.1rem;
629
741
  }
@@ -897,7 +1009,7 @@
897
1009
  opacity: 0.6;
898
1010
  }
899
1011
  .afwd-sidebar-link.afwd-active {
900
- color: var(--afw-accent);
1012
+ color: var(--afw-accent-text);
901
1013
  background: var(--afw-accent-soft);
902
1014
  font-weight: 600;
903
1015
  }
@@ -980,7 +1092,7 @@
980
1092
  opacity: 1;
981
1093
  }
982
1094
  .afw-heading-anchor:hover {
983
- color: var(--afw-accent);
1095
+ color: var(--afw-accent-text);
984
1096
  }
985
1097
  .afwd-prose p,
986
1098
  .afwd-prose ul,
@@ -1071,7 +1183,7 @@
1071
1183
  border-color: var(--afw-accent);
1072
1184
  }
1073
1185
  .afwd-prose a {
1074
- color: var(--afw-accent);
1186
+ color: var(--afw-accent-text);
1075
1187
  text-decoration: none;
1076
1188
  font-weight: 500;
1077
1189
  }
@@ -1099,7 +1211,7 @@
1099
1211
  font-size: 0.85rem;
1100
1212
  line-height: 1.6;
1101
1213
  }
1102
- /* Build-time highlighted code (syntect) sets its own inline background. */
1214
+ /* Code inside a block takes the block's colors, not inline-code styling. */
1103
1215
  .afwd-prose pre code {
1104
1216
  background: none;
1105
1217
  color: inherit;
@@ -1108,42 +1220,42 @@
1108
1220
  }
1109
1221
  /* Titled code block (built by the MDX front-end): a header bar — language label,
1110
1222
  * optional filename, and a copy button on the right — above the highlighted <pre>.
1111
- * The wrapper owns the radius and clips the corners of the dark header and code. */
1223
+ * The wrapper owns the radius and clips the corners of the header and code. */
1112
1224
  .afw-code {
1113
1225
  margin: 0 0 1.4rem;
1114
1226
  border: 1px solid var(--afw-border);
1115
1227
  border-radius: var(--afw-radius);
1116
1228
  overflow: hidden;
1117
- background: #2b303b;
1229
+ background: var(--afw-code-block-bg);
1118
1230
  }
1119
1231
  .afw-code-head {
1120
1232
  display: flex;
1121
1233
  align-items: center;
1122
1234
  gap: 0.55rem;
1123
1235
  padding: 0.4rem 0.5rem 0.4rem 0.95rem;
1124
- background: #23272f;
1125
- border-bottom: 1px solid rgba(255, 255, 255, 0.07);
1236
+ background: var(--afw-code-block-head-bg);
1237
+ border-bottom: 1px solid var(--afw-code-block-head-border);
1126
1238
  }
1127
1239
  .afw-code-lang {
1128
1240
  text-transform: uppercase;
1129
1241
  letter-spacing: 0.05em;
1130
1242
  font-size: 0.66rem;
1131
1243
  font-weight: 700;
1132
- color: rgba(255, 255, 255, 0.45);
1244
+ color: var(--afw-code-block-muted);
1133
1245
  }
1134
1246
  .afw-code-name {
1135
1247
  font-family: var(--afw-mono);
1136
1248
  font-size: 0.78rem;
1137
- color: rgba(255, 255, 255, 0.82);
1249
+ color: var(--afw-code-block-name);
1138
1250
  }
1139
1251
  .afw-code pre {
1140
1252
  margin: 0;
1141
1253
  border: none;
1142
1254
  border-radius: 0;
1143
- /* Readable default for blocks without build-time highlighting (e.g. string content
1144
- * rendered by Tabs via CodeBlock). Fenced blocks carry inline syntect
1145
- * colors, which override this. */
1146
- color: #e2e8f0;
1255
+ background: var(--afw-code-block-bg);
1256
+ /* Plain text (unknown languages, CodeBlock strings); highlighted tokens carry
1257
+ * their own `.sh-*` colors. */
1258
+ color: var(--afw-code-block-text);
1147
1259
  }
1148
1260
  .afw-copy {
1149
1261
  margin-left: auto;
@@ -1151,10 +1263,10 @@
1151
1263
  align-items: center;
1152
1264
  gap: 0.35rem;
1153
1265
  padding: 0.28rem 0.6rem;
1154
- border: 1px solid rgba(255, 255, 255, 0.16);
1266
+ border: 1px solid var(--afw-copy-border);
1155
1267
  border-radius: 999px;
1156
- background: rgba(255, 255, 255, 0.06);
1157
- color: rgba(255, 255, 255, 0.78);
1268
+ background: var(--afw-copy-bg);
1269
+ color: var(--afw-copy-text);
1158
1270
  font-family: var(--afw-font);
1159
1271
  font-size: 0.72rem;
1160
1272
  font-weight: 600;
@@ -1163,8 +1275,8 @@
1163
1275
  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
1164
1276
  }
1165
1277
  .afw-copy:hover {
1166
- background: rgba(255, 255, 255, 0.14);
1167
- color: #fff;
1278
+ background: var(--afw-copy-bg-hover);
1279
+ color: var(--afw-copy-text-hover);
1168
1280
  }
1169
1281
  .afw-copy.is-copied {
1170
1282
  background: color-mix(in srgb, #10b981 22%, transparent);
@@ -1265,7 +1377,7 @@
1265
1377
  color: var(--afw-text);
1266
1378
  }
1267
1379
  .afwd-toc-link.afwd-active {
1268
- color: var(--afw-accent);
1380
+ color: var(--afw-accent-text);
1269
1381
  border-left-color: var(--afw-accent);
1270
1382
  font-weight: 600;
1271
1383
  }
@@ -1293,7 +1405,7 @@
1293
1405
  text-decoration: none;
1294
1406
  }
1295
1407
  .afwd-crumb-link:hover {
1296
- color: var(--afw-accent);
1408
+ color: var(--afw-accent-text);
1297
1409
  }
1298
1410
 
1299
1411
  /* ── Page meta (last updated · edit link) ──────────────────────────────────── */
@@ -1328,7 +1440,7 @@
1328
1440
  text-decoration: none;
1329
1441
  }
1330
1442
  .afwd-edit-page:hover {
1331
- color: var(--afw-accent);
1443
+ color: var(--afw-accent-text);
1332
1444
  }
1333
1445
  .afwd-page-meta + .afwd-pagination {
1334
1446
  margin-top: 1.5rem;
@@ -1489,7 +1601,7 @@
1489
1601
  }
1490
1602
  .afwd-tab.afwd-active {
1491
1603
  background: var(--afw-bg);
1492
- color: var(--afw-accent);
1604
+ color: var(--afw-accent-text);
1493
1605
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08);
1494
1606
  }
1495
1607
  .afwd-tabs-panels {
@@ -1547,7 +1659,7 @@
1547
1659
  .afwd-steps > h3:hover::before,
1548
1660
  .afwd-steps > h4:hover::before {
1549
1661
  border-color: var(--afw-accent);
1550
- color: var(--afw-accent);
1662
+ color: var(--afw-accent-text);
1551
1663
  }
1552
1664
 
1553
1665
  /* ── Table wrapper ─────────────────────────────────────────────────────────── */
@@ -1666,7 +1778,7 @@
1666
1778
  }
1667
1779
  .afwd-feed-link:hover,
1668
1780
  .afwd-feed-link:focus-visible {
1669
- color: var(--afw-accent);
1781
+ color: var(--afw-accent-text);
1670
1782
  border-color: var(--afw-accent);
1671
1783
  }
1672
1784
  .afwd-feed-icon {
@@ -1680,7 +1792,7 @@
1680
1792
  color: var(--afw-text-muted);
1681
1793
  }
1682
1794
  .afwd-feed-inline a {
1683
- color: var(--afw-accent);
1795
+ color: var(--afw-accent-text);
1684
1796
  }
1685
1797
 
1686
1798
  .afwd-blog-back {
@@ -1779,7 +1891,7 @@
1779
1891
  transition: opacity 0.15s;
1780
1892
  }
1781
1893
  .afwd-post-card:hover .afwd-post-card-title {
1782
- color: var(--afw-accent);
1894
+ color: var(--afw-accent-text);
1783
1895
  }
1784
1896
  .afwd-post-card .afwd-post-meta {
1785
1897
  margin-top: 0.75rem;