Redesign docs site and configure beamtalk.dev#1007
Merged
Conversation
- Add CNAME for beamtalk.dev custom domain in GitHub Pages workflow - Redesign CSS: Inter font, warm palette, indigo accent, dark code blocks, top navigation bar, sidebar section labels - Add two-column landing page hero with syntax-highlighted code preview - Thread asset_prefix through to page_header for correct nav links in both standalone and site mode - Strip HTML comments (license headers) from rendered markdown output - Clarify license header policy: code files only, not .md files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
📝 WalkthroughWalkthroughUpdates the documentation site generation: large CSS/theme and layout overhaul (top nav, sidebar, responsive), HTML structure and page-header signature changes, renderer sanitization tweak (drop HTML comments), landing page with highlighted code/cards, propagate an asset_prefix through page writers, and add a CNAME file step to the Pages workflow. License header guidance tightened. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
crates/beamtalk-cli/src/commands/doc/site.rs (1)
123-159:landing_card_metakeyed by display title is brittle.If a title string in
PROSE_PAGESchanges, Line 157 fallback is used and descriptions quietly disappear. Prefer keying metadata byoutput_file(stable identifier) or storing emoji/description directly inPROSE_PAGES.Also applies to: 236-245
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@crates/beamtalk-cli/src/commands/doc/site.rs` around lines 123 - 159, The metadata lookup in landing_card_meta is brittle because it keys on display title; update it to use a stable identifier instead (e.g. output_file) or move the emoji/description into PROSE_PAGES and pass that metadata into landing_card_meta so the mapping no longer depends on mutable display strings; modify the landing_card_meta signature and call sites (or PROSE_PAGES entries) accordingly and ensure the same change is applied to the other similar helper referenced around the second occurrence (the block currently mirroring lines 236-245) so descriptions don't fall back to the default when titles change.crates/beamtalk-cli/src/commands/doc/renderer.rs (1)
86-93: Comment stripping predicate is too broad for mixed raw-HTML chunks.At Line 88, any raw HTML starting with
<!--is fully dropped. A chunk like<!--meta--><em>x</em>would lose<em>x</em>as well. Restrict dropping to events that are purely comments.Proposed fix
- Event::Html(raw) | Event::InlineHtml(raw) => { - if raw.trim_start().starts_with("<!--") { + Event::Html(raw) | Event::InlineHtml(raw) => { + let trimmed = raw.trim(); + if trimmed.starts_with("<!--") && trimmed.ends_with("-->") { None } else { Some(Event::Text(raw)) } }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@crates/beamtalk-cli/src/commands/doc/renderer.rs` around lines 86 - 93, The current Event::Html / Event::InlineHtml handler drops any raw chunk whose trimmed start is "<!--", which removes trailing valid HTML (e.g. "<!--meta--><em>x</em>"); update the predicate in that match arm to only drop when the trimmed raw is solely an HTML comment (e.g. trim both ends and check it starts with "<!--" AND ends with "-->"), otherwise treat the chunk as sanitized content (keep it as Some(Event::Text(raw)) or pass through sanitization); refer to the Event::Html / Event::InlineHtml match arm and the raw variable to implement this stricter comment-only check.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@crates/beamtalk-cli/src/commands/doc/assets.rs`:
- Around line 552-557: The selector `.code-window-bar span` is too broad and
causes decorative `.code-dot-*` spans to inherit title styles; update the CSS to
target only the filename/title by creating and using a dedicated class (e.g.,
`.code-window-title`) instead of styling every span. Replace `.code-window-bar
span { ... }` with a rule scoped to `.code-window-bar .code-window-title { ...
}`, add that class to the filename/title element in the markup, and leave
`.code-dot-*` spans unstyled so the dot indicators keep their intended spacing
and font.
In `@crates/beamtalk-cli/src/commands/doc/layout.rs`:
- Around line 33-37: The header's top-nav anchors currently build all targets
from the single variable nav_prefix which breaks standalone doc output (e.g.,
href="{nav_prefix}" -> "" resolves to the current page and "docs/..." or
"apidocs/" are missing); update the layout generation in layout.rs to be
mode-aware: detect standalone vs site mode (e.g., a boolean or by checking
nav_prefix or output_root) and branch when rendering the <a class="nav-logo">
and the links inside <nav class="nav-links"> so that in standalone mode the logo
points to the output root (explicit "/" or "./" as appropriate) and the
Language/Architecture/API links point to the correct root-relative locations (or
omit API link when apidocs are emitted to the root), while in site mode continue
using nav_prefix + "docs/..." and nav_prefix + "apidocs/"; adjust the template
logic that uses nav_prefix to choose paths accordingly so standalone doc output
resolves links correctly.
---
Nitpick comments:
In `@crates/beamtalk-cli/src/commands/doc/renderer.rs`:
- Around line 86-93: The current Event::Html / Event::InlineHtml handler drops
any raw chunk whose trimmed start is "<!--", which removes trailing valid HTML
(e.g. "<!--meta--><em>x</em>"); update the predicate in that match arm to only
drop when the trimmed raw is solely an HTML comment (e.g. trim both ends and
check it starts with "<!--" AND ends with "-->"), otherwise treat the chunk as
sanitized content (keep it as Some(Event::Text(raw)) or pass through
sanitization); refer to the Event::Html / Event::InlineHtml match arm and the
raw variable to implement this stricter comment-only check.
In `@crates/beamtalk-cli/src/commands/doc/site.rs`:
- Around line 123-159: The metadata lookup in landing_card_meta is brittle
because it keys on display title; update it to use a stable identifier instead
(e.g. output_file) or move the emoji/description into PROSE_PAGES and pass that
metadata into landing_card_meta so the mapping no longer depends on mutable
display strings; modify the landing_card_meta signature and call sites (or
PROSE_PAGES entries) accordingly and ensure the same change is applied to the
other similar helper referenced around the second occurrence (the block
currently mirroring lines 236-245) so descriptions don't fall back to the
default when titles change.
ℹ️ 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.
📒 Files selected for processing (10)
.github/workflows/docs.ymlCLAUDE.mdcrates/beamtalk-cli/src/commands/doc/assets.rscrates/beamtalk-cli/src/commands/doc/layout.rscrates/beamtalk-cli/src/commands/doc/mod.rscrates/beamtalk-cli/src/commands/doc/renderer.rscrates/beamtalk-cli/src/commands/doc/site.rsdocs/ADR/0028-beam-interop-strategy.mddocs/agents/expanded.mddocs/beamtalk-security.md
💤 Files with no reviewable changes (2)
- docs/beamtalk-security.md
- docs/ADR/0028-beam-interop-strategy.md
- Scope `.code-window-bar span` CSS to `.code-window-title` class to avoid decorative dots inheriting text-spacing rules - Fix standalone nav: omit prose-docs links when nav_prefix is empty (beamtalk doc output has no docs/ or apidocs/ subdirs); logo now points to index.html instead of bare "" - Tighten HTML comment stripping: only drop events that are *purely* a comment (starts with <!-- AND ends with -->) to avoid swallowing mixed chunks like <!--x--><em>y</em> - Key landing_card_meta by output_file (stable) instead of display title to prevent silent description loss when titles are renamed Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@crates/beamtalk-cli/src/commands/doc/site.rs`:
- Line 185: The landing header is rendered in standalone mode because
page_header is called with an empty prefix; change the call site (the
html.push_str(&page_header("Beamtalk", "style.css", "")) invocation) to pass a
non-empty prefix (for example "/" or the existing site prefix variable in scope)
so page_header does not treat it as API-only mode and the
Language/Architecture/API links are preserved; update the argument to
page_header to use the correct prefix value used elsewhere in site generation.
ℹ️ 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.
📒 Files selected for processing (4)
crates/beamtalk-cli/src/commands/doc/assets.rscrates/beamtalk-cli/src/commands/doc/layout.rscrates/beamtalk-cli/src/commands/doc/renderer.rscrates/beamtalk-cli/src/commands/doc/site.rs
page_header("Beamtalk", "style.css", "") was triggering standalone mode
(empty nav_prefix), suppressing Language/Architecture/API nav links on
the site landing page. Pass "./" so site mode is detected correctly.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
crates/beamtalk-cli/src/commands/doc/site.rs (1)
158-162: Consider logging when fallback is used.The fallback case silently returns a generic icon and empty description. If a new prose page is added to
PROSE_PAGESwithout updating this function, the card will render with<p></p>and a generic icon.A
debug!log when hitting the fallback would help catch missing entries during development.💡 Optional: Add debug log for fallback case
- _ => ("📄", ""), + unknown => { + debug!("No landing_card_meta for '{unknown}', using fallback"); + ("📄", "") + }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@crates/beamtalk-cli/src/commands/doc/site.rs` around lines 158 - 162, The fallback match arm currently returns ("📄", "") silently; update that arm to emit a debug! log (using the debug! macro) when it's hit so missing PROSE_PAGES entries are visible during development—include the page identifier or key variable passed into the function (the same name used in the match) in the message for context. Modify the match's _ => branch in the function that maps prose pages to (icon, description) so it logs the missing page before returning the generic ("📄", ""). Ensure the debug log is concise and descriptive (e.g., "prose card fallback: missing entry for {page_id}").
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@crates/beamtalk-cli/src/commands/doc/site.rs`:
- Around line 158-162: The fallback match arm currently returns ("📄", "")
silently; update that arm to emit a debug! log (using the debug! macro) when
it's hit so missing PROSE_PAGES entries are visible during development—include
the page identifier or key variable passed into the function (the same name used
in the match) in the message for context. Modify the match's _ => branch in the
function that maps prose pages to (icon, description) so it logs the missing
page before returning the generic ("📄", ""). Ensure the debug log is concise
and descriptive (e.g., "prose card fallback: missing entry for {page_id}").
ℹ️ 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.
📒 Files selected for processing (1)
crates/beamtalk-cli/src/commands/doc/site.rs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.mdfilesTest plan
just build && just clippy && just fmt-checkall pass🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Chores