Skip to content

docs: new landing headline and a thumbnail on the YouTube box - #744

Open
JuroOravec wants to merge 1 commit into
mainfrom
docs/landing-headline-video-thumbnail
Open

JuroOravec wants to merge 1 commit into
mainfrom
docs/landing-headline-video-thumbnail

Conversation

@JuroOravec

Copy link
Copy Markdown
Collaborator

What changed

Two changes to the docs site landing page. The docs site and the root README are the only things that change. No published package (citry, citry-core, citry-ui, ...) changes, so nothing the 1.x promise covers moves, and no changelog entry is needed.

1. New headline

The headline is now "Safe, fast, and smart Python frontend engineered for AI agents." in docs_site/content/index.md and in the README title (README.md line 5, which ships to PyPI; the line has no links, so the published-README rules are unaffected). git grep -i "engineered for" and git grep -i "the complete python" find no other copy outside docs/design/ and the archived docs_site/versions/ snapshots, which stay as they are. Social cards use the page title and description, not the headline, so no generated image changes.

How the line break works:

  • The last words sit in <span class="landing-hero__tail">AI agents.</span> inside the Markdown heading. The span is display: block in landing.py, so "AI agents." starts its own line. A span (not a <br>) keeps the heading text one sentence for search and screen readers, and linkify_headings still wraps the whole heading in its permalink <a>.
  • CSS on .landing-content .landing-hero h1: line-height: 1.1; text-wrap: auto; as the maintainer tried.

Three CSS values differ from the maintainer's test, and all three are needed to get his four lines at every width:

  • At 1440px with the old type size (4.6rem) the column beside the code panel is 540px wide, and "Safe, fast, and smart" needs about 600px, so "smart" wrapped to the next line (five lines: "Safe, fast, and / smart Python / frontend / engineered for / AI agents."). The h1 size is now clamp(2.7rem, 4.9vw, 4rem) (was clamp(2.9rem, 5.6vw, 4.6rem)), the largest size where the first line still fits. Please check the size in your browser; it is the one visible change beyond what was asked.
  • max-width: 10.5em replaces max-width: 15ch. Without a cap, a wide single column (601 to 720px, code panel hidden) fit "Python frontend engineered" on one line.
  • The phone rule is now clamp(2.4rem, 10vw, 3.6rem) (was clamp(2.6rem, 11vw, 3.6rem)) so the first line fits on a phone too.

Rendered lines measured in Chromium with a script that reads the line of every character (no horizontal overflow at any width):

Viewport width Lines
340 to 2560 px Safe, fast, and smart / Python frontend / engineered for / AI agents.
320 px Safe, fast, and / smart Python / frontend / engineered for / AI agents.

At 390px the headline is four lines with "AI agents." on the last one, and the lede and buttons follow directly. At 320px the first line cannot fit, so it wraps to five lines with "AI agents." still last.

2. Thumbnail on the YouTube box

<c-youtube-video> showed a blank dark rectangle until clicked. It now shows the video's picture behind the play button, and still loads nothing from YouTube or Google before the click.

  • New optional thumbnail argument: a path under /static/. Anything else (for example an i.ytimg.com URL) stops the docs build with an error that names the value, so a remote picture cannot be added by mistake. Without it, the box looks as before.
  • The picture is committed at docs_site/static/img/video-thumbnails/d3nPqvDdNB0.jpg (1280 by 720, 156 KB, from maxresdefault.jpg). The button keeps its play icon and its aria-label. The image has descriptive alt text because the docs alt_text check warns on an empty one (and build-check --strict runs in the release workflow).
  • CSS in site.css: the image fills the 16:9 box with object-fit: cover and a dark layer keeps the white play button and label readable. The new rules apply only to a box that holds a picture, because archived docs versions share this stylesheet. Measured: the box is the same size before and after a delayed image arrives (no layout shift), at 1440 and 390px.
  • docs_site/scripts/youtube_thumbnail.py <video id> downloads a thumbnail (falls back from maxresdefault.jpg to hqdefault.jpg on 404, rejects non-JPEG and cut-off answers, refuses to overwrite a file unless --replace). docs/codebase.md ("Add a video thumbnail") says how to refresh it when the video is re-recorded.
  • The same video appears on the docs home page and in the launch blog post, so both pass the same thumbnail.

Heads-up: the current picture is a frame of the recording that shows a "Stop the recording to save it" pop-up. It goes away when the video is re-recorded and the script is run for the new id.

Checks

  • Focused: docs_site/tests/test_youtube_video.py, test_youtube_thumbnail.py, test_landing_component.py (58 passed); ruff check and ruff format --check on docs_site pass.
  • New tests use synthetic input for the new argument and for the download script's fallback, rejection, and no-overwrite rules. No test pins landing page wording.
  • python -m docs_site build-check --strict: 0 errors, 0 warnings.
  • Browser (Playwright, Chromium), against the real built page: headline lines at 24 widths from 320 to 2560 px; no request to YouTube, Google, or ytimg before the click; the existing e2e tests for click-to-load, broken assets, and landing mount pass (3 passed).
  • python scripts/check.py --profile fast --reporter agent ran with a debug build of citry-core: every phase passed (cargo fmt, clippy, test; ruff; mypy; pyright; Node phases; validators; Vue render parity) except one test in the pytest phase: packages/py/citry/tests/test_i18n_format.py::test_the_python_bounds_match_what_the_formatter_accepts[1e-32768-True] (1 failed, 20125 passed). It fails with attempt to add with overflow inside the fixed_decimal crate, a check Rust compiles into debug builds only. This change touches no code under crates/ or packages/, so I expect CI, which builds a release wheel, to pass. I did not build a release to confirm.
  • Independent review (separate agents): an adversarial technical and security review, and two cold reads of the changed text. Fixed from them: the empty alt (strict build warning), the headline's phone and tablet wraps, the script's check for cut-off downloads, error messages, and several comments and doc passages. The security pass found no hole (the thumbnail value is author-only, and rendered attribute values are escaped).

Versioning

Docs site and README only. Nothing in crates/ or packages/ changes, so there is no 1.x behavior change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KUhrHajiCFnw2F7nAGf2Rh

The landing headline and the README title now read "Safe, fast, and
smart Python frontend engineered for AI agents." On the landing page the
last two words sit in a span that starts its own line, so the headline
renders as four lines ("Safe, fast, and smart / Python frontend /
engineered for / AI agents.") from 340px to wide desktops. The type
steps down so the first line fits beside the code panel, and a width cap
keeps a wide single column from merging lines.

The click-to-load YouTube box shows the video's thumbnail before the
click. The picture is a file this site serves (docs_site/static/img/
video-thumbnails/), so the page still loads nothing from YouTube or
Google before the click. A new `thumbnail` argument takes the path and
rejects anything outside /static/. docs_site/scripts/youtube_thumbnail.py
downloads a thumbnail for a video id, and docs/codebase.md says how to
refresh it when the video is re-recorded.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KUhrHajiCFnw2F7nAGf2Rh

This branch has not been deployed

No deployments
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.

1 participant