diff --git a/.github/workflows/page.yml b/.github/workflows/page.yml index 40a8be3..7793f17 100644 --- a/.github/workflows/page.yml +++ b/.github/workflows/page.yml @@ -35,10 +35,22 @@ jobs: with: persist-credentials: false - name: Install pandoc - run: sudo apt-get update && sudo apt-get install -y pandoc + env: + # Pinned: Ubuntu's apt pandoc predates the gfm `alerts` extension, + # so > [!NOTE] callouts would ship as literal text. + PANDOC_VERSION: "3.12.1" + run: | + curl -fsSL -o /tmp/pandoc.tar.gz \ + "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux-amd64.tar.gz" + sudo tar -xzf /tmp/pandoc.tar.gz -C /usr/local --strip-components=1 + pandoc --version - uses: actions/setup-python@v5 - name: Install uv - uses: astral-sh/setup-uv@v6 + # Pinned to hash (blanket policy); bump comment when updating + uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0 + with: + # Publish workflow: never read from the Actions cache + enable-cache: false - name: Make docs run: make web - uses: actions/configure-pages@v5 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 794fbb9..93866c9 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -7,8 +7,14 @@ on: workflow_dispatch: # Called by release-please: tags/releases made with GITHUB_TOKEN - # do not trigger push/release events (recursive trigger guard) + # do not trigger push/release events (recursive trigger guard), + # so the tag name must be passed in as an input. workflow_call: + inputs: + tag: + description: Tag created by release-please + type: string + required: false permissions: contents: write @@ -21,9 +27,19 @@ jobs: with: persist-credentials: false - name: Install pandoc + env: + # Pinned: Ubuntu's apt pandoc predates the gfm `alerts` extension, + # so > [!NOTE] callouts would ship as literal text. + PANDOC_VERSION: "3.12.1" + run: | + curl -fsSL -o /tmp/pandoc.tar.gz \ + "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux-amd64.tar.gz" + sudo tar -xzf /tmp/pandoc.tar.gz -C /usr/local --strip-components=1 + pandoc --version + - name: Install LaTeX run: | sudo apt-get update - sudo apt-get install -y pandoc texlive texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended librsvg2-bin + sudo apt-get install -y texlive texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended librsvg2-bin - name: Make docs run: make pdf markdown - name: Release MD and PDF @@ -31,3 +47,6 @@ jobs: with: working_directory: dist body_path: CHANGELOG.md + # workflow_call has no tag ref (runs on main), so use the + # release-please input; direct tag pushes use github.ref_name. + tag_name: ${{ inputs.tag || startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }} diff --git a/.github/workflows/readme.yml b/.github/workflows/readme.yml index a1e0da4..c78ba35 100644 --- a/.github/workflows/readme.yml +++ b/.github/workflows/readme.yml @@ -24,11 +24,26 @@ jobs: ref: ${{ github.event.repository.default_branch }} persist-credentials: false - name: Install pandoc + env: + # Pinned: Ubuntu's apt pandoc predates the gfm `alerts` extension, + # so > [!NOTE] callouts would ship as literal text. + PANDOC_VERSION: "3.12.1" run: | - sudo apt-get update - sudo apt-get install -y pandoc + curl -fsSL -o /tmp/pandoc.tar.gz \ + "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux-amd64.tar.gz" + sudo tar -xzf /tmp/pandoc.tar.gz -C /usr/local --strip-components=1 + pandoc --version - name: Generate README.md run: make readme + - name: Configure push credentials + # add-and-commit pushes with plain git, and its github_token input is + # API-only, so restore the auth header that checkout omits when + # persist-credentials is false. + env: + GH_TOKEN: ${{ github.token }} + run: | + git config --local http.https://github.com/.extraheader \ + "AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')" - name: Commit README.md uses: EndBug/add-and-commit@v11 with: diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 6c81102..b998924 100644 --- a/.github/workflows/release-please.yml +++ b/.github/workflows/release-please.yml @@ -15,6 +15,7 @@ jobs: pull-requests: write outputs: release_created: ${{ steps.release.outputs.release_created }} + tag_name: ${{ steps.release.outputs.tag_name }} steps: - id: release uses: googleapis/release-please-action@v5 @@ -30,6 +31,8 @@ jobs: needs: release-please if: needs.release-please.outputs.release_created == 'true' uses: $/.github/workflows/publish.yml + with: + tag: ${{ needs.release-please.outputs.tag_name }} permissions: contents: write diff --git a/src/template/md.tex b/src/template/md.tex index 667c605..fc20ad9 100644 --- a/src/template/md.tex +++ b/src/template/md.tex @@ -1,4 +1,9 @@ +

+ PDF Version +Web Version +

+

$if(titlepage-logo)$ $title$ diff --git a/src/template/readme_md.tex b/src/template/readme_md.tex index 63980bc..81d9f86 100644 --- a/src/template/readme_md.tex +++ b/src/template/readme_md.tex @@ -1,7 +1,9 @@

- Get the PDF version of this documentation! Download manual.pdf + PDF Version +Web Version

+

$if(titlepage-logo)$ $title$ diff --git a/src/template/web/index.html b/src/template/web/index.html index fb3153b..b632b32 100644 --- a/src/template/web/index.html +++ b/src/template/web/index.html @@ -32,7 +32,7 @@ -

+
button[popovertarget] { - display: inline-flex; - } +/* Keep the contents hamburger visible below 64rem. Yeti shows it from its nav + base rules, but drops it again once the nav's own container passes 32rem — + which would strand the drawer on a landscape phone or small tablet. */ +.nav > button[popovertarget] { + display: inline-flex; } @media (width >= 64rem) { @@ -37,6 +38,22 @@ } } +/* Nav actions (GitHub, Download PDF) belong to 48rem and up; on a phone only + the brand and the hamburger fit. This is what Yeti's [data-show="lg"] + utility would do, but the build's minifier mangles the less-than sign in + that utility's container query — and turns a less-than sign in a media + query here into an escaped one that drops the whole block — so every + condition in this file has to be written the "at least" way round. */ +.nav > [data-actions] { + display: none; +} + +@media (width >= 48rem) { + .nav > [data-actions] { + display: flex; + } +} + /* ---------- 3. Page head ---------- */ .page-head { border-block-end: var(--yeti-border-width) solid var(--yeti-color-border); @@ -103,6 +120,17 @@ border-inline-start-width: 0; /* no marker bar on the entry being read */ } +/* Closed state. The browser hides a closed popover itself, but only with a + user-agent rule — and #toc is a .card, whose author rule (display: flex) + outranks it, which used to leave a full-screen contents card in the page on + a phone. So the closed state is declared here; at 64rem and up the rule + below turns the same element into the sticky sidebar instead. */ +#toc:not(:popover-open) { + display: none; +} + +/* Open state on a phone: a drawer down the left edge, over a dimmed backdrop. + Light dismiss, Escape and the inlined link handler close it. */ #toc:popover-open { display: block; position: fixed; @@ -142,7 +170,7 @@ var(--yeti-space-md) ); } - #toc { + #toc:not(:popover-open) { display: block; max-block-size: calc( 100dvh - var(--yeti-scroll-padding) - var(--yeti-space-lg) @@ -235,7 +263,7 @@ /* ---------- 7. Figures ---------- */ .manual > p:has(> img) { margin-block-start: var(--yeti-space-xl); - padding: var(--yeti-space-lg); + padding: var(--yeti-space-sm); border: var(--yeti-border-width) solid var(--yeti-color-border); border-radius: var(--yeti-radius-md); background-color: light-dark( @@ -347,9 +375,6 @@ .site-footer .card::before { display: none; } - .manual > p:has(> img) { - box-shadow: none; - } .manual pre.sourceCode { white-space: pre-wrap; overflow: visible;