@hutusi/amytis 1.15.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hutusi/amytis",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "A high-performance digital garden and blog engine with Next.js 16 and Tailwind CSS v4",
   "repository": {
     "type": "git",
@@ -34,6 +34,7 @@
     "import-obsidian": "bun scripts/import-obsidian.ts",
     "import-book": "bun scripts/import-book.ts",
     "sync-book": "bun scripts/sync-book-chapters.ts",
+    "sync-vuepress-book": "bun scripts/sync-vuepress-book.ts",
     "series-draft": "bun scripts/series-draft.ts",
     "add-series-redirects": "bun scripts/add-series-redirects.ts",
     "deploy": "bun scripts/deploy.ts",
@@ -47,54 +48,75 @@
   },
   "dependencies": {
     "@giscus/react": "^3.1.0",
+    "@shikijs/transformers": "^4.1.0",
     "@tailwindcss/typography": "^0.5.19",
     "d3": "^7.9.0",
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
+    "hast-util-to-html": "^9.0.5",
     "image-size": "^2.0.2",
-    "katex": "^0.16.45",
-    "mermaid": "^11.14.0",
-    "next": "16.2.3",
+    "katex": "^0.16.47",
+    "mermaid": "^11.15.0",
+    "next": "16.2.6",
     "next-image-export-optimizer": "^1.20.1",
     "next-themes": "^0.4.6",
-    "react": "19.2.5",
-    "react-dom": "19.2.5",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
     "react-icons": "^5.6.0",
     "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^16.1.1",
     "rehype-katex": "^7.0.1",
+    "rehype-parse": "^9.0.1",
     "rehype-raw": "^7.0.0",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
+    "remark-directive": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
-    "sanitize-html": "^2.17.2",
+    "sanitize-html": "^2.17.4",
+    "shiki": "^4.1.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.1",
-    "@tailwindcss/postcss": "^4.2.2",
-    "@types/bun": "^1.3.12",
+    "@iconify-json/logos": "^1.2.11",
+    "@iconify-json/vscode-icons": "^1.2.52",
+    "@next/eslint-plugin-next": "^16.2.6",
+    "@playwright/test": "^1.60.0",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/bun": "^1.3.14",
     "@types/d3": "^7.4.3",
     "@types/hast": "^3.0.4",
     "@types/image-size": "^0.8.0",
     "@types/mdast": "^4.0.4",
-    "@types/node": "^24.12.2",
+    "@types/node": "^25.8.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@types/react-syntax-highlighter": "^15.5.13",
     "@types/sanitize-html": "^2.16.1",
+    "acorn": "^8.16.0",
     "babel-plugin-react-compiler": "1.0.0",
-    "eslint": "^9.39.4",
-    "eslint-config-next": "16.2.3",
-    "pagefind": "^1.5.0",
-    "pdf-to-img": "^5.0.0",
-    "tailwindcss": "^4.2.2",
-    "typescript": "^5.9.3"
+    "eslint": "^10.4.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "pagefind": "^1.5.2",
+    "pdf-to-img": "^6.1.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
+  },
+  "overrides": {
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "@typescript-eslint/project-service": "^8.59.3",
+    "@typescript-eslint/scope-manager": "^8.59.3",
+    "@typescript-eslint/tsconfig-utils": "^8.59.3",
+    "@typescript-eslint/type-utils": "^8.59.3",
+    "@typescript-eslint/types": "^8.59.3",
+    "@typescript-eslint/typescript-estree": "^8.59.3",
+    "@typescript-eslint/utils": "^8.59.3",
+    "@typescript-eslint/visitor-keys": "^8.59.3",
+    "typescript-eslint": "^8.59.3"
   },
   "ignoreScripts": [
     "sharp",

package/scripts/generate-code-group-icons.ts

@@ -0,0 +1,79 @@
+/**
+ * One-shot generator: builds CSS rules for the code-group tab icons by reading
+ * Iconify's logos / vscode-icons packs and embedding each icon as a data URI.
+ *
+ * Usage:
+ *   bun scripts/generate-code-group-icons.ts > /tmp/icons.css
+ * Then replace the block between the BEGIN/END markers in src/app/globals.css.
+ *
+ * Each icon key here corresponds to a value returned by resolveCodeGroupIcon
+ * in src/lib/code-group-icons.ts. Add to both files to support a new key.
+ */
+import { icons as logos } from '@iconify-json/logos';
+import { icons as vscodeIcons } from '@iconify-json/vscode-icons';
+
+type IconSrc = typeof logos | typeof vscodeIcons;
+
+const MAP: Record<string, { src: IconSrc; name: string }> = {
+  npm: { src: logos, name: 'npm-icon' },
+  yarn: { src: logos, name: 'yarn' },
+  pnpm: { src: logos, name: 'pnpm' },
+  bun: { src: logos, name: 'bun' },
+  deno: { src: logos, name: 'deno' },
+  typescript: { src: logos, name: 'typescript-icon' },
+  javascript: { src: logos, name: 'javascript' },
+  python: { src: logos, name: 'python' },
+  rust: { src: logos, name: 'rust' },
+  go: { src: logos, name: 'go' },
+  java: { src: logos, name: 'java' },
+  ruby: { src: logos, name: 'ruby' },
+  php: { src: logos, name: 'php' },
+  c: { src: logos, name: 'c' },
+  cpp: { src: logos, name: 'c-plusplus' },
+  html: { src: logos, name: 'html-5' },
+  css: { src: logos, name: 'css-3' },
+  json: { src: vscodeIcons, name: 'file-type-json' },
+  yaml: { src: vscodeIcons, name: 'file-type-yaml' },
+  markdown: { src: vscodeIcons, name: 'file-type-markdown' },
+  bash: { src: logos, name: 'bash-icon' },
+  docker: { src: logos, name: 'docker-icon' },
+  vite: { src: logos, name: 'vitejs' },
+  react: { src: logos, name: 'react' },
+  vue: { src: logos, name: 'vue' },
+  nextjs: { src: logos, name: 'nextjs-icon' },
+  node: { src: logos, name: 'nodejs-icon' },
+  tailwind: { src: logos, name: 'tailwindcss-icon' },
+};
+
+function buildSvg(src: IconSrc, name: string): string | null {
+  const icon = src.icons[name];
+  if (!icon) return null;
+  const w = icon.width ?? src.width ?? 24;
+  const h = icon.height ?? src.height ?? 24;
+  // Iconify "body" is the inner content of the <svg> tag; wrap to get a full SVG.
+  return `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 ${w} ${h}'>${icon.body}</svg>`;
+}
+
+function encodeDataUri(svg: string): string {
+  // CSS data URIs only require `#` and `"` to be encoded; iconify bodies use
+  // double-quoted attributes, so swap to single quotes (valid SVG).
+  return svg.replace(/"/g, "'").replace(/#/g, '%23').replace(/\n/g, '').replace(/\s+/g, ' ');
+}
+
+const lines: string[] = [
+  '/* === BEGIN: generated by scripts/generate-code-group-icons.ts — do not hand-edit === */',
+];
+for (const [key, { src, name }] of Object.entries(MAP)) {
+  const svg = buildSvg(src, name);
+  if (!svg) {
+    console.error(`Missing icon: ${name}`);
+    continue;
+  }
+  const dataUri = encodeDataUri(svg);
+  lines.push(`.cg-tab[data-cg-icon="${key}"]::before {`);
+  lines.push(`  content: '';`);
+  lines.push(`  background-image: url("data:image/svg+xml,${dataUri}");`);
+  lines.push(`}`);
+}
+lines.push('/* === END: generated icons === */');
+console.log(lines.join('\n'));

package/scripts/render-rst.py

@@ -563,6 +563,140 @@ def strip_preamble_nodes(document: Any) -> Any:
     return stripped
 
 
+def _language_from_classes(classes: list[str] | None) -> str:
+    """Recover the source language from a literal_block's class list when the
+    explicit `language` attribute is absent. Docutils stores ``.. code-block:: foo``
+    as classes=['code', 'foo']; the first class that isn't a docutils-internal
+    marker is the language name.
+    """
+    if not classes:
+        return ""
+    for cls in classes:
+        if cls not in ("code", "literal-block", "linenos"):
+            return cls
+    return ""
+
+
+def _build_amytis_code_marker(
+    text: str,
+    language: str,
+    highlight_lines: list[int] | None,
+    linenos: bool,
+    title: str | None,
+) -> str:
+    """Build the opaque <pre data-amytis-code> marker that the JS-side
+    Shiki post-processor in src/lib/shiki-rst.ts replaces with highlighted HTML.
+    """
+    attrs = ['data-amytis-code=""']
+    if language:
+        attrs.append(f'data-language="{html.escape(language, quote=True)}"')
+    if highlight_lines:
+        attrs.append(
+            f'data-highlight-lines="{",".join(str(n) for n in highlight_lines)}"'
+        )
+    if linenos:
+        attrs.append('data-line-numbers="true"')
+    if title:
+        attrs.append(f'data-title="{html.escape(title, quote=True)}"')
+
+    escaped = html.escape(text, quote=False)
+    return f'<pre {" ".join(attrs)}><code>{escaped}</code></pre>'
+
+
+def _build_inner_block_marker(block: Any) -> tuple[str, str]:
+    """Helper: build the per-block <pre data-amytis-code> marker AND return the
+    tab label (from the new `:label:` option, or the language as fallback).
+    Used by both the standalone-literal_block path and the code-group path.
+    """
+    classes = list(block.get("classes") or [])
+    language = block.get("language") or _language_from_classes(classes)
+    highlight_args = block.get("highlight_args") or {}
+    hl_lines = list(highlight_args.get("hl_lines") or [])
+    linenos = "linenos" in classes
+    caption_text = block.get("amytis_caption")  # set by the directive when :caption: is present
+    label = block.get("amytis_label") or language or ""
+
+    marker = _build_amytis_code_marker(
+        text=block.astext(),
+        language=language,
+        highlight_lines=hl_lines,
+        linenos=linenos,
+        title=caption_text,
+    )
+    return marker, label
+
+
+def transform_literal_blocks_to_markers(document: Any) -> None:
+    """Replace every literal_block with an opaque <pre data-amytis-code> marker
+    so the JS-side post-processor can run Shiki uniformly. Caption-bearing
+    literal-block-wrapper containers are flattened into the marker's data-title.
+
+    Code-group containers (emitted by the .. code-group:: directive) are
+    handled FIRST so their child literal_blocks are consumed before the
+    standalone-block pass sees them — otherwise the standalone pass would
+    replace them and we'd lose the grouping wrapper.
+    """
+    from docutils import nodes
+    import json
+
+    # Pass 1: collapse caption containers so child literal_blocks carry their caption
+    # as a custom attribute. (Doing this once here means the helper doesn't need to
+    # walk back up to find a parent literal-block-wrapper.)
+    for container in list(document.findall(nodes.container)):
+        if "literal-block-wrapper" not in (container.get("classes") or []):
+            continue
+        caption_node = next(
+            (c for c in container.children if isinstance(c, nodes.caption)),
+            None,
+        )
+        inner_block = next(
+            (c for c in container.children if isinstance(c, nodes.literal_block)),
+            None,
+        )
+        if caption_node is not None and inner_block is not None:
+            inner_block["amytis_caption"] = caption_node.astext().strip()
+            container.parent.replace(container, inner_block)
+
+    # Pass 2: handle code-group containers. The directive marks them with the
+    # 'amytis-code-group-source' class. Per CLAUDE.md "strict build over silent
+    # runtime failure", malformed groups raise rather than getting dropped, and
+    # group ids are issued from a monotonic counter so two groups with identical
+    # label sets never share an id (which would couple their tab radios).
+    group_counter = 0
+    for container in list(document.findall(nodes.container)):
+        if "amytis-code-group-source" not in (container.get("classes") or []):
+            continue
+
+        inner_blocks = list(container.findall(nodes.literal_block))
+        if not inner_blocks:
+            raise RstRenderError(
+                "Empty or malformed '.. code-group::' directive: expected at least one nested .. code-block:: child."
+            )
+
+        markers: list[str] = []
+        labels: list[str] = []
+        for block in inner_blocks:
+            marker, label = _build_inner_block_marker(block)
+            markers.append(marker)
+            labels.append(label)
+
+        group_counter += 1
+        group_id = f"rst-{group_counter}"
+        labels_json = html.escape(json.dumps(labels, ensure_ascii=False), quote=True)
+        wrapper_html = (
+            f'<div data-amytis-code-group="" data-labels="{labels_json}" '
+            f'data-group-id="{group_id}">'
+            + "".join(markers)
+            + "</div>"
+        )
+        container.parent.replace(container, nodes.raw("", wrapper_html, format="html"))
+
+    # Pass 3: replace remaining (non-grouped) literal_blocks.
+    for block in list(document.findall(nodes.literal_block)):
+        marker, _ = _build_inner_block_marker(block)
+        block.parent.replace(block, nodes.raw("", marker, format="html"))
+
+
 def extract_html_body_from_doctree(document: Any) -> str:
     from docutils.core import publish_from_doctree
 
@@ -598,22 +732,92 @@ def build_output(document: Any, source_file: Path, image_base_slug: str, warning
         raise RstRenderError("Missing document title.")
 
     assets = extract_assets(document, source_file, image_base_slug)
+    # Read-only extractions first; the literal-block transformation mutates the tree.
+    text = extract_body_text(document)
+    headings = extract_headings(document)
+    metadata = extract_metadata(document)
+
+    transform_literal_blocks_to_markers(document)
     html_body = extract_html_body_from_doctree(strip_preamble_nodes(document))
 
     return {
         "title": title_node.astext().strip(),
         "html": rewrite_html_assets(html_body, assets),
-        "text": extract_body_text(document),
-        "headings": extract_headings(document),
-        "metadata": extract_metadata(document),
+        "text": text,
+        "headings": headings,
+        "metadata": metadata,
         "assets": assets,
         "warnings": list(dict.fromkeys(warnings)),
     }
 
 
+_amytis_directives_registered = False
+
+
+def register_amytis_directives() -> None:
+    """Register the .. code-group:: directive and a code-block subclass that
+    accepts a :label: option. Both are global to the docutils registry, so
+    registering once per process is enough.
+
+    The code-block override only ADDS the :label: option; standard behavior
+    (language argument, :linenos:, :emphasize-lines:, :caption:) goes through
+    docutils' built-in implementation unchanged. The label is stashed on the
+    resulting literal_block via a custom amytis_label attribute and consumed
+    by transform_literal_blocks_to_markers.
+    """
+    global _amytis_directives_registered
+    if _amytis_directives_registered:
+        return
+
+    from docutils import nodes
+    from docutils.parsers.rst import Directive, directives
+    from docutils.parsers.rst.directives.body import CodeBlock as BaseCodeBlock
+
+    class LabeledCodeBlock(BaseCodeBlock):
+        option_spec = {
+            **BaseCodeBlock.option_spec,
+            "label": directives.unchanged,
+        }
+
+        def run(self):
+            result = super().run()
+            label = self.options.get("label")
+            if label:
+                for node in result:
+                    for lb in node.findall(nodes.literal_block):
+                        lb["amytis_label"] = label
+            return result
+
+    class CodeGroup(Directive):
+        """Wrap nested code-blocks into a tabbed code-group.
+
+        Body content is parsed as rST and contributes literal_block children;
+        transform_literal_blocks_to_markers later consumes the whole subtree
+        and emits the <div data-amytis-code-group> wrapper marker.
+        """
+
+        has_content = True
+        required_arguments = 0
+        optional_arguments = 0
+        option_spec = {}
+
+        def run(self):
+            wrapper = nodes.container()
+            wrapper["classes"].append("amytis-code-group-source")
+            self.state.nested_parse(self.content, self.content_offset, wrapper)
+            return [wrapper]
+
+    directives.register_directive("code-block", LabeledCodeBlock)
+    directives.register_directive("code", LabeledCodeBlock)
+    directives.register_directive("sourcecode", LabeledCodeBlock)
+    directives.register_directive("code-group", CodeGroup)
+    _amytis_directives_registered = True
+
+
 def render_single_file(source_file: Path, image_base_slug: str, strict: bool) -> dict[str, Any]:
     from docutils.core import publish_doctree
 
+    register_amytis_directives()
     warnings: list[str] = []
     source = normalize_legacy_doc_role_syntax(source_file.read_text(encoding="utf-8"))
     with temporary_role_overrides(source_file, warnings):