Render the code block shell at build time

The frame, header, label and language were being built by JavaScript after the
page loaded. With scripting off, and in the window before hydration, a code
block was bare text on the page background: the border, radius and padding used
to sit on <pre> and now sit on the wrapper that script created.

A Shiki transformer emits the whole shell instead, including the copy button.
The copy handler is delegated at the document level, so it finds a statically
rendered button by the same selector.

Shiki, and not rehype, because plugins registered through `markdown.processor`
never reach .mdx pages. rehypeWbr adds 18 <wbr> elements to the kubernetes-agent
permissions page and none to kustomize.mdx, which has eight matches for it.

code-blocks.js drops from 431 lines to 327: the wrapping, the copy button
markup and the language table all go. It keeps copying, collapsing, and folding
a <details data-group> set into one block with a language menu, which merges
sibling blocks and so cannot be done per-block at build time.

Two tests cover the shell with scripting disabled.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: enf0rc3

astro.config.mjs

@@ -7,6 +7,7 @@ import { attributeMarkdown, wrapTables } from '/src/themes/octopus/utilities/cus
 import llmMdEmitter from './src/integrations/llm-md-emitter.ts';
 import pruneDist from './src/integrations/prune-dist.ts';
 import rehypeWbr from './src/plugins/rehype-wbr.js';
+import shikiCodeBlock from './src/plugins/shiki-code-block.js';
 
 // https://astro.build/config
 export default defineConfig({
@@ -36,16 +37,9 @@ export default defineConfig({
             langAlias: {
                 ocl: 'hcl'
             },
-            transformers: [
-                {
-                    // Shiki drops the fence's meta string, which the code block
-                    // header renders as the block's label
-                    pre(node) {
-                        const label = this.options.meta?.__raw?.trim();
-                        if (label) node.properties['data-label'] = label;
-                    }
-                }
-            ]
+            // A transformer, because rehype plugins registered through
+            // `processor` below never reach .mdx pages
+            transformers: [shikiCodeBlock()]
         },
         processor: unified({
             remarkPlugins: [

src/plugins/shiki-code-block.js

@@ -0,0 +1,118 @@
+// Wraps every highlighted block in the code block shell at build time, so the
+// frame, header, label and language are on the page before any script runs.
+// code-blocks.js adds the behaviour: copying, collapsing, and folding a
+// <details data-group> set into one block with a language menu.
+
+const REST = 'Copy to clipboard';
+
+/** Display names for the fence languages used across the docs. */
+const LANGUAGE_NAMES = {
+  bash: 'Bash',
+  batch: 'Batch',
+  'c#': 'C#',
+  cs: 'C#',
+  csharp: 'C#',
+  docker: 'Docker',
+  dockerfile: 'Dockerfile',
+  fsharp: 'F#',
+  go: 'Go',
+  hcl: 'HCL',
+  html: 'HTML',
+  ini: 'INI',
+  java: 'Java',
+  javascript: 'JavaScript',
+  js: 'JavaScript',
+  json: 'JSON',
+  log: 'Log',
+  markdown: 'Markdown',
+  nginx: 'nginx',
+  ocl: 'OCL',
+  plaintext: 'Text',
+  powershell: 'PowerShell',
+  ps: 'PowerShell',
+  python: 'Python',
+  ruby: 'Ruby',
+  sh: 'Shell',
+  shell: 'Shell',
+  sql: 'SQL',
+  text: 'Text',
+  txt: 'Text',
+  typescript: 'TypeScript',
+  xml: 'XML',
+  yaml: 'YAML',
+  yml: 'YAML',
+};
+
+function displayName(language) {
+  const key = String(language ?? '')
+    .trim()
+    .toLowerCase();
+  if (!key) return '';
+  return LANGUAGE_NAMES[key] ?? key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+function h(tagName, properties, children = []) {
+  return { type: 'element', tagName, properties, children };
+}
+
+function text(value) {
+  return { type: 'text', value };
+}
+
+export default function shikiCodeBlock() {
+  return {
+    name: 'octopus:code-block',
+
+    root(node) {
+      const pre = node.children.find(
+        (child) => child.type === 'element' && child.tagName === 'pre'
+      );
+      if (!pre) return;
+
+      // langAlias rewrites what Shiki reports, so the attribute Astro set from
+      // the fence wins when it is there. ```ocl has to stay OCL, not HCL.
+      const language = displayName(
+        pre.properties?.['data-language'] ?? this.options.lang
+      );
+      const label = this.options.meta?.__raw?.trim() ?? '';
+
+      // Focusable so an overflowing panel can be scrolled from the keyboard.
+      pre.properties = { ...pre.properties, tabindex: '0' };
+
+      const header = h('div', { className: ['code-block__header'] }, [
+        h(
+          'p',
+          { className: ['code-block__label'], hidden: !label },
+          label ? [text(label)] : []
+        ),
+        h('div', { className: ['code-block__actions'] }, [
+          h('span', { className: ['code-block__language'] }, [text(language)]),
+          h(
+            'button',
+            {
+              type: 'button',
+              className: ['code-block__copy', 'btn', 'btn--small'],
+              'data-tooltip': REST,
+              'aria-label': 'Copy code to clipboard',
+            },
+            // Empty: the glyph is a CSS mask on the span itself.
+            [
+              h(
+                'span',
+                { className: ['code-block__copy-icon', 'btn__icon'] },
+                []
+              ),
+            ]
+          ),
+        ]),
+      ]);
+
+      const body = h('div', { className: ['code-block__body'] }, [
+        h('div', { className: ['code-block__panel'] }, [pre]),
+        h('div', { className: ['code-block__fade'] }, []),
+      ]);
+
+      node.children = [h('div', { className: ['code-block'] }, [header, body])];
+    },
+  };
+}