docs: publish the themed HTML manual to copperline.dev/docs on release

.github/workflows/docs-site.yml

@@ -0,0 +1,67 @@
+name: Docs site HTML
+
+# Builds the HTML manual with MyST and publishes it to the copperline.dev
+# website repository (LinuxJedi/copperline.github.io) under /docs when a v*
+# tag is pushed, so the docs on the site always match the latest release.
+# The HTML build itself is checked on every push/PR by the docs job in
+# ci.yml; this workflow only handles publication. A workflow_dispatch
+# trigger allows re-publishing from whatever ref it is run on (e.g. after a
+# docs hotfix on main) without cutting a release.
+#
+# Pushing to the website repository needs the SITE_DEPLOY_KEY secret: the
+# private half of an SSH deploy key whose public half is installed with
+# write access on LinuxJedi/copperline.github.io.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+concurrency:
+  group: docs-site-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    name: Build and publish HTML docs
+    # No Typst/PDF here, so plain ubuntu is enough (unlike docs-release.yml).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Install MyST CLI
+        run: npm install -g mystmd
+      - name: Build HTML
+        working-directory: docs
+        env:
+          # The docs live under copperline.dev/docs, not at the site root;
+          # MyST prepends this to every internal link and asset URL.
+          BASE_URL: /docs
+        run: |
+          myst build --html --ci --strict
+          test -s _build/html/index.html
+      - name: Check out the website repository
+        uses: actions/checkout@v4
+        with:
+          repository: LinuxJedi/copperline.github.io
+          ssh-key: ${{ secrets.SITE_DEPLOY_KEY }}
+          path: site
+      - name: Replace /docs with the new build
+        # A full replace (not an overlay) so pages and hashed assets deleted
+        # upstream do not linger on the site.
+        run: |
+          rm -rf site/docs
+          cp -r docs/_build/html site/docs
+      - name: Commit and push
+        working-directory: site
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A docs
+          if git diff --cached --quiet; then
+            echo "Docs are unchanged; nothing to publish."
+            exit 0
+          fi
+          git commit -m "Publish docs for ${{ github.ref_name }}"
+          git push

docs/README.md

@@ -30,6 +30,14 @@ myst build --html        # static site in docs/_build/html
 myst start               # or: live-reloading local preview server
 ```
 
+The HTML site is themed to match copperline.dev via `site.css` (wired up
+through the `style` option in `myst.yml`). On every `v*` tag the
+`docs-site.yml` workflow rebuilds it with `BASE_URL=/docs` and publishes it
+to the website repository, where it is served at
+[copperline.dev/docs](https://copperline.dev/docs). The `@font-face` rules
+in `site.css` point at fonts hosted by the website, so local previews fall
+back to system fonts; everything else looks the same.
+
 ## PDF
 
 ```sh

docs/myst.yml

@@ -70,3 +70,10 @@ site:
   options:
     favicon: ../assets/brand/copperline.ico
     hide_authors: true
+    logo: ../assets/brand/copperline-logo.png
+    logo_alt: Copperline
+    # The logo links back to the main site; the sidebar TOC covers the
+    # docs themselves.
+    logo_url: https://copperline.dev/
+    # Restyles the HTML site build to match copperline.dev; see site.css.
+    style: site.css

docs/site.css

@@ -0,0 +1,177 @@
+/* Copperline theme for the MyST book-theme HTML export, applied via the
+   `style` option in myst.yml. It restyles the docs to match copperline.dev
+   (palette, fonts, copper hairline) without replacing the theme, so it only
+   affects the HTML site build, not the PDF export.
+
+   The @font-face sources point at the font files self-hosted by the website
+   repository; they resolve when the docs are served from copperline.dev/docs.
+   Anywhere else (myst start, CI preview) the fallback system fonts apply. */
+
+@font-face {
+  font-family: "Chakra Petch";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("/assets/fonts/chakra-petch-500.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Chakra Petch";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url("/assets/fonts/chakra-petch-600.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Chakra Petch";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("/assets/fonts/chakra-petch-700.woff2") format("woff2");
+}
+@font-face {
+  font-family: "IBM Plex Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("/assets/fonts/ibm-plex-mono-400.woff2") format("woff2");
+}
+@font-face {
+  font-family: "IBM Plex Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("/assets/fonts/ibm-plex-mono-500.woff2") format("woff2");
+}
+@font-face {
+  font-family: "IBM Plex Mono";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url("/assets/fonts/ibm-plex-mono-600.woff2") format("woff2");
+}
+@font-face {
+  font-family: "IBM Plex Sans";
+  font-style: normal;
+  font-weight: 100 700;
+  font-display: swap;
+  src: url("/assets/fonts/ibm-plex-sans-var.woff2") format("woff2");
+}
+
+:root {
+  /* Palette lifted from copperline.dev's style.css. */
+  --cl-bg: #080b13;
+  --cl-surface: #11151f;
+  --cl-surface-2: #161b29;
+  --cl-line: #232a3d;
+  --cl-ink: #eef1f8;
+  --cl-ink-soft: #b9c1d4;
+  --cl-copper: #e89154;
+  --cl-copper-hi: #f7b878;
+  --cl-copper-dp: #b9622c;
+  --cl-blue: #54a6ff;
+  --cl-blue-dp: #2e6dc4;
+}
+
+/* Typography: same three families as the website. ------------------------ */
+
+body {
+  font-family: "IBM Plex Sans", system-ui, sans-serif;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: "Chakra Petch", "IBM Plex Sans", sans-serif;
+  letter-spacing: 0.01em;
+}
+
+code, kbd, pre, samp {
+  font-family: "IBM Plex Mono", ui-monospace, "SF Mono", monospace;
+}
+
+/* Copper hairline under the sticky top nav - the site's signature motif. - */
+
+.myst-top-nav {
+  position: sticky;
+}
+
+.myst-top-nav::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 2px;
+  background: linear-gradient(
+    90deg,
+    var(--cl-copper-dp),
+    var(--cl-copper-hi),
+    var(--cl-blue)
+  );
+}
+
+/* Links: chrome blue, copper on hover, in both color schemes. ------------ */
+/* !important is needed to beat the theme's Tailwind utility classes. */
+
+article a,
+.myst-toc a {
+  color: var(--cl-blue-dp) !important;
+}
+
+html.dark article a,
+html.dark .myst-toc a {
+  color: var(--cl-blue) !important;
+}
+
+article a:hover,
+.myst-toc a:hover,
+html.dark article a:hover,
+html.dark .myst-toc a:hover {
+  color: var(--cl-copper-hi) !important;
+}
+
+/* Inline code: copper, as on the website. Fenced blocks keep the theme's
+   syntax highlighting. */
+
+article code:not(pre code) {
+  color: var(--cl-copper-dp) !important;
+}
+
+html.dark article code:not(pre code) {
+  color: var(--cl-copper-hi) !important;
+}
+
+/* Keyboard keys: little machined keycaps, as used heavily in the guide. -- */
+
+kbd {
+  padding: 0.1em 0.5em;
+  font-size: 0.85em;
+  border: 1px solid #c2c9d6;
+  border-bottom-width: 2px;
+  border-radius: 5px;
+  background: #f4f6fa;
+}
+
+html.dark kbd {
+  color: var(--cl-ink-soft);
+  border-color: var(--cl-line);
+  background: var(--cl-surface-2);
+}
+
+/* Dark scheme surfaces: deep blue-black instead of the theme's stone. ---- */
+
+html.dark,
+html.dark body {
+  background-color: var(--cl-bg) !important;
+}
+
+html.dark body {
+  color: var(--cl-ink);
+}
+
+html.dark .myst-top-nav {
+  background-color: rgba(8, 11, 19, 0.85) !important;
+}
+
+html.dark pre {
+  background-color: var(--cl-surface) !important;
+  border: 1px solid var(--cl-line);
+}