Skip to content

scripts/render_design_doc: support collapsible TOC navigation, table overflow wrapping fixes, and inline SVG diagram passthrough #887

Description

@JoshuaVSherman

Part of #737

What this builds

Enhances scripts/render_design_doc.ts (and its test suite) with layout and rendering improvements requested during interactive design document reviews:

  1. Collapsible Sidebar Navigation: Adds a collapse toggle button inside the <nav class="toc"> header and a floating ☰ Table of Contents button when collapsed. When collapsed, .layout.toc-collapsed expands the main content area to 100% full width (grid-template-columns: 1fr). Persists the user's collapsed/expanded preference across page reloads via localStorage.
  2. Table Overflow & Column Formatting: Fixes narrow letter-by-letter / single-word cell wrapping by applying overflow-wrap: normal; word-break: normal; on th/td, white-space: nowrap; on th headers, and min-width: 650px on tables inside scrollable .table-wrapper containers.
  3. Raw SVG Passthrough: Passes inline <svg ...>...</svg> blocks directly through to HTML output unescaped so rich graphical Entity Relationship Diagrams (ERDs) and architecture diagrams render visually in Chrome rather than escaping to raw text.

Acceptance criteria

  1. Running scripts/render_design_doc.ts or scripts/render-design-doc.sh on markdown containing <svg> blocks renders raw unescaped SVG elements in the output HTML.
  2. The rendered HTML includes a collapsible Table of Contents sidebar with toggle controls ( and ☰ Table of Contents), expanding main content to full width when collapsed and saving collapsed state in localStorage.
  3. Multi-column tables inside .table-wrapper maintain normal word boundaries and nowrap headers without squished single-word column wrapping.
  4. All layout unit tests in test/render_design_doc_script.test.ts pass 100% green.

Metadata

Metadata

Assignees

No one assigned

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions