chore: merge the site mark and spacing fixes

docs_assets/extra.css

@@ -200,11 +200,12 @@
   background: #fff;
 }
 
-/* Headline figures, read as one line of numbers */
+/* Headline figures, read as one line of numbers: four fit on one row of
+   the text column. */
 .rb-stats {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(7rem, 1fr));
-  gap: 0.6rem 1.5rem;
+  gap: 0.6rem 1rem;
   margin: 1rem 0 1.5rem;
   padding: 0.8rem 1rem;
   border: 1px solid var(--rb-border);
@@ -277,6 +278,18 @@
   margin: 1rem 0;
 }
 
+/* A table lines up with the text around it. Material indents the table
+   by 0.8rem and offsets that with a negative margin on the wrapper, which
+   the margin above removes, and the table's own margin doubled the space
+   above it. */
+.md-typeset .md-typeset__table {
+  padding: 0;
+}
+
+.md-typeset .md-typeset__table > table {
+  margin: 0;
+}
+
 .rb-timestamp {
   font-size: 0.8rem;
   color: var(--rb-text-secondary);
@@ -343,10 +356,6 @@
 
 /* Key and value cards: the header row is empty, so it is not drawn and
    not announced. */
-.rb-meta-card table {
-  margin: 1rem 0 !important;
-}
-
 .rb-meta-card thead,
 .md-typeset table thead:not(:has(th:not(:empty))) {
   display: none;
@@ -410,6 +419,24 @@
   min-height: 44px;
 }
 
+/* Buttons that wrap onto a second line keep a gap between the rows. */
+.md-typeset .md-button {
+  margin-block: 0.25rem;
+}
+
+/* The copy button stays inside a one-line code block: at 44 px it hung
+   below the block and covered the end of the line. 24 px is the minimum
+   target size of WCAG 2.2. */
+.md-typeset .md-code__button {
+  min-height: 0;
+  width: 24px;
+  height: 24px;
+}
+
+.md-typeset pre > code {
+  padding-right: 2.6rem;
+}
+
 .rb-visually-hidden {
   position: absolute !important;
   width: 1px !important;
@@ -760,13 +787,21 @@
   }
 }
 
-/* The sidebar title stays legible over the list scrolling under it. */
+/* The sidebar title stays legible over the list scrolling under it. With
+   tabs the title shown is the active section's label, held at the top of
+   the sidebar: a rule under it ends the list cleanly instead of a half
+   line of text touching the label. */
 @media (min-width: 76.25em) {
   .md-nav--primary > .md-nav__title,
-  .md-nav--secondary > .md-nav__title {
+  .md-nav--secondary > .md-nav__title,
+  .md-nav--lifted > .md-nav__list > .md-nav__item--active > .md-nav__link {
     background: var(--md-default-bg-color);
     border-bottom: 1px solid var(--rb-border);
   }
+
+  .md-nav--lifted > .md-nav__list > .md-nav__item--active > .md-nav__link {
+    padding-bottom: 0.4rem;
+  }
 }
 
 /* Material's compact footer defaults sit just below WCAG AA on the dark bar. */
@@ -853,8 +888,15 @@
   .md-typeset table:not([class]):not([data-rb-stack]) :is(td, th):first-child {
     position: sticky;
     left: 0;
+    min-width: min(6rem, 30vw);
     max-width: 40vw;
     background: var(--md-default-bg-color);
+    overflow-wrap: break-word;
+  }
+
+  /* A long link or path breaks anywhere, so it never squeezes the first
+     column down to one letter per line. */
+  .md-typeset table:not([class]):not([data-rb-stack]) td:not(:first-child) :is(a, code) {
     overflow-wrap: anywhere;
   }
 
@@ -868,7 +910,6 @@
   .md-typeset pre > code {
     white-space: pre-wrap;
     overflow-wrap: anywhere;
-    padding-right: 2.6rem;
   }
 
   .md-typeset :is(.rb-terminal, .language-text) pre > code {

docs_assets/overrides/assets/brand/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><style>.c{fill:#3b3f7a}@media (prefers-color-scheme: dark){.c{fill:#8a8fd6}}</style><rect x="11.8" y="2.5" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="11.8" y="40" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="2.5" y="11.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="40" y="11.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="18.8" y="2.5" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="18.8" y="40" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="2.5" y="18.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="40" y="18.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="25.8" y="2.5" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="25.8" y="40" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="2.5" y="25.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="40" y="25.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="32.8" y="2.5" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="32.8" y="40" width="3.4" height="5.5" rx="0.8" class="c"/><rect x="2.5" y="32.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="40" y="32.8" width="5.5" height="3.4" rx="0.8" class="c"/><rect x="8" y="8" width="32" height="32" rx="4" class="c"/><rect x="11.6" y="11.6" width="5" height="5" rx="0.6" fill="#8be0f7"/><rect x="18.2" y="11.6" width="5" height="5" rx="0.6" fill="#8be0f7"/><rect x="24.8" y="11.6" width="5" height="5" rx="0.6" fill="#4fa3c4"/><rect x="18.2" y="18.2" width="5" height="5" rx="0.6" fill="#8be0f7"/><rect x="31.4" y="18.2" width="5" height="5" rx="0.6" fill="#4fa3c4"/><rect x="11.6" y="24.8" width="5" height="5" rx="0.6" fill="#8be0f7"/><rect x="31.4" y="24.8" width="5" height="5" rx="0.6" fill="#8be0f7"/><rect x="18.2" y="31.4" width="5" height="5" rx="0.6" fill="#4fa3c4"/><rect x="24.8" y="31.4" width="5" height="5" rx="0.6" fill="#8be0f7"/><rect x="31.4" y="31.4" width="5" height="5" rx="0.6" fill="#8be0f7"/></svg>

docs_assets/overrides/assets/brand/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" role="img" aria-label="RetroBIOS"><mask id="glyph"><rect x="8" y="8" width="32" height="32" rx="4" fill="#fff"/><rect x="11.6" y="11.6" width="5" height="5" rx="0.6" fill="#000"/><rect x="18.2" y="11.6" width="5" height="5" rx="0.6" fill="#000"/><rect x="24.8" y="11.6" width="5" height="5" rx="0.6" fill="#5a5a5a"/><rect x="18.2" y="18.2" width="5" height="5" rx="0.6" fill="#000"/><rect x="31.4" y="18.2" width="5" height="5" rx="0.6" fill="#5a5a5a"/><rect x="11.6" y="24.8" width="5" height="5" rx="0.6" fill="#000"/><rect x="31.4" y="24.8" width="5" height="5" rx="0.6" fill="#000"/><rect x="18.2" y="31.4" width="5" height="5" rx="0.6" fill="#5a5a5a"/><rect x="24.8" y="31.4" width="5" height="5" rx="0.6" fill="#000"/><rect x="31.4" y="31.4" width="5" height="5" rx="0.6" fill="#000"/></mask><rect x="11.8" y="2.5" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="11.8" y="40" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="2.5" y="11.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="40" y="11.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="18.8" y="2.5" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="18.8" y="40" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="2.5" y="18.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="40" y="18.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="25.8" y="2.5" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="25.8" y="40" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="2.5" y="25.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="40" y="25.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="32.8" y="2.5" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="32.8" y="40" width="3.4" height="5.5" rx="0.8" fill="#fff"/><rect x="2.5" y="32.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="40" y="32.8" width="5.5" height="3.4" rx="0.8" fill="#fff"/><rect x="8" y="8" width="32" height="32" rx="4" fill="#fff" mask="url(#glyph)"/></svg>

docs_assets/overrides/main.html

@@ -29,6 +29,12 @@
   {% else %}{% set section = 'reference' %}{% endif %}
   {% set preview_image = config.site_url ~ 'assets/og/' ~ section ~ '.png' if config.site_url else '' %}
 
+  {# The theme's favicon is the 32 px PNG. Browsers that read an SVG icon
+     take this one, listed after it, and a home-screen shortcut takes the
+     opaque 180 px icon (scripts/make_site_icons.py makes all three). #}
+  <link rel="icon" type="image/svg+xml" href="{{ 'assets/brand/favicon.svg' | url }}">
+  <link rel="apple-touch-icon" sizes="180x180" href="{{ 'assets/brand/apple-touch-icon.png' | url }}">
+
   <meta property="og:type" content="{{ 'website' if not url else 'article' }}">
   <meta property="og:site_name" content="{{ config.site_name }}">
   <meta property="og:title" content="{{ page_title }}">

mkdocs.yml

@@ -39,8 +39,8 @@ theme:
       icon: material/brightness-4
       name: Switch to auto
   font: false
-  logo: assets/images/logo.png
-  favicon: assets/images/favicon.png
+  logo: assets/brand/logo.svg
+  favicon: assets/brand/favicon-32.png
   icon:
     logo: material/chip
   features:

scripts/generate_site.py

@@ -6194,8 +6194,8 @@ theme:
       icon: material/brightness-4
       name: Switch to auto
   font: false
-  logo: assets/images/logo.png
-  favicon: assets/images/favicon.png
+  logo: assets/brand/logo.svg
+  favicon: assets/brand/favicon-32.png
   icon:
     logo: material/chip
   features:

scripts/make_site_icons.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Write the site's own mark: header logo, favicon and touch icon.
+
+The mark is the chip of the project logo drawn as vector shapes: a body,
+four pins per side and the pixel glyph on a 4 by 4 grid. Three variants:
+
+- ``logo.svg``: white, the glyph cut out so the header colour shows through.
+  It sits on the indigo header in both schemes.
+- ``favicon.svg``: indigo chip with a cyan glyph, lighter in a dark browser.
+- ``favicon-32.png`` and ``apple-touch-icon.png`` (180 px, opaque): the same
+  shapes rasterised by a headless Chromium through Playwright, for browsers
+  that take no SVG icon and for home-screen shortcuts.
+
+The files land in ``docs_assets/overrides/assets/brand/``, which MkDocs copies
+with the theme. The site build never runs this script.
+
+    python scripts/make_site_icons.py
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT = ROOT / "docs_assets" / "overrides" / "assets" / "brand"
+
+HEADER = "#3b3f7a"
+GLYPH = "#8be0f7"
+GLYPH_DIM = "#4fa3c4"
+
+# (column, row, dim) on the 4 by 4 grid, read from the project logo.
+PIXELS = [
+    (0, 0, False), (1, 0, False), (2, 0, True),
+    (1, 1, False), (3, 1, True),
+    (0, 2, False), (3, 2, False),
+    (1, 3, True), (2, 3, False), (3, 3, False),
+]
+
+BODY = (8, 8, 32, 4)  # x, y, size, corner radius in a 48 unit box
+PIN_CENTRES = (13.5, 20.5, 27.5, 34.5)
+PIN_WIDTH = 3.4
+PIN_LENGTH = 5.5
+CELL = 5.0
+GAP = 1.6
+
+
+def _pins(fill: str) -> str:
+    half = PIN_WIDTH / 2
+    rects = []
+    for centre in PIN_CENTRES:
+        start = centre - half
+        rects += [
+            (start, 8 - PIN_LENGTH, PIN_WIDTH, PIN_LENGTH),
+            (start, 40, PIN_WIDTH, PIN_LENGTH),
+            (8 - PIN_LENGTH, start, PIN_LENGTH, PIN_WIDTH),
+            (40, start, PIN_LENGTH, PIN_WIDTH),
+        ]
+    return "".join(
+        f'<rect x="{x:g}" y="{y:g}" width="{w:g}" height="{h:g}" rx="0.8" fill="{fill}"/>'
+        for x, y, w, h in rects
+    )
+
+
+def _glyph(bright: str, dim: str) -> str:
+    span = 4 * CELL + 3 * GAP
+    origin = BODY[0] + (BODY[2] - span) / 2
+    return "".join(
+        f'<rect x="{origin + c * (CELL + GAP):g}" y="{origin + r * (CELL + GAP):g}" '
+        f'width="{CELL:g}" height="{CELL:g}" rx="0.6" fill="{dim if is_dim else bright}"/>'
+        for c, r, is_dim in PIXELS
+    )
+
+
+def _body(fill: str, extra: str = "") -> str:
+    x, y, size, radius = BODY
+    return f'<rect x="{x}" y="{y}" width="{size}" height="{size}" rx="{radius}" fill="{fill}"{extra}/>'
+
+
+def logo_svg() -> str:
+    """White chip, glyph cut out: the header colour shows through it."""
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" role="img" aria-label="RetroBIOS">'
+        '<mask id="glyph">' + _body("#fff") + _glyph("#000", "#5a5a5a") + "</mask>"
+        + _pins("#fff") + _body("#fff", ' mask="url(#glyph)"') + "</svg>"
+    )
+
+
+def favicon_svg() -> str:
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">'
+        "<style>.c{fill:" + HEADER + "}"
+        "@media (prefers-color-scheme: dark){.c{fill:#8a8fd6}}</style>"
+        + _pins(HEADER).replace(f'fill="{HEADER}"', 'class="c"')
+        + _body(HEADER).replace(f'fill="{HEADER}"', 'class="c"')
+        + _glyph(GLYPH, GLYPH_DIM) + "</svg>"
+    )
+
+
+def touch_icon_svg() -> str:
+    """Opaque square: iOS fills transparency with black."""
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="-6 -6 60 60">'
+        f'<rect x="-6" y="-6" width="60" height="60" fill="{HEADER}"/>'
+        + logo_svg().split(">", 1)[1].rsplit("</svg>", 1)[0] + "</svg>"
+    )
+
+
+def main() -> None:
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:
+        raise SystemExit("Playwright with Chromium is needed: pip install playwright") from exc
+    OUT.mkdir(parents=True, exist_ok=True)
+    for name, text in (("logo.svg", logo_svg()), ("favicon.svg", favicon_svg())):
+        (OUT / name).write_text(text + "\n", encoding="utf-8")
+        print((OUT / name).relative_to(ROOT))
+    rasters = (
+        ("favicon-32.png", 32, favicon_svg().replace("@media (prefers-color-scheme: dark)", "@media not all")),
+        ("apple-touch-icon.png", 180, touch_icon_svg()),
+    )
+    with sync_playwright() as playwright:
+        browser = playwright.chromium.launch()
+        for name, size, text in rasters:
+            page = browser.new_page(viewport={"width": size, "height": size})
+            sized = text.replace("<svg ", f'<svg width="{size}" height="{size}" ', 1)
+            page.set_content(f'<html><body style="margin:0;background:transparent">{sized}</body></html>')
+            page.screenshot(path=str(OUT / name), omit_background=True, clip={"x": 0, "y": 0, "width": size, "height": size})
+            page.close()
+            print((OUT / name).relative_to(ROOT))
+        browser.close()
+
+
+if __name__ == "__main__":
+    main()