docs: add one-command README HTML/PDF export

2026-07-23 05:48:43 +04:00
parent 3d28d3832f
commit 5b1a78782a
4 changed files with 171 additions and 2 deletions
@@ -0,0 +1,58 @@
+<!-- Injected by Asciidoctor when generating the print/PDF HTML variant.
+     Usage: asciidoctor -a docinfodir=docs -a docinfo=shared README.adoc -o README-print.html
+     Fixes color-emoji rendering in headless Chromium and adapts the layout for print. -->
+<style>
+/* Font stacks with an explicit emoji fallback. "Noto Color Emoji" must be
+   installed system-wide (package: fonts-noto-color-emoji). */
+* {
+    font-family: "Noto Sans", "Noto Color Emoji", sans-serif !important;
+}
+pre, code, kbd, samp {
+    font-family: "Noto Sans Mono", "Noto Color Emoji", monospace !important;
+}
+
+@media print {
+    /* The left-floating TOC is screen-only; bring it back into the flow */
+    #header, #toc {
+        position: static !important;
+        width: auto !important;
+        max-width: none !important;
+        float: none !important;
+        height: auto !important;
+        overflow: visible !important;
+    }
+    #content {
+        margin: 0 !important;
+        padding: 0 !important;
+        max-width: none !important;
+    }
+    body {
+        margin: 0;
+        font-size: 10pt;
+        line-height: 1.35;
+    }
+    /* Keep headings with their content, break tables between rows only */
+    h1, h2, h3, h4, h5, h6 {
+        page-break-after: avoid;
+    }
+    tr, td, th, .admonitionblock, .imageblock {
+        page-break-inside: avoid;
+    }
+    /* Long code listings may overflow the page width: allow wrapping */
+    pre {
+        white-space: pre-wrap;
+        word-wrap: break-word;
+    }
+    img {
+        max-width: 100%;
+    }
+    /* Links are not clickable in a PDF: keep them readable, not blue */
+    a {
+        color: inherit;
+        text-decoration: none;
+    }
+    a[href^="http"]::after {
+        content: "";
+    }
+}
+</style>
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Generate the documentation export(s) from README.adoc.
+#
+#   docs/generate-readme-pdf.sh           # README.html + README.pdf
+#   docs/generate-readme-pdf.sh --html    # README.html only
+#   docs/generate-readme-pdf.sh --pdf     # README.pdf only
+#
+# Both outputs land in the project root and are Git-ignored.
+#
+# Requirements:
+#   - asciidoctor            (e.g. gem install asciidoctor)
+#   - chromium               (headless PDF rendering)
+#   - fonts-noto-color-emoji (color emoji in the PDF)
+#
+# Why Chromium instead of asciidoctor-pdf (used by the VSCodium extension)?
+# Its Prawn engine cannot embed color-emoji fonts (CBDT/COLR), so emoji
+# disappear. Chromium handles them fine as long as "Noto Color Emoji"
+# is installed. The docs/docinfo.html stylesheet (emoji fallback + print
+# rules) is injected only for this build, via Asciidoctor's docinfo
+# mechanism, and adapts the layout for print (TOC in flow, table/page
+# breaks, wrapped code listings).
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+MODE="${1:---all}"
+HTML_OUT="README.html"
+PDF_OUT="README.pdf"
+
+build_html() {
+    asciidoctor -b html5 -a docinfodir=docs -a docinfo=shared README.adoc -o "$1"
+    echo "HTML generated: $1"
+}
+
+build_pdf() {
+    # Resolve to an absolute path for the file:// URL
+    local html_path="$1"
+    [[ "$html_path" != /* ]] && html_path="$PWD/$html_path"
+    chromium --headless --disable-gpu --no-sandbox \
+        --no-pdf-header-footer \
+        --print-to-pdf="$PDF_OUT" \
+        "file://$html_path"
+    echo "PDF generated: $PDF_OUT"
+}
+
+case "$MODE" in
+    --html)
+        build_html "$HTML_OUT"
+        ;;
+    --pdf)
+        TMP_HTML="$(mktemp --suffix=.html)"
+        trap 'rm -f "$TMP_HTML"' EXIT
+        build_html "$TMP_HTML" >/dev/null
+        build_pdf "$TMP_HTML"
+        ;;
+    --all)
+        build_html "$HTML_OUT"
+        build_pdf "$HTML_OUT"
+        ;;
+    -h|--help)
+        sed -n '2,10p' "$0"
+        exit 0
+        ;;
+    *)
+        echo "Usage: $0 [--html|--pdf|--all]" >&2
+        exit 1
+        ;;
+esac