Docs site: HTML comment fix, ADR generation, mobile responsiveness

[jamesc]

Summary

• Fix HTML comment stripping for pulldown-cmark 0.13 — multi-line HtmlBlock events are now collected and examined as a whole before deciding to drop
• Generate ADR pages from docs/ADR/*.md with dedicated sidebar navigation and index page
• Extract Tooling page from language-features.md into standalone beamtalk-tooling.md
• Add class hierarchy summaries — one-line doc comment excerpts in the hierarchy tree
• Simplify stdlib README — remove outdated class hierarchy diagram, BEAM mapping table, and double H1
• Update CNAME to www.beamtalk.dev
• Mobile responsiveness — single-column TOC, scrollable tables, scaled headings, stacked method headers, sidebar overlay with tap-to-close, 480px small-screen breakpoint
• Fix wording — "cleaned-up" → "modernised" Smalltalk syntax

Test plan

• just test passes (all Rust, stdlib, BUnit tests green)
• Pre-push hooks pass (clippy, fmt, dialyzer, biome)
• Verify rendered site at www.beamtalk.dev after deploy
• Check mobile layout on phone/tablet

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added Architecture Decision Records (ADRs) to docs with dedicated navigation and index.
  • Improved responsive design for docs on mobile and tablet.
  • Added class summaries in documentation hierarchy.
  • Enhanced sidebar overlay for improved mobile navigation.

• Documentation

  • Added a comprehensive Tooling guide (CLI, REPL, VS Code, testing).
  • Updated language features with refined examples and terminology.
  • Simplified standard library README and updated documentation links to the new domain.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 070f778 and ab8ce5d.

📒 Files selected for processing (1)

• README.md

---

📝 Walkthrough

Walkthrough

Adds ADR (Architecture Decision Records) generation and integration into the docs site pipeline; strips HTML comments during markdown rendering; renders per-class first-line summaries in hierarchies; introduces a responsive sidebar overlay and CSS tweaks; adds new tooling docs; updates GitHub Pages CNAME to www.beamtalk.dev.

Changes

Cohort / File(s)	Summary
ADR Generation & Site Integration crates/beamtalk-cli/src/commands/doc/site.rs, crates/beamtalk-cli/src/commands/doc/mod.rs	Adds ADR discovery, parsing, rendering, index generation, and navigation. New generate_adr_docs public function; generate_prose_docs gains extra_links param to accept ADR link rewrites. Integrates ADR generation into overall site flow and updates PROSE_PAGES.
Markdown Rendering & HTML Sanitization crates/beamtalk-cli/src/commands/doc/renderer.rs	Adds strip_html_comments to drop pure HTML comments from pulldown-cmark event streams; refactors render_doc to apply block- and inline-level HTML comment stripping. Injects sidebar-overlay element and updates sidebar toggle/overlay handlers.
Hierarchy Summaries & Layout crates/beamtalk-cli/src/commands/doc/layout.rs	Builds a name→summary map from class doc_comments and threads it through hierarchy rendering. Updates write_hierarchy_node signature to accept summaries and renders optional per-class first-line summaries.
Responsive Styling & UI Assets crates/beamtalk-cli/src/commands/doc/assets.rs	Adds .sidebar-overlay styles and responsive breakpoints (max-width: 768px, 480px). Collapses TOC on small screens, enables table horizontal scroll, adjusts typography, code padding, and method-header stacking for mobile.
Prose & New Tooling Doc docs/beamtalk-language-features.md, docs/beamtalk-tooling.md	Rewords and tightens language-features doc, expands live-patching example, removes embedded Tooling section and adds docs/beamtalk-tooling.md with CLI/REPL/VS Code/testing docs.
Stdlib README Cleanup stdlib/src/README.md	Removes extensive class-hierarchy, BEAM mapping, and design sections; replaces with minimal pointer to individual class pages.
Site Config (CI/CD) .github/workflows/docs.yml, README.md	Updates GitHub Pages CNAME from beamtalk.dev to www.beamtalk.dev. Updates API docs links in README.

Sequence Diagram

sequenceDiagram
    participant SiteGen as Site Generator
    participant ADRDisc as ADR Discovery
    participant ADRRender as ADR Renderer
    participant ProseGen as Prose Generator
    participant LinkRewrite as Link Rewriter
    participant PageRender as Page Renderer

    SiteGen->>ADRDisc: discover_adrs(adr_source)
    ADRDisc->>ADRDisc: parse metadata (number, slug, title)
    ADRDisc->>ADRRender: render_adr_page(adr)
    ADRDisc->>ADRRender: render_adr_index(adrs)
    ADRDisc-->>SiteGen: return adr_links

    SiteGen->>ProseGen: generate_prose_docs(prose_pages, extra_links=adr_links)
    ProseGen->>LinkRewrite: rewrite_prose_links(content, extra_links)
    LinkRewrite-->>ProseGen: rewritten content
    ProseGen->>PageRender: render prose pages (with ADR nav)
    SiteGen->>PageRender: write_site_landing_page (include ADR cards)
    PageRender-->>SiteGen: site generation complete

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Restructure docs site: landing page, /apidocs/, and /docs/ prose pages (BT-652) #625: Adds/changes site generation pipeline and touches the same doc site modules; closely related to ADR integration and prose link changes.
• Replace hand-rolled markdown renderer with pulldown-cmark (BT-645) #619: Changes markdown rendering to pulldown-cmark and event handling; closely related to HTML comment stripping and renderer refactor.
• Redesign docs site and configure beamtalk.dev #1007: Modifies docs site rendering (sidebar/header/hierarchy); overlaps with sidebar overlay, hierarchy, and renderer edits.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the three main categories of changes: HTML comment handling fix, ADR generation, and mobile responsiveness improvements.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch worktree-docs/html-comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

stdlib/src/README.md (1)

7-7: LGTM! Simplification aligns with the documentation overhaul.

The minimal README appropriately directs users to per-class API pages, which aligns with the PR's broader documentation restructuring.

Optional enhancement for discoverability

Consider adding a link or brief navigation hint to help users locate the class pages, e.g.:

-See each class page for full API documentation and usage examples.
+See the [class documentation](../docs/stdlib/) for full API documentation and usage examples.

Or list a few key classes if navigation is not immediately obvious from the rendered site context.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@stdlib/src/README.md` at line 7, Update the README (stdlib/src/README.md) to
include a short navigation hint or direct link(s) to the per-class API pages so
users can find class documentation more easily; for example add a sentence like
"See the API docs at <site-root>/stdlib or the class index" or list 3–5 key
class pages (e.g., ClassA, ClassB, ClassC) to improve discoverability when the
site context doesn't make navigation obvious.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@stdlib/src/README.md`:
- Line 7: Update the README (stdlib/src/README.md) to include a short navigation
hint or direct link(s) to the per-class API pages so users can find class
documentation more easily; for example add a sentence like "See the API docs at
<site-root>/stdlib or the class index" or list 3–5 key class pages (e.g.,
ClassA, ClassB, ClassC) to improve discoverability when the site context doesn't
make navigation obvious.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 96bf782 and 070f778.

📒 Files selected for processing (9)

• .github/workflows/docs.yml
• crates/beamtalk-cli/src/commands/doc/assets.rs
• crates/beamtalk-cli/src/commands/doc/layout.rs
• crates/beamtalk-cli/src/commands/doc/mod.rs
• crates/beamtalk-cli/src/commands/doc/renderer.rs
• crates/beamtalk-cli/src/commands/doc/site.rs
• docs/beamtalk-language-features.md
• docs/beamtalk-tooling.md
• stdlib/src/README.md