Skip to content

Commit 660ee38

Browse files
jdaltonjdalton
committed
fix(docs): readable doc pages — width, padding, contrast, syntax highlighting
Doc pages (tour.html, vers.html, hardening.md, …) were flush-left, pure-white-on-near-black, code indistinguishable from prose — "torture to read" per feedback. Rendering changes (scripts/tour.mts renderDocs): - Load highlight.js's github.min.css + github-dark.min.css with prefers-color-scheme media queries so syntax highlighting adapts to the user's OS theme in both light and dark modes. - Add highlight.js script + an inline init that walks every <pre><code> and calls hljs.highlightElement. Both get SRI hashes auto-injected by the existing injectSri pass; the CSP pipeline hashes the inline script. Style changes (walkthrough-overrides.css): - .doc-body: 72ch max-width centered column, 32px top padding, 64px bottom — newspaper reading rhythm. Body text drops from pure white to var(--prose-text), the GitHub-tuned off-white that still passes contrast without burning retinas. - Headings: h1/h2 get a thin bottom rule; h3 overrides the all-caps treatment inherited from annotation-cards so doc h3s render as normal prose headings. - Links: muted underline that thickens on hover — no naked blue. - Inline <code>: monospace + subtle chip background so code reads as code inline without color-jumping. - Fenced <pre><code>: container has its own padding, border, horizontal scroll. highlight.js paints tokens over the top once the page loads. - Blockquotes, tables, lists, hr: all styled to match the same off-white contrast band.
1 parent f5a7445 commit 660ee38

2 files changed

Lines changed: 155 additions & 1 deletion

File tree

‎scripts/tour.mts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,12 @@ async function renderDocs(
247247
` <meta name="viewport" content="width=device-width, initial-scale=1" />\n` +
248248
` <title>${escapeHtml(doc.title)} — Socket PackageURL.js</title>\n` +
249249
` <link rel="stylesheet" href="/walkthrough.css" />\n` +
250-
` <link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.10.0/styles/github-dark.min.css" />\n` +
250+
// Theme-adaptive syntax highlighting. Media queries gate which
251+
// highlight.js theme the browser actually applies based on the
252+
// user's OS preference; both stylesheets download, the
253+
// non-matching one just yields zero matched rules.
254+
` <link rel="stylesheet" media="(prefers-color-scheme: light)" href="https://unpkg.com/@highlightjs/cdn-assets@11.10.0/styles/github.min.css" />\n` +
255+
` <link rel="stylesheet" media="(prefers-color-scheme: dark)" href="https://unpkg.com/@highlightjs/cdn-assets@11.10.0/styles/github-dark.min.css" />\n` +
251256
`</head>\n` +
252257
`<body data-slug="${escapeHtml(slug)}" data-doc="${escapeHtml(doc.filename)}">\n` +
253258
` <header class="topbar">\n` +
@@ -262,6 +267,11 @@ async function renderDocs(
262267
` <main class="doc-body">\n` +
263268
`${body}\n` +
264269
` </main>\n` +
270+
// highlight.js — loaded at the bottom so code blocks are in the
271+
// DOM by the time it runs. The SRI + CSP pipeline pass hashes
272+
// both the <script src> tag and the inline init block later.
273+
` <script src="https://unpkg.com/@highlightjs/cdn-assets@11.10.0/highlight.min.js"></script>\n` +
274+
` <script>document.querySelectorAll('pre code').forEach(b => window.hljs && window.hljs.highlightElement(b))</script>\n` +
265275
`</body>\n` +
266276
`</html>\n`
267277
await fs.writeFile(path.join(tourDir, `${doc.filename}.html`), html)

‎walkthrough-overrides.css‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -364,6 +364,150 @@ html[data-theme='dark'] .file-grid > .code-section:hover {
364364
margin-left: 2px;
365365
}
366366

367+
/* ─── Topic doc pages ───────────────────────────────────────────
368+
* Pages rendered from docs/*.md into <main class="doc-body">. The
369+
* meander parts pages have a two-column layout with their own
370+
* spacing rules; these docs are single-column prose and need
371+
* newspaper-style centered reading width, muted body text, and
372+
* syntax-highlighted code blocks to stop being "torture to read."
373+
*/
374+
.doc-body {
375+
/* Centered reading column — ~72 chars at this font size keeps
376+
* eyes from shuttling too far across a wide monitor. Scale the
377+
* side padding on mobile so small screens don't hit the edges. */
378+
max-width: 72ch;
379+
margin: 0 auto;
380+
padding: 32px 24px 64px;
381+
/* Tone down body from pure white. --prose-text is a GitHub-tuned
382+
* off-white (#e6edf3) in dark, #1f2328 in light — both land in
383+
* the "readable, not aggressive" band. */
384+
color: var(--prose-text);
385+
font-size: 16px;
386+
line-height: 1.65;
387+
}
388+
.doc-body h1,
389+
.doc-body h2,
390+
.doc-body h3,
391+
.doc-body h4,
392+
.doc-body h5,
393+
.doc-body h6 {
394+
color: var(--prose-text);
395+
line-height: 1.25;
396+
margin: 2em 0 0.6em;
397+
}
398+
.doc-body h1 {
399+
font-size: 30px;
400+
margin-top: 0;
401+
border-bottom: 1px solid var(--rule);
402+
padding-bottom: 0.3em;
403+
}
404+
.doc-body h2 {
405+
font-size: 22px;
406+
border-bottom: 1px solid var(--rule);
407+
padding-bottom: 0.2em;
408+
}
409+
.doc-body h3 {
410+
font-size: 18px;
411+
/* Override the all-caps 11px treatment the page also applies to
412+
* <h3> inside annotation cards; doc-body h3s are normal headings. */
413+
text-transform: none !important;
414+
letter-spacing: 0 !important;
415+
font-weight: 600 !important;
416+
color: var(--prose-text) !important;
417+
font-size: 18px !important;
418+
margin: 2em 0 0.6em !important;
419+
}
420+
.doc-body h4 {
421+
font-size: 16px;
422+
font-weight: 600;
423+
}
424+
.doc-body p,
425+
.doc-body li {
426+
color: var(--prose-text);
427+
}
428+
.doc-body a {
429+
color: var(--accent);
430+
text-decoration: none;
431+
border-bottom: 1px solid color-mix(in srgb, var(--accent) 35%, transparent);
432+
transition: border-color var(--transition-fast);
433+
}
434+
.doc-body a:hover {
435+
border-bottom-color: var(--accent);
436+
}
437+
.doc-body ul,
438+
.doc-body ol {
439+
padding-left: 1.5em;
440+
}
441+
.doc-body li {
442+
margin: 0.25em 0;
443+
}
444+
.doc-body blockquote {
445+
margin: 1em 0;
446+
padding: 0.4em 1em;
447+
border-left: 3px solid color-mix(in srgb, var(--accent) 50%, transparent);
448+
color: var(--eyebrow);
449+
background: color-mix(in srgb, var(--accent) 4%, transparent);
450+
border-radius: 0 4px 4px 0;
451+
}
452+
.doc-body table {
453+
border-collapse: collapse;
454+
margin: 1em 0;
455+
display: block;
456+
overflow-x: auto;
457+
font-size: 14px;
458+
}
459+
.doc-body th,
460+
.doc-body td {
461+
border: 1px solid var(--rule);
462+
padding: 6px 10px;
463+
text-align: left;
464+
}
465+
.doc-body th {
466+
background: color-mix(in srgb, var(--accent) 6%, var(--page-bg));
467+
font-weight: 600;
468+
}
469+
470+
/* Inline code — subtle chip background + monospace, so it visually
471+
* separates from surrounding prose without being a different color
472+
* than the code-block text it shares glyphs with. */
473+
.doc-body :not(pre) > code {
474+
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
475+
font-size: 0.88em;
476+
background: color-mix(in srgb, var(--rule) 35%, transparent);
477+
padding: 1px 5px;
478+
border-radius: 4px;
479+
color: inherit;
480+
border: 1px solid color-mix(in srgb, var(--rule) 50%, transparent);
481+
}
482+
483+
/* Fenced code blocks. highlight.js paints tokens once
484+
* <script>hljs.highlightElement(block)</script> runs; the container
485+
* owns the padding, border, scroll behavior. */
486+
.doc-body pre {
487+
margin: 1em 0;
488+
padding: 14px 16px;
489+
background: var(--code-bg);
490+
border: 1px solid var(--rule);
491+
border-radius: 6px;
492+
overflow-x: auto;
493+
line-height: 1.5;
494+
}
495+
.doc-body pre > code {
496+
background: none;
497+
border: 0;
498+
padding: 0;
499+
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
500+
font-size: 13.5px;
501+
color: inherit;
502+
/* highlight.js's theme CSS sets foreground token colors; let it
503+
* win over the doc-body prose color. */
504+
}
505+
.doc-body hr {
506+
margin: 2em 0;
507+
border: 0;
508+
border-top: 1px solid var(--rule);
509+
}
510+
367511
/* The first annotation inside each file-block is almost always file
368512
* boilerplate — license header, @fileoverview, etc. Render it in a
369513
* muted, italic tone so it reads as framing rather than body content. */

0 commit comments

Comments
 (0)