Public: anyone can read this; the crew can change it.

Code and docs read cleanly: a commit's id is seven characters, a wrapped list item stays one item #14314

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The owner saw hashes take too much room while reading docs in the code viewer. Signed-out screenshots of the live forge at 1440, 1024 and 390 px, plus dark mode, showed two real problems: 1. A commit's full id as the ref.

Notes

shipped production is serving it deploy 08ee03a

opened this

The owner saw hashes take too much room while reading docs in the code viewer. Signed-out screenshots of the live forge at 1440, 1024 and 390 px, plus dark mode, showed two real problems:

1. A commit's full id as the ref. Opening a commit and pressing Browse files lands on /tree/<40-hex>. The ref switcher showed 582ef43ee6d5b31b41…, and on a phone the "Files" handle printed all 40 characters, squeezing Files to one letter per line. Both now show 582ef43 with the full id in title (refText in src/web/pages/refs.ts). The id also stays in every link. A long branch name now truncates in the handle instead of crowding it.

2. Wrapped list items split. src/web/markdown.ts closed a list item at the end of its first line. Every wrapped bullet came out as a one-line bullet followed by a stray paragraph outside the list. This hit most of docs/ (for example the "Shape" section of MCP.md, on blob pages and on /docs/*). A list item now keeps:

  • indented continuation lines, and unindented ones with no blank line before them (CommonMark lazy continuation)
  • nested lists, and a later paragraph of its own
  • an indented fence, with the indent stripped from the code

A blank line between items keeps one list, and an ordered list keeps its starting number (<ol start>). Plain lists render byte-for-byte as before. All 735 .md files in the repo render with balanced list, item and paragraph tags.

Checked with no change needed: no page scrolls sideways at 390 px. Code, tables and diffs scroll inside their own boxes, and short hashes on the commit list and commit page were already 7 characters.

Tests: new test/code-viewer-reading.test.ts covers refText, the switcher, the list cases, a tag-balance check, the served tree and blob pages at a commit id (no full id in the text), and a Chromium measurement at 390 px (Files stays on one line, no sideways scroll). Three tests that pinned the old markup were updated, and a nested task item now counts as a task.

Not fixed, noted: the /docs index is 15013 B against a 14848 B test budget (test/docs-link.test.ts). That test already fails on main without this change. In rendered markdown, heading underlines are wider than the text because --measure is in ch and each heading has its own font size.

🤖 Generated with Claude Code

commented

<!-- look-pages 278a2784b1ba --> Look pages for 278a278, from the gate:

  • look pages (inferred): this pull changes src/web/markdown.ts, src/web/pages/explorer.ts, src/web/pages/refs.ts and 1 more; the forge pictures / (src/web/markdown.ts), /docs (src/web/markdown.ts), /explore (src/web/markdown.ts) and 25 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs