🤖 feat: improve docs with Shiki highlighting and page TOC (#547)

This PR enhances the documentation with three key improvements:

## 1. Added mdbook-pagetoc
Provides in-page table of contents for better navigation on long
documentation pages.

## 2. Build-Time Syntax Highlighting with Maximum Code Reuse
Replaced client-side markdown rendering with a build-time preprocessor
that:
- Highlights code at build time using Shiki (same as main app)
- **Reuses actual React components** via SSR to ensure consistency:
  - `CodeBlockSSR` component imports and uses `CopyIcon` from main app
  - Renders to static HTML with `renderToStaticMarkup()`
  - Eliminates duplication and ensures docs match app styling exactly
- Reduces browser bundle size (no 4.9MB JavaScript for syntax
highlighting)

**Implementation:**
- `scripts/mdbook-shiki.ts` - mdBook preprocessor that uses React SSR
- `src/components/Messages/CodeBlockSSR.tsx` - SSR-friendly code block
(reuses CopyIcon)
- `src/utils/highlighting/shiki-shared.ts` - Shared utilities between
app and docs
- `docs/theme/copy-buttons.js` - Vanilla JS to hydrate copy
functionality

**Fixes in this update:**
- ✅ Copy button now matches main app styling (reuses actual CopyIcon
component)
- ✅ All code blocks processed consistently (fixed regex to match blocks
without language)
- ✅ Removed trailing newlines (exact line counts)
- ✅ Better font-size balance (reduced to 0.85em)

## 3. Enhanced Styling
- Code blocks with line numbers and copy buttons matching main app
- Improved typography and spacing
- GitHub-style alert callouts
- Consistent color tokens from main app

## Verification
```bash
cd docs && mdbook build
# All checks pass:
# - 0 unprocessed code blocks
# - All using main app's CopyIcon
# - Correct line counts
# - Consistent styling
```

_Generated with `cmux`_

Author: ammar-agent

.github/workflows/docs.yml

@@ -39,7 +39,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.cargo/bin
-          key: ${{ runner.os }}-cargo-bins-mdbook-mermaid-0.16.0-linkcheck-0.7.7
+          key: ${{ runner.os }}-cargo-bins-mdbook-mermaid-0.16.0-linkcheck-0.7.7-pagetoc-0.2.1
           restore-keys: |
             ${{ runner.os }}-cargo-bins-
 
@@ -61,6 +61,20 @@ jobs:
             cargo install mdbook-linkcheck --version 0.7.7
           fi
 
+      - name: Install mdbook-pagetoc
+        run: |
+          if ! command -v mdbook-pagetoc &> /dev/null; then
+            cargo install mdbook-pagetoc --version 0.2.1
+          fi
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
       - name: Build docs
         run: cd docs && mdbook build
 

.gitignore

@@ -108,3 +108,10 @@ src/test-workspaces/
 terminal-bench-results/
 nodemon.json
 test_hot_reload.sh
+
+# TypeDoc
+.typedoc/
+
+# mdBook auto-generated assets
+docs/theme/pagetoc.css
+docs/theme/pagetoc.js

docs/book.toml

@@ -13,11 +13,17 @@ use-default-preprocessors = true
 [preprocessor.mermaid]
 command = "mdbook-mermaid"
 
+[preprocessor.pagetoc]
+
+[preprocessor.shiki]
+command = "bun ../scripts/mdbook-shiki.ts"
+renderer = ["html"]
+
 [output.html]
 git-repository-url = "https://github.com/coder/cmux"
 edit-url-template = "https://github.com/coder/cmux/edit/main/docs/{path}"
-additional-js = ["mermaid.min.js", "mermaid-init.js"]
-additional-css = ["theme/custom.css"]
+additional-js = ["mermaid.min.js", "mermaid-init.js", "theme/pagetoc.js", "theme/copy-buttons.js"]
+additional-css = ["theme/custom.css", "theme/pagetoc.css"]
 default-theme = "navy"
 preferred-dark-theme = "navy"
 favicon = "theme/favicon.webp"

docs/theme/copy-buttons.js

@@ -0,0 +1,65 @@
+/**
+ * Copy button handler for statically rendered code blocks
+ * Attaches click handlers to pre-rendered buttons
+ */
+
+(function() {
+  'use strict';
+
+  // Initialize copy buttons after DOM loads
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initCopyButtons);
+  } else {
+    initCopyButtons();
+  }
+
+  function initCopyButtons() {
+    document.querySelectorAll('.code-copy-button').forEach(function(button) {
+      button.addEventListener('click', function() {
+        var wrapper = button.closest('.code-block-wrapper');
+        var code = wrapper.dataset.code;
+        
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(code).then(function() {
+            showFeedback(button, true);
+          }).catch(function(err) {
+            console.warn('Failed to copy:', err);
+            showFeedback(button, false);
+          });
+        } else {
+          // Fallback for older browsers
+          fallbackCopy(code);
+          showFeedback(button, true);
+        }
+      });
+    });
+  }
+
+  function showFeedback(button, success) {
+    var originalContent = button.innerHTML;
+    
+    // Match the main app's CopyButton feedback - show "Copied!" text
+    if (success) {
+      button.innerHTML = '<span class="copy-feedback">Copied!</span>';
+    } else {
+      button.innerHTML = '<span class="copy-feedback">Failed!</span>';
+    }
+    button.disabled = true;
+    
+    setTimeout(function() {
+      button.innerHTML = originalContent;
+      button.disabled = false;
+    }, 2000);
+  }
+
+  function fallbackCopy(text) {
+    var textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    document.execCommand('copy');
+    document.body.removeChild(textarea);
+  }
+})();

docs/theme/custom.css

@@ -509,3 +509,135 @@ details[open] > summary::before {
   background-size: contain;
   background-repeat: no-repeat;
 }
+
+
+/* Page TOC (Table of Contents) overrides */
+@media only screen and (min-width:1440px) {
+  .pagetoc a {
+    /* Reduce vertical spacing for more compact TOC */
+    padding-top: 2px !important;
+    padding-bottom: 2px !important;
+    line-height: 1.4;
+    font-size: 0.9em;
+  }
+
+  /* Tighter indentation for nested levels */
+  .pagetoc .pagetoc-H2 {
+    padding-left: 15px !important;
+  }
+  .pagetoc .pagetoc-H3 {
+    padding-left: 30px !important;
+  }
+  .pagetoc .pagetoc-H4 {
+    padding-left: 45px !important;
+  }
+
+  /* Add subtle visual hierarchy */
+  .pagetoc .pagetoc-H2 a {
+    font-weight: 500;
+  }
+  .pagetoc .pagetoc-H3 a {
+    font-weight: 400;
+    opacity: 0.9;
+  }
+  .pagetoc .pagetoc-H4 a {
+    font-weight: 400;
+    opacity: 0.8;
+  }
+}
+
+
+
+
+
+/* Code block wrapper with line numbers and copy button (from cmux app) */
+.code-block-wrapper {
+  position: relative;
+  margin: 0.75em 0;
+}
+
+/* Code block with line numbers - each line is a grid row */
+.code-block-container {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  background: var(--color-background-secondary);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  padding: 6px 0;
+  font-family: var(--font-monospace);
+  font-size: 12px;
+  line-height: 1.6;
+  overflow-x: auto;
+}
+
+.line-number {
+  background: rgba(0, 0, 0, 0.2);
+  padding: 0 8px 0 6px;
+  text-align: right;
+  color: rgba(255, 255, 255, 0.4);
+  user-select: none;
+  border-right: 1px solid rgba(255, 255, 255, 0.2);
+}
+
+.code-line {
+  padding: 0 8px;
+  white-space: pre;
+}
+
+.code-line code {
+  background: transparent;
+  padding: 0;
+}
+
+/* Reusable copy button styles */
+.copy-button {
+  padding: 6px 8px;
+  background: rgba(0, 0, 0, 0.6);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 4px;
+  color: rgba(255, 255, 255, 0.6);
+  cursor: pointer;
+  transition:
+    color 0.2s,
+    background 0.2s,
+    border-color 0.2s;
+  font-size: 12px;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.copy-button:hover {
+  background: rgba(0, 0, 0, 0.8);
+  color: rgba(255, 255, 255, 0.9);
+  border-color: rgba(255, 255, 255, 0.2);
+}
+
+.copy-icon {
+  width: 14px;
+  height: 14px;
+}
+
+.copy-feedback {
+  font-size: 11px;
+  color: rgba(255, 255, 255, 0.9);
+}
+
+/* Code block specific positioning */
+.code-copy-button {
+  position: absolute;
+  bottom: 8px;
+  right: 8px;
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+
+.code-block-wrapper:hover .code-copy-button {
+  opacity: 1;
+}
+
+/* Hide mdBook's default highlight.js styles for transformed blocks */
+.code-block-wrapper pre,
+.code-block-wrapper .hljs {
+  display: none;
+}

scripts/docs.sh

@@ -8,5 +8,5 @@ if [ ! -f "docs/mermaid-init.js" ] || [ ! -f "docs/mermaid.min.js" ]; then
   cd ..
 fi
 
-# Serve the docs (bind to all hosts for remote access)
-cd docs && mdbook serve --hostname 0.0.0.0 --open
+# Serve the docs (bind to all hosts for remote access, port 3001 to avoid conflict with main app)
+cd docs && mdbook serve --hostname 0.0.0.0 --port 3001 --open