Skip to content

Refine Getting Started docs: typography, preview styling, content polish#6340

Merged
Alek99 merged 13 commits intomainfrom
alek/port-pr-1818
Apr 25, 2026
Merged

Refine Getting Started docs: typography, preview styling, content polish#6340
Alek99 merged 13 commits intomainfrom
alek/port-pr-1818

Conversation

@Alek99
Copy link
Copy Markdown
Member

@Alek99 Alek99 commented Apr 17, 2026

Summary

Ports reflex-web PR #1818 into docs/app and follows up with a content pass across all four Getting Started markdown pages.

Typography & preview styling

  • Smaller semibold headings, lighter body weight, tighter vertical rhythm
  • Content column widened (42rem → 52rem, 56rem → 64rem); right sidebar moved xl:2xl: so mid-width screens have room to read
  • Navbar tabs visible from md: (was xl:) instead of collapsing to a burger
  • Pill-style tabs (pill-tab / pill-tab-list), slate-tinted inline rt-Code, hover-reveal copy button with "Copy" label, softer borders
  • docgen_pipeline._render_tabs / _render_section rewritten with cleaner rx.el.div + tailwind classes

Getting Started content

  • Introduction: new tagline + time estimate, pill tabs, slate highlight (was violet), tightened walkthrough, two md alert info CTA cards
  • Installation: ~3 min estimate, removed embedded video, rewrote as single uv-based flow with <your-app> placeholder, Rosetta + bun.exe notes promoted to alert blocks
  • Basics: ~10 min estimate, consolidated single-line setup steps, fixed rx.app typo, fixed three broken [`code`](link) links (rx.el, rx.cond, rx.foreach were rendering empty), added CTA cards
  • Dashboard tutorial: ~20 min hands-on estimate, trimmed the ~180-line finished-app dump at the top down to a one-sentence roadmap + link to #full-app, numbered Setup steps, promoted "What are you building?" H3 → H2, renamed Conclusion → Full app + Recap, dropped Advanced Section stub, unified all 10 preview boxes (slate border, 12px radius, 2em padding, spacing="4", rx.box wrap)

Sidebar order

  • Getting Started now shows Installation before Introduction

Known caveats

  • The link-handler for inline [`code`](url) markdown in reflex_ui_shared.components.blocks.typography.doclink2 takes text: str and drops nested <code> children — this PR works around it by using plain-text link labels. A proper fix (accept *children and render inside rx.link) would benefit all pages.
  • padding="2em" on preview containers may not fully render because [&>div]:!p-0 in docpage.py emits padding: 0 !important on every direct <div> child; an extra rx.box wrap, swap to rx.el.section, or removing the rule would fix it.

Test plan

  • Visit /docs/getting-started/introduction, /installation, /basics, /dashboard-tutorial
  • Verify headings feel tighter and content column is wider
  • Resize browser: tabs stay visible through md:, right sidebar hides below 2xl:, hamburger only at <md:
  • Tabs render as pills (not underline), active state = white pill with subtle shadow
  • Hover a code block → copy button fades in with "Copy" label
  • Inline `code` renders slate, not purple
  • Sidebar: Getting Started expands with Installation above Introduction
  • uv run reflex compile succeeds

🤖 Generated with Claude Code

@codspeed-hq
Copy link
Copy Markdown

codspeed-hq Bot commented Apr 17, 2026

Merging this PR will not alter performance

✅ 9 untouched benchmarks


Comparing alek/port-pr-1818 (6e7ff3d) with main (8430f30)

Open in CodSpeed

@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented Apr 17, 2026

Greptile Summary

This PR refines all four Getting Started docs with tighter typography (smaller semibold headings, lighter body weight), a wider content column, pill-style tabs, slate-tinted inline code, and a hover-reveal copy button. Content is polished across Introduction, Installation, Basics, and Dashboard Tutorial with time estimates, consolidated setup steps, fixed typos (rx.appapp), fixed broken [`code`](link) anchors, and CTA alert cards.

  • P1: installation.md line 109 links to /docs/getting-started/introduction (hyphen) — all other Getting Started links use /docs/getting_started/… (underscore), so this will 404.
  • P2: .code-block button in tailwind-theme.css sets top: 8px and right: 12px without position: absolute; the positioning silently depends on Radix UI's implicit button styling.

Confidence Score: 4/5

Safe to merge after fixing the broken internal link on the installation page CTA.

One P1 broken link will 404 for any user clicking the 'Next: Build your first app' CTA on the Installation page. All other changes are well-scoped documentation and styling updates with no logic regressions.

docs/getting_started/installation.md — broken link on the final CTA line.

Important Files Changed

Filename Overview
docs/getting_started/installation.md Rewritten as concise uv-based flow; contains a broken internal link (/docs/getting-started/introduction should use underscores) on the final CTA line.
docs/app/assets/tailwind-theme.css Adds rt-Code slate override, hover-reveal copy button, and pill-tab styles; top/right on the copy button lack position: absolute, making those values implicitly dependent on Radix UI's own button positioning.
docs/app/reflex_docs/docgen_pipeline.py Rewrites _render_tabs and _render_section with cleaner rx.el.div + inline styles; removes unused c_color import; no logic issues.
docs/app/reflex_docs/templates/docpage/docpage.py Content column widened (42→52rem, 56→64rem) and right sidebar breakpoint moved from xl: to 2xl:; straightforward layout tweak.
docs/getting_started/dashboard_tutorial.md Trims ~180-line finished-app preview from intro, unifies preview box styling (slate border, rx.box wrap), fixes compile-time anchor link, renames Conclusion → Full app; no issues.
packages/reflex-ui-shared/src/reflex_ui_shared/components/blocks/headings.py All heading levels downsized (e.g. h1 lg:text-5xl→4xl) and weight changed from font-[525] to font-semibold; consistent across _comp and _comp_xd variants.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User visits /docs/getting-started] --> B[Sidebar: Getting Started]
    B --> C[Installation\n/docs/getting_started/installation]
    B --> D[Introduction\n/docs/getting_started/introduction]
    B --> E[Basics\n/docs/getting_started/basics]
    B --> F[Dashboard Tutorial\n/docs/getting_started/dashboard_tutorial]
    C -->|CTA link broken hyphen| X["/docs/getting-started/introduction\n404"]
    C -->|should link to| D
    style X fill:#ffcccc,stroke:#cc0000
Loading

Reviews (1): Last reviewed commit: "Refine Getting Started docs: typography,..." | Re-trigger Greptile

Comment thread docs/getting_started/installation.md
Comment thread docs/app/assets/tailwind-theme.css
Alek99 and others added 2 commits April 24, 2026 12:01
Port reflex-web PR #1818 plus content polish across all Getting Started pages.

Typography & preview styling (docs/app + packages/reflex-ui-shared):
- Tighter headings (smaller, semibold) and lighter body weight
- Wider content column (42rem→52rem / 56rem→64rem); right sidebar moved
  from xl: to 2xl: so mid-width screens have more room
- Navbar tabs visible from md: (was xl:) so they don't collapse to a
  burger at medium widths
- Pill-style tabs (pill-tab / pill-tab-list); slate-tinted inline rt-Code;
  hover-reveal copy button with "Copy" label; softer borders
- docgen_pipeline: cleaner rx.el.div section/tabs renderers with
  consistent gap and padding

Getting Started content:
- Introduction: new tagline, pill tabs, slate highlight (was violet),
  tightened walkthrough, added "Keep learning" / "Ship faster with AI"
  CTA cards
- Installation: added ~3 min estimate, removed embedded video, rewrote
  as a single uv-based flow with <your-app> placeholder, promoted Rosetta
  + bun.exe notes to md alert blocks, added "Next" CTA
- Basics: added ~10 min estimate, flattened Prerequisites wrapper,
  consolidated four single-line setup steps, fixed `rx.app` typo, fixed
  three broken [`code`](link) markdown links (rx.el / rx.cond /
  rx.foreach were rendering empty), added two CTA cards
- Dashboard tutorial: added ~20 min estimate, trimmed ~180-line
  finished-app dump at top down to a one-sentence roadmap + link to
  #full-app, numbered Setup steps, promoted "What are you building?"
  from H3 to H2, renamed Conclusion → Full app + Recap, dropped
  Advanced Section stub, unified all 10 preview boxes (slate border,
  12px radius, 2em padding, spacing="4", rx.box wrap)

Sidebar order:
- Getting Started now lists Installation before Introduction

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The tightened version lost nuance; the original phrasing about State
being uncompiled server code with no special caveats reads better.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@Alek99 Alek99 force-pushed the alek/port-pr-1818 branch from d8a34d2 to 0a4910e Compare April 24, 2026 19:02
@Alek99 Alek99 requested a review from a team as a code owner April 24, 2026 19:02
Comment thread docs/getting_started/introduction.md
Comment thread docs/getting_started/introduction.md
Comment thread docs/getting_started/dashboard_tutorial.md
Alek99 and others added 9 commits April 24, 2026 12:36
- Add H1 headings to introduction and installation pages.
- Info alerts now use the neutral --c-slate-* scale to match codeblock
  styling (border + background) instead of the blue-tinted default.
- Promote the Rosetta 2 macOS note from info to warning.
- Show the finished dashboard app preview at the top of the tutorial
  (no code) so readers see the end result before walking through it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Dashboard tutorial: collapse list-of-lists → dataclass churn, introduce
  `@dataclass User` up front, reduce from 4 to 2 table previews.
- Dashboard tutorial: restyle the hero + full-app previews with a header
  row (title + subtitle + Add User button), compact table, polished bar
  chart (rounded bars, clean axes, dashed gridlines, slate-1 frame bg).
- Dashboard tutorial: rename "Cleanup" → "Customize", "Full app" → "Full
  app styled", shorten titles to ≤4 words, fix framing bugs around the
  graph-empty messaging and "last part" claim.
- Chat tutorial: shorten H1 to "AI Chat App", add meta line, add a live
  hero preview styled like the finished app, drop the hardcoded-API-key
  section, switch setup to uv-first, convert Note blockquote to alert.
- Chat tutorial style: modernize bubbles — 18px rounded with tail
  corners, slate-3 questions with border, accent-9 answers with white
  text, drop heavy shadows.
- Introduction / Basics: add `as_="h3"` to demo `rx.heading` calls so
  they don't render as additional `<h1>` on the page.
- Code blocks: add expand/collapse toggle on code blocks over 20 lines,
  using native `<details>` + `has-[details[open]]:` CSS so no Reflex
  state is needed.
- Shiki copy button: halve the animation timings so the copy feedback
  feels snappier.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A segmented button on the right side of the breadcrumb:
- Clicking the copy icon fetches the current page's `.md` URL and copies
  the markdown to the clipboard, with a clipboard-API fallback to
  `document.execCommand('copy')` for permission-blocked contexts.
- Clicking the chevron opens a popover with two items: "Copy page" and
  a link to "llms-full.txt" for full-site markdown.
- Icon pops to a green checkmark for ~1.5s as click feedback.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirrors the marketing site's GitHub button — icon plus star count,
linking to the reflex repo. Placed before the search bar.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two new menu items below the existing copy/llms-full options open the
page in ChatGPT or Claude with a prefilled prompt referencing the
page's `.md` URL: "Read from <url> so I can ask questions about its
contents".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Highlighted item at the top of the dropdown opens build.reflex.dev
with the page's `.md` URL prefilled into the prompt. Visual treatment
uses a violet gradient icon tile and gradient hover background to
stand out from the other items.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Switching from `run_script` + `window.open` (which got blocked as a
popup since it ran after a server roundtrip) to real `<a target="_blank">`
elements. Hrefs are constructed server-side using a hardcoded prod
docs origin so the prefilled prompt references a fetchable URL.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Revert the as_="h3" additions on demo `rx.heading` calls in basics.md
and introduction.md — clutter in example code. The single-H1
guarantee is now enforced at the source: the `md definition` block's
title `rx.heading` defaults to `as_="h3"` so directives no longer
emit extra `<h1>` elements.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Kastier1
Kastier1 previously approved these changes Apr 24, 2026
`add_imports` calls `code_block_markdown(_MOCK_ARG)` to walk the
component tree for imports, which passed a `Var[str]` rather than a
real string. The expand-threshold check `code.count('\n')` raised
`VarAttributeError`. Fall back to the plain block when `code` isn't a
real `str`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Comment thread docs/getting_started/dashboard_tutorial.md
The python source block in the dashboard tutorial's Full app styled
section was the old layout (plain index, basic bar chart). Update it
to match the rendered eval block: nested rx.box + rx.vstack with the
header row, compact table, and polished bar chart.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@Alek99 Alek99 merged commit 1a64caa into main Apr 25, 2026
68 of 69 checks passed
@Alek99 Alek99 deleted the alek/port-pr-1818 branch April 25, 2026 00:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants