mmlado · Sep 4, 2026 · Sep 4, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -33,6 +33,21 @@ jobs:
       - name: Generate Sphinx docs
         run: sphinx-build -W --keep-going -b html docs docs/_build/html
 
+      # 4b. Build the PDF and ship it inside the HTML tree, so it lands in the
+      #     versioned directory (/vX.Y/cryptnox-id-cli.pdf) on deploy — the
+      #     index page's "Download as PDF" link and the docs hub point there.
+      - name: Install LaTeX for PDF
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            latexmk texlive-latex-recommended texlive-latex-extra \
+            texlive-fonts-recommended texlive-fonts-extra tex-gyre
+
+      - name: Build PDF (pdflatex)
+        run: |
+          sphinx-build -M latexpdf docs docs/_build
+          cp docs/_build/latex/cryptnox-id-cli.pdf docs/_build/html/cryptnox-id-cli.pdf
+
       # 5. Fetch what is currently published, to carry earlier versions over
       #    (continue-on-error: the branch does not exist on the very first deploy)
       - name: Fetch previously published versions

diff --git a/docs/conf.py b/docs/conf.py
@@ -62,8 +62,10 @@
 html_show_sourcelink = False  # no "View page source" link
 html_copy_source = False  # and no _sources/*.rst.txt on the published site
 
-# PDF output name for a local `make latexpdf` run. CI builds HTML only - pdflatex
-# cannot render several characters these docs legitimately use.
+# PDF built by CI (docs.yml) with pdflatex and shipped inside the versioned HTML
+# dir as <repo_slug>.pdf. pdflatex cannot render every Unicode character, so the
+# sources stay within its set: no emoji outside `.. only:: html`, no arrows or
+# math symbols (use ->, at least, ...). The em/en dashes and ellipses it handles.
 latex_documents = [("index", f"{repo_slug}.tex", product_name, author, "manual")]
 
 todo_include_todos = False  # .. todo:: blocks must never reach the published site

diff --git a/docs/factory/pre-personalization-profiles.rst b/docs/factory/pre-personalization-profiles.rst
@@ -50,7 +50,7 @@ Built-in profiles
 
    * **generated on-card** — ``piv quickstart --profile ms-logon --slot 9A
      --algorithm RSA2048`` (the private key never leaves the card);
-   * **imported**, for an AD-issued credential (CSR → CA → import, or PKCS#12
+   * **imported**, for an AD-issued credential (CSR -> CA -> import, or PKCS#12
      import via :doc:`/piv/piv-personalization`).
 
    The object carries the ``IMPORTABLE`` attribute so the second path is
@@ -147,7 +147,7 @@ whole profile before anything is sent to a card:
 
 - the admin key mechanism must be AES-128/192/256 (this applet's 9B is
   AES-only);
-- PIN and PUK ``min`` must be at least 6 and ``max`` must be ≥ ``min``;
+- PIN and PUK ``min`` must be at least 6 and ``max`` must be at least ``min``;
 - PIN and PUK ``retries`` must be 0–10;
 - every key's mechanism must be one this applet actually supports (see
   ``inspect-defaults``);

diff --git a/docs/fido2/fido2-guide.rst b/docs/fido2/fido2-guide.rst
@@ -43,7 +43,7 @@ doesn't consume a retry.
 Write operations
 --------------------
 
-These use the CTAP2 **PIN/UV Auth Protocol** (ECDH key agreement →
+These use the CTAP2 **PIN/UV Auth Protocol** (ECDH key agreement ->
 AES/HMAC under protocol 1 or 2). PINs are entered by masked prompt or a
 ``--*-env`` variable, never on the command line, and are registered with
 the redactor.
@@ -100,7 +100,7 @@ authenticatorConfig policy
 applet exposes two subcommands; each is authorized by a pinUvAuthToken
 carrying the **authenticatorConfiguration** permission, so pass
 ``--pin-env NAME`` when a clientPIN is set. (The pinUvAuthParam is MACed
-over a mandatory ``32×0xFF`` prefix — per the CTAP 2.1 spec, not a card
+over a mandatory prefix of 32 ``0xFF`` bytes — per the CTAP 2.1 spec, not a card
 quirk.)
 
 .. code-block:: console

diff --git a/docs/genuine/genuineness-guide.rst b/docs/genuine/genuineness-guide.rst
@@ -23,7 +23,7 @@ that need **no secret key material**:
   against the on-card leaf certificate's public key. Because the nonce is
   random per run, a copied certificate or a replayed signature cannot pass —
   the card must physically hold the device private key *now*.
-* **Certificate chain.** ``leaf → Genuineness CA → … → pinned Cryptnox root``,
+* **Certificate chain.** ``leaf -> Genuineness CA -> … -> pinned Cryptnox root``,
   validated (name chaining, signatures, validity windows, CA constraints) and
   anchored on the pinned trust store. A root is trusted only because it is
   pinned — never because it appears in a chain read off the card.

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,6 +6,10 @@ Command-line management for the Cryptnox multi-applet smart card: PIV
 DESFire contactless — three independent functions on one physical card,
 driven by one tool: |cli|.
 
+.. only:: html
+
+   📄 `Download this documentation as PDF <cryptnox-id-cli.pdf>`__
+
 .. toctree::
    :maxdepth: 2
    :caption: General

diff --git a/docs/piv/quick-start-a-working-piv-card.rst b/docs/piv/quick-start-a-working-piv-card.rst
@@ -35,8 +35,8 @@ The one-command path
    $ cryptnox-id piv quickstart --default-keys
 
 ``piv quickstart`` detects the card state, then runs whatever is still needed
-of: PIN → PUK → key in slot 9C (ECC P-256, generated **on-card** — the private
-key never exists outside the card) → self-signed certificate → CHUID/CCC →
+of: PIN -> PUK -> key in slot 9C (ECC P-256, generated **on-card** — the private
+key never exists outside the card) -> self-signed certificate -> CHUID/CCC ->
 smoke-test. Steps already done are skipped, so re-runs converge. New PIN/PUK
 values come from masked prompts or ``CRYPTNOX_PIV_NEW_PIN`` /
 ``CRYPTNOX_PIV_NEW_PUK``.
@@ -118,7 +118,7 @@ returns ``6985`` for sign operations).
         --public-key 9c.pub.pem --out 9c.crt.pem
    $ cryptnox-id piv perso import-cert --slot 9C --cert 9c.crt.pem
 
-Or CA-issued: ``generate-csr`` → have your CA sign it → ``import-cert``.
+Or CA-issued: ``generate-csr`` -> have your CA sign it -> ``import-cert``.
 Large certificates are written with ISO command chaining automatically.
 
 **Step 4 — standard data objects.** Most PIV clients (including

diff --git a/docs/piv/ssh-public-key-authentication.rst b/docs/piv/ssh-public-key-authentication.rst
@@ -85,7 +85,7 @@ Fixing it: give 9A the SIGN role
 ------------------------------------
 
 You don't need the full ``ms-logon`` profile for this — the built-in ``ssh``
-profile changes only 9A's ``role`` (``AUTHENTICATE`` → ``AUTHENTICATE,
+profile changes only 9A's ``role`` (``AUTHENTICATE`` -> ``AUTHENTICATE,
 SIGN``); everything else is identical to ``cryptnox-default``. See
 :doc:`/factory/pre-personalization-profiles` for the full built-in profile list.
 

diff --git a/docs/piv/tls-client-authentication.rst b/docs/piv/tls-client-authentication.rst
@@ -60,7 +60,7 @@ platform. Try the target site directly first:
 1. Visit the target site. Some Firefox versions detect a PC/SC smart card
    natively and offer the card's certificate without any setup.
 2. If no certificate is offered, register the module manually:
-   ``about:preferences#privacy`` → **Security Devices** → **Load**. Module
+   ``about:preferences#privacy`` -> **Security Devices** -> **Load**. Module
    name: anything recognizable (e.g. ``Cryptnox PIV``). Module filename: the
    ``opensc-pkcs11.so`` path from :doc:`/piv/ssh-public-key-authentication`.
 3. Reload the site. On a certificate request, Firefox shows a picker listing

diff --git a/docs/piv/windows-logon-and-remote-desktop.rst b/docs/piv/windows-logon-and-remote-desktop.rst
@@ -120,7 +120,7 @@ Step 3 — log on
 * **Local/interactive**: select the smart-card credential tile and enter the
   PIV PIN.
 * **Remote Desktop**: in ``mstsc`` the card is redirected by default (Local
-  Resources → Smart cards). Connect to the domain host and authenticate with
+  Resources -> Smart cards). Connect to the domain host and authenticate with
   the PIN at the remote credential prompt.
 
 Scope and limits