From ee133f6050a7dbfaa0577162d5873b237d78609e Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sat, 30 May 2026 15:11:33 +0200
Subject: [PATCH 1/3] Fix mislabeled C/SAL block in API-Declarations.

---
 docs/Features/Advanced/API-Declarations.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/Features/Advanced/API-Declarations.md b/docs/Features/Advanced/API-Declarations.md
index 9d6d43a9..f25ee339 100644
--- a/docs/Features/Advanced/API-Declarations.md
+++ b/docs/Features/Advanced/API-Declarations.md
@@ -101,11 +101,11 @@ With `cdecl` calling convention fully supported, twinBASIC can also handle varia
 
 Using the [given C/C++ prototype](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-wsprintfw):
 
-```cpp
+```c
 int WINAPIV wsprintfW(
-  [out] LPWSTR  unnamedParam1,
-  [in]  LPCWSTR unnamedParam2,
-        ...
+  /* [out] */ LPWSTR  unnamedParam1,
+  /* [in]  */ LPCWSTR unnamedParam2,
+              /* ... */
 );
 ```
 

From e18bd6da922e6d85e6b071b938c8de79c1f0e4c8 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sat, 30 May 2026 15:12:04 +0200
Subject: [PATCH 2/3] Curate Shiki grammar set, warn on unknown fence labels.

---
 builder/highlight.mjs | 46 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 5 deletions(-)

diff --git a/builder/highlight.mjs b/builder/highlight.mjs
index 4ef16347..0e47ca01 100644
--- a/builder/highlight.mjs
+++ b/builder/highlight.mjs
@@ -21,8 +21,27 @@ import { loadHighlightTheme } from "./highlight-theme.mjs";
 
 // Fenced-info aliases that select the bundled tB grammar.
 const TB_ALIASES = new Set(["tb", "twinbasic", "vb", "vba"]);
-const SHIKI_BUNDLED_LANGS = [
-  "js", "json", "ruby", "html", "yaml", "xml", "sql", "sh", "cpp", "c", "liquid",
+
+// Fence labels that explicitly disclaim highlighting -- never warn for these.
+// Empty info string lands as wrapperLang `plaintext` (see renderCodeBlock).
+const SILENT_LANGS = new Set(["plaintext", "text", "txt", ""]);
+
+// Shiki grammars to load alongside the tB grammar. Restricted to labels
+// actually used in docs/ -- the highlighter warns at build time for any
+// unknown label, so adding a new fence language is a deliberate step:
+// extend this list, run the build, verify no warning. Aliases are
+// recognized automatically (shiki registers both canonical and alias
+// names, so loading `js` accepts `javascript` too, `yaml` accepts `yml`,
+// `batch` accepts `bat`). Counts from the last survey are noted.
+const SHIKI_LANGS = [
+  "js",     // 56 blocks (CEF/WebView2 interop tutorials)
+  "yaml",   // 13 blocks (config snippets)
+  "json",   //  7 blocks
+  "c",      //  3 blocks (Win32 API examples, comment style demos)
+  "html",   //  2 blocks (transitively loads css + javascript)
+  "xml",    //  1 block
+  "sql",    //  1 block
+  "batch",  //  1 block (Windows .bat examples)
 ];
 
 // Phase 11 (B5) server-side copy-button: emitted inside the wrapper
@@ -50,21 +69,32 @@ export async function initHighlighter({ copyButton = true } = {}) {
     const tbGrammar = JSON.parse(grammarText);
     shiki = await createHighlighter({
       themes: [],
-      langs: [tbGrammar, ...SHIKI_BUNDLED_LANGS],
+      langs: [tbGrammar, ...SHIKI_LANGS],
     });
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
 
+  // Dedup unknown-language warnings per init. SILENT_LANGS suppresses
+  // explicit plaintext intent (text, txt, plaintext) and empty fences.
+  const warned = new Set();
+  const warn = (lang) => {
+    if (warned.has(lang)) return;
+    warned.add(lang);
+    console.warn(
+      `highlight: unknown fence language "${lang}" -- falling back to plain text. ` +
+      `Add it to highlight.mjs's SHIKI_LANGS to enable highlighting.`);
+  };
+
   const copyButtonHtml = copyButton ? COPY_BUTTON_HTML : "";
   cached = {
-    render: (code, lang) => renderCodeBlock(shiki, theme, copyButtonHtml, code, lang),
+    render: (code, lang) => renderCodeBlock(shiki, theme, copyButtonHtml, code, lang, warn),
     themeCss: theme.css,
   };
   return cached;
 }
 
-function renderCodeBlock(shiki, theme, copyButtonHtml, code, lang) {
+function renderCodeBlock(shiki, theme, copyButtonHtml, code, lang, warn) {
   const lower = (lang || "").toLowerCase();
   const isTb = TB_ALIASES.has(lower);
   // The wrapper class is `language-<as-typed>`; keep `vb` / `vba` /
@@ -82,6 +112,12 @@ function renderCodeBlock(shiki, theme, copyButtonHtml, code, lang) {
     }
   }
 
+  // Warn for non-silent fence labels that don't resolve to a loaded
+  // grammar. SILENT_LANGS covers explicit plaintext intent.
+  if (!shikiLang && !SILENT_LANGS.has(lower) && warn) {
+    warn(lower);
+  }
+
   // The trailing \n inside <code> matches the rouge / kramdown shape:
   // GFM strips the user's trailing newline; one is re-added here.
   const codeBody = code.endsWith("\n") ? code : code + "\n";

From 3106c3af4cc574ad7b0cbc746530401868613925 Mon Sep 17 00:00:00 2001
From: Kuba Sunderland-Ober <kuba@mareimbrium.org>
Date: Sat, 30 May 2026 15:24:08 +0200
Subject: [PATCH 3/3] Drop the enable_copy_code_button config option. The
 button is always enabled.

---
 builder/highlight.mjs                 | 9 ++++-----
 builder/tbdocs.mjs                    | 4 +---
 builder/template.mjs                  | 7 +++----
 docs/Documentation/Pipeline-Stages.md | 4 ++--
 docs/Documentation/Tools.md           | 2 +-
 docs/_config.yml                      | 3 ---
 6 files changed, 11 insertions(+), 18 deletions(-)

diff --git a/builder/highlight.mjs b/builder/highlight.mjs
index 0e47ca01..688014f8 100644
--- a/builder/highlight.mjs
+++ b/builder/highlight.mjs
@@ -57,7 +57,7 @@ const COPY_BUTTON_HTML =
 
 let cached = null;
 
-export async function initHighlighter({ copyButton = true } = {}) {
+export async function initHighlighter() {
   if (cached) return cached;
 
   const theme = await loadHighlightTheme();
@@ -86,15 +86,14 @@ export async function initHighlighter({ copyButton = true } = {}) {
       `Add it to highlight.mjs's SHIKI_LANGS to enable highlighting.`);
   };
 
-  const copyButtonHtml = copyButton ? COPY_BUTTON_HTML : "";
   cached = {
-    render: (code, lang) => renderCodeBlock(shiki, theme, copyButtonHtml, code, lang, warn),
+    render: (code, lang) => renderCodeBlock(shiki, theme, code, lang, warn),
     themeCss: theme.css,
   };
   return cached;
 }
 
-function renderCodeBlock(shiki, theme, copyButtonHtml, code, lang, warn) {
+function renderCodeBlock(shiki, theme, code, lang, warn) {
   const lower = (lang || "").toLowerCase();
   const isTb = TB_ALIASES.has(lower);
   // The wrapper class is `language-<as-typed>`; keep `vb` / `vba` /
@@ -133,7 +132,7 @@ function renderCodeBlock(shiki, theme, copyButtonHtml, code, lang, warn) {
     tokenizedHtml = escapeHtml(codeBody);
   }
 
-  return `<div class="language-${wrapperLang} highlighter-rouge">${copyButtonHtml}<div class="highlight"><pre class="highlight"><code>${tokenizedHtml}</code></pre></div></div>`;
+  return `<div class="language-${wrapperLang} highlighter-rouge">${COPY_BUTTON_HTML}<div class="highlight"><pre class="highlight"><code>${tokenizedHtml}</code></pre></div></div>`;
 }
 
 // Shiki's `codeToTokensBase` with `includeExplanation` returns
diff --git a/builder/tbdocs.mjs b/builder/tbdocs.mjs
index 5dc3a14e..dbe45699 100644
--- a/builder/tbdocs.mjs
+++ b/builder/tbdocs.mjs
@@ -153,9 +153,7 @@ export async function runBuild(opts) {
   // Build the shared markdown-it instance up front so Phase 2's SEO
   // pass and Phase 3's body renderer use the same configured renderer.
   // initHighlighter overlaps with the running git shell-outs above.
-  const highlighter = await initHighlighter({
-    copyButton: config.enable_copy_code_button !== false,
-  });
+  const highlighter = await initHighlighter();
   const linkTables = buildLinkTables(pages);
   const baseurl = String(config.baseurl || "");
   const staticFileSet = new Set(staticFiles.map((s) => s.srcRel));
diff --git a/builder/template.mjs b/builder/template.mjs
index c1bfa2ec..76491a77 100644
--- a/builder/template.mjs
+++ b/builder/template.mjs
@@ -270,11 +270,10 @@ const SVG_SYMBOLS_COPY = `<!-- Bootstrap Icons. MIT License: https://github.com/
   </svg>
 </symbol>`;
 
-// Port of theme's _includes/icons/icons.html. Search and copy-code-button
-// icons are conditional.
+// Port of theme's _includes/icons/icons.html. The search icon is
+// conditional; the copy-code icons ship unconditionally.
 function buildSvgSprites(config) {
   const searchEnabled = config.search_enabled !== false;
-  const copyEnabled = config.enable_copy_code_button !== false;
   const parts = [
     `  <svg xmlns="http://www.w3.org/2000/svg" class="d-none">`,
     SVG_SYMBOL_LINK,
@@ -282,7 +281,7 @@ function buildSvgSprites(config) {
     SVG_SYMBOL_EXPAND,
   ];
   if (searchEnabled) parts.push(SVG_SYMBOL_DOC);
-  if (copyEnabled) parts.push(SVG_SYMBOLS_COPY);
+  parts.push(SVG_SYMBOLS_COPY);
   parts.push(`</svg>`);
   return parts.join("\n");
 }
diff --git a/docs/Documentation/Pipeline-Stages.md b/docs/Documentation/Pipeline-Stages.md
index ac5c07d1..b15b80dd 100644
--- a/docs/Documentation/Pipeline-Stages.md
+++ b/docs/Documentation/Pipeline-Stages.md
@@ -268,7 +268,7 @@ Returns `{ book: <parsed YAML> }`, or `{}` when the file is absent. The orchestr
 Before Phase 2 completes, the orchestrator builds the shared markdown-it instance that both Phase 2's SEO pass and Phase 3's render pass reuse. Three functions from `render.mjs` are called in sequence:
 
 ```js
-const highlighter = await initHighlighter({ copyButton: boolean });
+const highlighter = await initHighlighter();
 const linkTables  = buildLinkTables(pages);
 const markdown    = createMarkdownIt({ highlighter, linkTables, baseurl, staticFiles });
 ```
@@ -298,7 +298,7 @@ Renders each page's `rawContent` to `page.renderedContent` using the shared `sit
 |---|---|---|
 | `renderPhase` | `(pages, site, staticFiles?) → Promise<void>` | Main entry point. |
 | `createMarkdownIt` | `({ highlighter, linkTables, baseurl, staticFiles }) → MarkdownIt` | Configures and returns a markdown-it instance with all plugins and render-rule overrides applied. See [Extending the Builder](Extending) for how to add a plugin here. |
-| `initHighlighter` | `({ copyButton?: boolean }) → Promise<{ render, themeCss }>` | Initialises Shiki with the bundled twinBASIC grammar (delegates to `highlight.mjs` internally). `render(code, lang)` returns highlighted HTML; `themeCss` is the generated `tb-highlight.css` string or `null` when no theme was loaded. |
+| `initHighlighter` | `() → Promise<{ render, themeCss }>` | Initialises Shiki with the bundled twinBASIC grammar (delegates to `highlight.mjs` internally). `render(code, lang)` returns highlighted HTML; `themeCss` is the generated `tb-highlight.css` string or `null` when no theme was loaded. |
 | `buildLinkTables` | `(pages: Page[]) → { byPath, byUrl, byRedirect }` | Builds lookup tables keyed by `srcRel`, `permalink`, and `redirect_from` entries. Used by the relative-links plugin to resolve in-source `[X](Y.md)` links to absolute URLs at render time. |
 | `kramdownSlug` | `(text: string) → string` | Converts heading text to a kramdown-compatible anchor slug: lowercase, strip non-word characters, deduplicate with `-1`, `-2`, and so on. |
 | `rewriteAdmonitions` | `(src: string) → string` | Pre-render text pass: converts GFM `> [!NOTE]` / `[!IMPORTANT]` / `[!WARNING]` / `[!TIP]` / `[!CAUTION]` blocks to the `markdown-alert markdown-alert-<type>` class structure. |
diff --git a/docs/Documentation/Tools.md b/docs/Documentation/Tools.md
index 188e9c73..800e5a5d 100644
--- a/docs/Documentation/Tools.md
+++ b/docs/Documentation/Tools.md
@@ -128,7 +128,7 @@ The build pipeline also reads a handful of declarative files. They are not execu
 
 | File | Effect |
 |---|---|
-| `docs/_config.yml` | Site config. `tbdocs` reads `url`, `baseurl`, `title`, `logo`, `also_build_offline`, `also_build_pdf`, `offline_exclude`, `exclude`, `enable_copy_code_button`, the footer / aux-link knobs, the GitHub edit-link knobs, and the offline-download-link knobs. Jekyll-only keys (`markdown`, `kramdown`, `theme`, `highlighter`, the `defaults` block, the `compress_html` block) are ignored. |
+| `docs/_config.yml` | Site config. `tbdocs` reads `url`, `baseurl`, `title`, `logo`, `also_build_offline`, `also_build_pdf`, `offline_exclude`, `exclude`, the footer / aux-link knobs, the GitHub edit-link knobs, and the offline-download-link knobs. Jekyll-only keys (`markdown`, `kramdown`, `theme`, `highlighter`, the `defaults` block, the `compress_html` block) are ignored. |
 | `docs/_book.yml` | The PDF book's chapter manifest. Entries are resolved to pages via the selector schema (`page` / `pages` / `nav_page` / `nav_pages` / `no_descent`) and control PDF outline behaviour via `landing_page:`, `landing_is_target:`, `no_outline_entry:`, `no_heading_shift:`, and `outline_closed:`. Full schema is documented in the file header. Phase 2 resolves chapter arrays; Phase 8 assembles `book.html`. |
 | `builder/themes/Light.theme`, `Dark.theme`, `Classic.theme` | twinBASIC IDE theme files, vendored from the BETA installer. `builder/highlight-theme.mjs` parses them into a Symbol-keyed palette that drives both the renderer's scope-to-class mapping and the generated `tb-highlight.css`. Refresh from the installer when the IDE adds new palette entries. |
 | `builder/twinbasic.tmLanguage.json` | TextMate grammar for the twinBASIC language. Shiki uses it to tokenise every ` ```tb ` code block. |
diff --git a/docs/_config.yml b/docs/_config.yml
index ff8a4c9c..3ec652de 100644
--- a/docs/_config.yml
+++ b/docs/_config.yml
@@ -3,9 +3,6 @@ logo: favicon.png
 logo_with_title: true
 url: "https://docs.twinbasic.com"
 
-# For copy button on code
-enable_copy_code_button: true
-
 # Aux links for the upper right navigation
 aux_links:
   "twinBASIC Home":