PDF User Manual Pipeline for use in Release and nightly Build

2026-03-30 04:31:04 +02:00 · 2026-03-27 01:10:54 +01:00
parent db031bb5e3
commit 318f3720b8
11 changed files with 624 additions and 5 deletions
--- a/.github/latex-manual/manual-template.tex
+++ b/.github/latex-manual/manual-template.tex
@@ -0,0 +1,255 @@
+%% ============================================================
+%%  KST4Contest – pandoc LaTeX manual template
+%%  PDF engine: XeLaTeX
+%%  Usage: pandoc --template=manual-template.tex --pdf-engine=xelatex
+%% ============================================================
+\documentclass[11pt,a4paper]{article}
+
+%% ─── Font / encoding ──────────────────────────────────────────────────────
+\usepackage{fontspec}
+% Latin Modern handles all Western European characters (umlauts etc.)
+\defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase}
+
+%% ─── Language ─────────────────────────────────────────────────────────────
+\usepackage{polyglossia}
+$if(polyglossia-lang)$
+\setmainlanguage{$polyglossia-lang$}
+$else$
+\setmainlanguage{english}
+$endif$
+
+%% ─── Page layout ──────────────────────────────────────────────────────────
+\usepackage[a4paper, top=2.5cm, bottom=2.5cm, left=2.5cm, right=2.5cm]{geometry}
+
+%% ─── Colors ───────────────────────────────────────────────────────────────
+\usepackage[dvipsnames,svgnames,x11names]{xcolor}
+\definecolor{brand-green}{RGB}{7,166,54}
+\definecolor{link-blue}{RGB}{0,86,163}
+\definecolor{code-bg}{RGB}{245,247,250}
+\definecolor{code-border}{RGB}{180,200,225}
+\definecolor{blockquote-line}{RGB}{7,166,54}
+
+%% ─── Hyperlinks ───────────────────────────────────────────────────────────
+\usepackage{hyperref}
+\hypersetup{
+  colorlinks  = true,
+  linkcolor   = link-blue,
+  urlcolor    = link-blue,
+  filecolor   = link-blue,
+  citecolor   = link-blue,
+  pdftitle    = {$title$},
+  pdfauthor   = {DO5AMF (Marc Fröhlich), DN9APW (Philipp Wagner)},
+  pdfsubject  = {KST4Contest User Manual},
+  pdfkeywords = {KST4Contest, pratiKST, VHF, Contest, Ham Radio},
+  bookmarks            = true,
+  bookmarksnumbered    = true,
+  bookmarksopen        = true,
+  bookmarksopenlevel   = 2,
+  pdfpagemode          = UseOutlines,
+}
+
+%% ─── Graphics ─────────────────────────────────────────────────────────────
+\usepackage{graphicx}
+\graphicspath{{./}{./github_docs/}}
+\makeatletter
+\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
+\def\maxheight{\ifdim\Gin@nat@height>0.65\textheight 0.65\textheight\else\Gin@nat@height\fi}
+\makeatother
+\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
+
+%% ─── Tables ───────────────────────────────────────────────────────────────
+\usepackage{longtable}
+\usepackage{booktabs}
+\usepackage{array}
+\usepackage{calc}
+\usepackage{multirow}
+\setlength{\tabcolsep}{8pt}
+\renewcommand{\arraystretch}{1.35}
+% Pandoc pipe-table helpers
+\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}}
+\newcolumntype{C}[1]{>{\centering\arraybackslash}p{#1}}
+\newcolumntype{R}[1]{>{\raggedleft\arraybackslash}p{#1}}
+
+%% ─── Lists ────────────────────────────────────────────────────────────────
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{2pt}\setlength{\parskip}{0pt}}
+
+%% ─── Code blocks (--listings flag) ───────────────────────────────────
+\usepackage{listings}
+\lstset{
+  basicstyle       = \ttfamily\small,
+  backgroundcolor  = \color{code-bg},
+  frame            = single,
+  framesep         = 4pt,
+  rulecolor        = \color{code-border},
+  breaklines       = true,
+  breakatwhitespace= false,
+  showstringspaces = false,
+  extendedchars    = true,
+  xleftmargin      = 6pt,
+  xrightmargin     = 6pt,
+  aboveskip        = 8pt,
+  belowskip        = 8pt,
+  literate         = {→}{{\ensuremath{\rightarrow}}}1
+                     {←}{{\ensuremath{\leftarrow}}}1
+                     {↔}{{\ensuremath{\leftrightarrow}}}1,
+}
+
+%% ─── Blockquotes ──────────────────────────────────────────────────────────
+\usepackage{mdframed}
+\newmdenv[
+  topline      = false,
+  rightline    = false,
+  bottomline   = false,
+  leftline     = true,
+  linewidth    = 3pt,
+  linecolor    = blockquote-line,
+  backgroundcolor = code-bg,
+  leftmargin   = 0pt,
+  rightmargin  = 0pt,
+  innerleftmargin  = 12pt,
+  innerrightmargin = 8pt,
+  innertopmargin   = 6pt,
+  innerbottommargin= 6pt,
+  skipabove    = 8pt,
+  skipbelow    = 8pt,
+]{blockquotebox}
+
+\renewenvironment{quote}
+  {\begin{blockquotebox}\small\itshape}
+  {\end{blockquotebox}}
+
+%% ─── Section styling ──────────────────────────────────────────────────────
+\usepackage{titlesec}
+
+\titleformat{\section}
+  {\Large\bfseries\color{brand-green}}
+  {}
+  {0em}
+  {}
+  [\color{brand-green}\titlerule]
+\titlespacing{\section}{0pt}{20pt}{10pt}
+
+\titleformat{\subsection}
+  {\large\bfseries\color{brand-green}}
+  {}
+  {0em}
+  {}
+\titlespacing{\subsection}{0pt}{14pt}{6pt}
+
+\titleformat{\subsubsection}
+  {\normalsize\bfseries}
+  {}
+  {0em}
+  {}
+\titlespacing{\subsubsection}{0pt}{10pt}{4pt}
+
+% Level 4 (####): displayed as a named block heading in dark-grey
+\titleformat{\paragraph}
+  {\normalsize\bfseries\color{brand-green}}
+  {}
+  {0em}
+  {}
+\titlespacing{\paragraph}{0pt}{8pt}{2pt}
+
+% Level 5 (#####): slightly smaller, italic, lighter grey
+\titleformat{\subparagraph}
+  {\small\bfseries\itshape\color{brand-green!85!black}}
+  {}
+  {0em}
+  {}
+\titlespacing{\subparagraph}{0pt}{6pt}{1pt}
+
+% Reserve two additional section levels for future use (###### and deeper).
+% Pandoc currently maps up to \subparagraph for standard Markdown headings.
+\titleclass{\subsubsubsection}{straight}[\subparagraph]
+\newcounter{subsubsubsection}[subparagraph]
+\renewcommand\thesubsubsubsection{\thesubparagraph.\arabic{subsubsubsection}}
+\titleformat{\subsubsubsection}
+  {\small\bfseries\color{brand-green!75!black}}
+  {}
+  {0em}
+  {}
+\titlespacing{\subsubsubsection}{0pt}{5pt}{1pt}
+
+\titleclass{\subsubsubsubsection}{straight}[\subsubsubsection]
+\newcounter{subsubsubsubsection}[subsubsubsection]
+\renewcommand\thesubsubsubsubsection{\thesubsubsubsection.\arabic{subsubsubsubsection}}
+\titleformat{\subsubsubsubsection}
+  {\small\itshape\color{brand-green!65!black}}
+  {}
+  {0em}
+  {}
+\titlespacing{\subsubsubsubsection}{0pt}{4pt}{1pt}
+
+\setcounter{secnumdepth}{6}
+\setcounter{tocdepth}{6}
+
+%% ─── Header / Footer ──────────────────────────────────────────────────────
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\fancyhf{}
+\fancyhead[L]{\small\color{brand-green}\textbf{KST4Contest}}
+\fancyhead[R]{\small\color{brand-green}$if(version)$$version$$endif$}
+\fancyfoot[L]{\small\color{gray}DO5AMF (Marc Fröhlich) \textbar\ DN9APW (Philipp Wagner)}
+\fancyfoot[C]{\small\color{gray}\thepage}
+\fancyfoot[R]{\small\color{gray}$title$}
+\renewcommand{\headrulewidth}{0.4pt}
+\renewcommand{\footrulewidth}{0.3pt}
+\renewcommand{\headrule}{\color{brand-green}\hrule width\headwidth height\headrulewidth}
+
+%% ─── Paragraph spacing ────────────────────────────────────────────────────
+\usepackage{parskip}
+\setlength{\parskip}{6pt}
+\setlength{\parindent}{0pt}
+
+%% ─── TOC styling ──────────────────────────────────────────────────────────
+\usepackage{tocloft}
+\renewcommand{\cfttoctitlefont}{\Large\bfseries\color{brand-green}}
+\renewcommand{\cftsecfont}{\bfseries\color{brand-green}}
+\renewcommand{\cftsecpagefont}{\bfseries\color{brand-green}}
+\renewcommand{\cftsubsecfont}{\color{brand-green}}
+\renewcommand{\cftsubsecpagefont}{\color{brand-green}}
+\renewcommand{\cftsubsubsecfont}{\color{brand-green!85!black}}
+\renewcommand{\cftsubsubsecpagefont}{\color{brand-green!85!black}}
+\renewcommand{\cftparafont}{\color{brand-green!75!black}}
+\renewcommand{\cftparapagefont}{\color{brand-green!75!black}}
+\renewcommand{\cftsubparafont}{\color{brand-green!65!black}}
+\renewcommand{\cftsubparapagefont}{\color{brand-green!65!black}}
+\setlength{\cftbeforesecskip}{4pt}
+
+%% ─── Misc ─────────────────────────────────────────────────────────────────
+\usepackage{amsmath}
+\usepackage{microtype}
+% Pandoc helper macros
+\newcommand{\passthrough}[1]{#1}
+
+%% ══════════════════════════════════════════════════════════════════════════
+\begin{document}
+
+%% ─── Title page ───────────────────────────────────────────────────────────
+\begin{titlepage}
+  \pagecolor{brand-green}
+  \centering
+  \vspace*{3.5cm}
+  {\fontsize{52}{62}\selectfont\bfseries\color{white}KST4Contest}\\[0.4cm]
+  {\fontsize{22}{28}\selectfont\color{white!75!brand-green}pratiKST (ON4KST Chat Client)}\\[2.8cm]
+  \color{white!40!brand-green}\rule{10cm}{0.6pt}\\[1.8cm]
+  {\LARGE\bfseries\color{white}$title$}\\[1cm]
+  $if(version)${\large\color{white!80!brand-green}Version:\space$version$}\\[0.6cm]$endif$
+  \vfill
+  {\large\color{white}DO5AMF · Marc Fröhlich · DM5M · DN9APW · Philipp Wagner}\\[0.4cm]
+  {\color{white!70!brand-green}\today}\\[2cm]
+\end{titlepage}
+
+\pagecolor{white}
+\newpage
+
+%% ─── Table of Contents ────────────────────────────────────────────────────
+\tableofcontents
+\newpage
+
+%% ─── Main content ─────────────────────────────────────────────────────────
+$body$
+
+\end{document}
--- a/.github/latex-manual/strip-wiki-links.lua
+++ b/.github/latex-manual/strip-wiki-links.lua
@@ -0,0 +1,156 @@
+--[[
+  strip-wiki-links.lua – pandoc Lua filter for KST4Contest documentation
+  -----------------------------------------------------------------------
+  1. Removes language-switch blockquotes (GitHub Wiki navigation) that
+     are not relevant in the printed PDF manual.
+  2. Converts internal GitHub-wiki-style links to in-document anchors
+     so links jump within the generated PDF.
+  3. Replaces flag emoji and other symbols that XeLaTeX cannot render with
+     plain-text equivalents.
+--]]
+
+local PAGE_ANCHOR_MAP = {
+  ["de-Home"] = "kst4contest-wiki",
+  ["de-Installation"] = "installation",
+  ["de-Konfiguration"] = "konfiguration",
+  ["de-Funktionen"] = "funktionen",
+  ["de-Benutzeroberflaeche"] = "benutzeroberflache",
+  ["de-Makros-und-Variablen"] = "makros-und-variablen",
+  ["de-Log-Synchronisation"] = "log-synchronisation",
+  ["de-AirScout-Integration"] = "airscout-integration",
+  ["de-DX-Cluster-Server"] = "integrierter-dx-cluster-server",
+  ["de-Changelog"] = "changelog",
+
+  ["en-Home"] = "kst4contest-wiki",
+  ["en-Installation"] = "installation",
+  ["en-Configuration"] = "configuration",
+  ["en-Features"] = "features",
+  ["en-User-Interface"] = "user-interface",
+  ["en-Macros-and-Variables"] = "macros-and-variables",
+  ["en-Log-Sync"] = "log-synchronisation",
+  ["en-AirScout-Integration"] = "airscout-integration",
+  ["en-DX-Cluster-Server"] = "built-in-dx-cluster-server",
+  ["en-Changelog"] = "changelog",
+
+  ["Installation"] = "installation",
+  ["Konfiguration"] = "konfiguration",
+  ["Funktionen"] = "funktionen",
+  ["Benutzeroberflaeche"] = "benutzeroberflache",
+  ["Makros-und-Variablen"] = "makros-und-variablen",
+  ["Log-Synchronisation"] = "log-synchronisation",
+  ["AirScout-Integration"] = "airscout-integration",
+  ["DX-Cluster-Server"] = "integrierter-dx-cluster-server",
+  ["Changelog"] = "changelog",
+
+  ["Configuration"] = "configuration",
+  ["Features"] = "features",
+  ["User-Interface"] = "user-interface",
+  ["Macros-and-Variables"] = "macros-and-variables",
+  ["Log-Sync"] = "log-synchronisation",
+}
+
+local function normalize_anchor(text)
+  local s = text:lower()
+  s = s:gsub("%%20", "-")
+  s = s:gsub("ä", "a"):gsub("ö", "o"):gsub("ü", "u"):gsub("ß", "ss")
+  s = s:gsub("[^%w%s%-_]", "")
+  s = s:gsub("[_%s]+", "-")
+  s = s:gsub("%-+", "-")
+  s = s:gsub("^%-", ""):gsub("%-$", "")
+  return s
+end
+
+local function normalize_page_key(page)
+  local key = page:gsub("^%./", ""):gsub("^/", "")
+  key = key:gsub("^github_docs/", "")
+  key = key:gsub("%.md$", "")
+  return key
+end
+
+local function resolve_page_anchor(page)
+  local key = normalize_page_key(page)
+  return PAGE_ANCHOR_MAP[key] or normalize_anchor(key)
+end
+
+local function convert_url_token(token)
+  local url, trailing = token:match("^(https?://%S-)([%.%,%;%:%!%?]?)$")
+  if not url then
+    return nil
+  end
+
+  local link = pandoc.Link({pandoc.Str(url)}, url)
+  if trailing ~= "" then
+    return {link, pandoc.Str(trailing)}
+  end
+  return link
+end
+
+-- Map of emoji / special Unicode sequences → plain-text replacements.
+-- Add more entries here as needed.
+local EMOJI_MAP = {
+  -- Flag sequences
+  ["\xF0\x9F\x87\xAC\xF0\x9F\x87\xA7"] = "[EN]",  -- 🇬🇧
+  ["\xF0\x9F\x87\xA9\xF0\x9F\x87\xAA"] = "[DE]",  -- 🇩🇪
+  -- Status symbols
+  ["\xE2\x9C\x85"] = "[OK]",   -- ✅
+  ["\xE2\x9D\x8C"] = "[--]",   -- ❌
+  -- Misc symbols used in tables / text
+  ["\xF0\x9F\x94\xB4"] = "[red]",    -- 🔴
+  ["\xF0\x9F\x9F\xA1"] = "[yellow]", -- 🟡
+  ["\xF0\x9F\x9F\xA2"] = "[green]",  -- 🟢
+}
+
+--- Replace emoji in a plain string.
+local function replace_emoji(text)
+  for pattern, replacement in pairs(EMOJI_MAP) do
+    text = text:gsub(pattern, replacement)
+  end
+  return text
+end
+
+--- Filter: remove language-switch blockquotes from PDF output.
+-- These blockquotes appear in every wiki page for GitHub navigation
+-- but are not needed in the printed manual.
+function BlockQuote(el)
+  local text = pandoc.utils.stringify(el)
+  if text:find("Du liest gerade die deutsche Version") or
+     text:find("You are reading the English version") then
+    return {}
+  end
+  return el
+end
+
+--- Filter: convert internal wiki links to in-PDF anchor links.
+function Link(el)
+  local target = el.target
+  -- Keep external URLs unchanged.
+  if target:match("^https?://") or target:match("^mailto:") then
+    return el
+  end
+
+  if target:match("^#") then
+    local fragment = target:gsub("^#", "")
+    return pandoc.Link(el.content, "#" .. normalize_anchor(fragment), el.title, el.attr)
+  end
+
+  local page, fragment = target:match("^([^#]+)#(.+)$")
+  if page and fragment then
+    return pandoc.Link(el.content, "#" .. normalize_anchor(fragment), el.title, el.attr)
+  end
+
+  return pandoc.Link(el.content, "#" .. resolve_page_anchor(target), el.title, el.attr)
+end
+
+--- Filter: replace emoji sequences in plain Str elements.
+function Str(el)
+  local linkified = convert_url_token(el.text)
+  if linkified then
+    return linkified
+  end
+
+  local replaced = replace_emoji(el.text)
+  if replaced ~= el.text then
+    return pandoc.Str(replaced)
+  end
+  return el
+end
--- a/.github/workflows/docs-pdf.yml
+++ b/.github/workflows/docs-pdf.yml
@@ -0,0 +1,107 @@
+name: Build Documentation PDF
+
+# Runs when documentation changes are pushed to main, or on manual trigger.
+# Also triggered as a dependency from the tagged-release workflow.
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - github_docs/**
+      - .github/latex-manual/**
+      - .github/workflows/docs-pdf.yml
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs-pdf:
+    name: Build Documentation PDF
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4.1.7
+
+      - name: Resolve version string
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
+            VERSION="${{ github.ref_name }}"
+          else
+            VERSION="$(grep -m1 '<version>' pom.xml | sed 's/.*<version>\(.*\)<\/version>.*/\1/')-${GITHUB_SHA::7}"
+          fi
+          echo "DOC_VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Install pandoc and LaTeX toolchain
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y --no-install-recommends \
+            pandoc \
+            texlive-xetex \
+            texlive-fonts-recommended \
+            texlive-latex-extra \
+            texlive-plain-generic
+
+      - name: Build English PDF manual
+        run: |
+          mkdir -p dist
+          pandoc \
+            --from=markdown-yaml_metadata_block \
+            --template=.github/latex-manual/manual-template.tex \
+            --pdf-engine=xelatex \
+            --lua-filter=.github/latex-manual/strip-wiki-links.lua \
+            --resource-path=.:github_docs \
+            --listings \
+            --toc \
+            --toc-depth=6 \
+            -V title="User Manual" \
+            -V polyglossia-lang=english \
+            -V version="${DOC_VERSION}" \
+            -o dist/KST4Contest-${DOC_VERSION}-manual-en.pdf \
+            github_docs/en-Home.md \
+            github_docs/en-Installation.md \
+            github_docs/en-Configuration.md \
+            github_docs/en-Features.md \
+            github_docs/en-User-Interface.md \
+            github_docs/en-Macros-and-Variables.md \
+            github_docs/en-Log-Sync.md \
+            github_docs/en-AirScout-Integration.md \
+            github_docs/en-DX-Cluster-Server.md \
+            github_docs/en-Changelog.md
+
+      - name: Build German PDF manual
+        run: |
+          pandoc \
+            --from=markdown-yaml_metadata_block \
+            --template=.github/latex-manual/manual-template.tex \
+            --pdf-engine=xelatex \
+            --lua-filter=.github/latex-manual/strip-wiki-links.lua \
+            --resource-path=.:github_docs \
+            --listings \
+            --toc \
+            --toc-depth=6 \
+            -V title="Benutzerhandbuch" \
+            -V polyglossia-lang=german \
+            -V version="${DOC_VERSION}" \
+            -o dist/KST4Contest-${DOC_VERSION}-manual-de.pdf \
+            github_docs/de-Home.md \
+            github_docs/de-Installation.md \
+            github_docs/de-Konfiguration.md \
+            github_docs/de-Funktionen.md \
+            github_docs/de-Benutzeroberflaeche.md \
+            github_docs/de-Makros-und-Variablen.md \
+            github_docs/de-Log-Synchronisation.md \
+            github_docs/de-AirScout-Integration.md \
+            github_docs/de-DX-Cluster-Server.md \
+            github_docs/de-Changelog.md
+
+      - name: Upload PDF artifacts
+        uses: actions/upload-artifact@v4.3.4
+        with:
+          name: docs-pdf
+          path: dist/KST4Contest-*-manual-*.pdf
+          retention-days: 30
--- a/.github/workflows/tagged-release.yml
+++ b/.github/workflows/tagged-release.yml
@@ -134,26 +134,110 @@ jobs:
          name: linux-appimage
          path: dist/praktiKST-${{ github.ref_name }}-linux-x86_64.AppImage

+  build-docs-pdf:
+    name: Build Documentation PDF
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4.1.7
+
+      - name: Install pandoc and LaTeX toolchain
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y --no-install-recommends \
+            pandoc \
+            texlive-xetex \
+            texlive-fonts-recommended \
+            texlive-latex-extra \
+            texlive-plain-generic
+
+      - name: Build English PDF manual
+        run: |
+          mkdir -p dist
+          pandoc \
+            --from=markdown-yaml_metadata_block \
+            --template=.github/latex-manual/manual-template.tex \
+            --pdf-engine=xelatex \
+            --lua-filter=.github/latex-manual/strip-wiki-links.lua \
+            --resource-path=.:github_docs \
+            --listings \
+            --toc \
+            --toc-depth=3 \
+            -V title="User Manual" \
+            -V polyglossia-lang=english \
+            -V version="${{ github.ref_name }}" \
+            -o dist/KST4Contest-${{ github.ref_name }}-manual-en.pdf \
+            github_docs/en-Home.md \
+            github_docs/en-Installation.md \
+            github_docs/en-Configuration.md \
+            github_docs/en-Features.md \
+            github_docs/en-User-Interface.md \
+            github_docs/en-Macros-and-Variables.md \
+            github_docs/en-Log-Sync.md \
+            github_docs/en-AirScout-Integration.md \
+            github_docs/en-DX-Cluster-Server.md \
+            github_docs/en-Changelog.md
+
+      - name: Build German PDF manual
+        run: |
+          pandoc \
+            --from=markdown-yaml_metadata_block \
+            --template=.github/latex-manual/manual-template.tex \
+            --pdf-engine=xelatex \
+            --lua-filter=.github/latex-manual/strip-wiki-links.lua \
+            --resource-path=.:github_docs \
+            --listings \
+            --toc \
+            --toc-depth=3 \
+            -V title="Benutzerhandbuch" \
+            -V polyglossia-lang=german \
+            -V version="${{ github.ref_name }}" \
+            -o dist/KST4Contest-${{ github.ref_name }}-manual-de.pdf \
+            github_docs/de-Home.md \
+            github_docs/de-Installation.md \
+            github_docs/de-Konfiguration.md \
+            github_docs/de-Funktionen.md \
+            github_docs/de-Benutzeroberflaeche.md \
+            github_docs/de-Makros-und-Variablen.md \
+            github_docs/de-Log-Synchronisation.md \
+            github_docs/de-AirScout-Integration.md \
+            github_docs/de-DX-Cluster-Server.md \
+            github_docs/de-Changelog.md
+
+      - name: Upload PDF artifacts
+        uses: actions/upload-artifact@v4.3.4
+        with:
+          name: docs-pdf
+          path: dist/KST4Contest-${{ github.ref_name }}-manual-*.pdf
+
  release-tag:
    name: Publish Tagged Release
    runs-on: ubuntu-latest
    needs:
      - build-windows-zip
      - build-linux-appimage
+      - build-docs-pdf

    steps:
      - name: Download Windows artifact
-        uses: actions/download-artifact@v4.1.1
+        uses: actions/download-artifact@v4.1.3
        with:
          name: windows-zip
          path: release-assets/windows

      - name: Download Linux artifact
-        uses: actions/download-artifact@v4.1.1
+        uses: actions/download-artifact@v4.1.3
        with:
          name: linux-appimage
          path: release-assets/linux

+      - name: Download PDF manuals
+        uses: actions/download-artifact@v4.1.3
+        with:
+          name: docs-pdf
+          path: release-assets/docs
+
      - name: Create tagged release
        uses: ncipollo/release-action@v1
        with:
@@ -165,4 +249,8 @@ jobs:
          replacesArtifacts: false
          makeLatest: ${{ !startsWith(github.ref_name, 'beta-') }}
          generateReleaseNotes: true
-          artifacts: release-assets/windows/praktiKST-${{ github.ref_name }}-windows-x64.zip,release-assets/linux/praktiKST-${{ github.ref_name }}-linux-x86_64.AppImage
+          artifacts: >-
+            release-assets/windows/praktiKST-${{ github.ref_name }}-windows-x64.zip,
+            release-assets/linux/praktiKST-${{ github.ref_name }}-linux-x86_64.AppImage,
+            release-assets/docs/KST4Contest-${{ github.ref_name }}-manual-en.pdf,
+            release-assets/docs/KST4Contest-${{ github.ref_name }}-manual-de.pdf
--- a/.gitignore
+++ b/.gitignore
@@ -30,5 +30,8 @@ target/
 #builds
 build/

+#pdf output directory
+dist/
+
 #zip files for local backups
 *.zip
--- a/github_docs/de-AirScout-Integration.md
+++ b/github_docs/de-AirScout-Integration.md
@@ -48,7 +48,8 @@ In AirScout die UDP-Schnittstelle aktivieren:
 In den KST4Contest-Preferences → **AirScout Settings**:
 - AirScout-Kommunikation aktivieren
 - IP und Port auf Standardwerte lassen (sofern nicht geändert)
-![AirscoutSchritt3](as_plane_feed_3.png)
+
+![AirscoutSchritt3](as_plane_feed_3.png){ width=85% }



--- a/github_docs/de-Konfiguration.md
+++ b/github_docs/de-Konfiguration.md
@@ -9,7 +9,9 @@ Nach dem ersten Start öffnet sich das **Einstellungsfenster** – dieses ist de
 ---

 ## Station Settings (Stationseinstellungen)
+
 ![Stationseinstellungen](client_settings_window_station.png)
+
 ### Login und Chat-Kategorien

 Hier werden die Zugangsdaten für den ON4KST-Chat eingetragen (Rufzeichen und Passwort). 
--- a/github_docs/de-Log-Synchronisation.md
+++ b/github_docs/de-Log-Synchronisation.md
@@ -5,6 +5,7 @@
 KST4Contest markiert gearbeitete Stationen automatisch in der Chat-Benutzerliste. Dafür gibt es zwei grundlegende Methoden:

 ---
+
 ![Log-Synchronisation Einstellungsfenster](client_settings_window_logsync.png)

 ## Methode 1: Universal File Based Callsign Interpreter (Simplelogfile)
@@ -33,6 +34,7 @@ Das Logprogramm sendet beim Speichern eines QSOs ein UDP-Paket an die Broadcast-
 ## Unterstützte Logprogramme

 ### UCXLog (DL7UCX)
+
 ![UCXLog Konfiguration](ucxlog_logsync.png)

 UCXLog sendet QSO-UDP-Pakete und Transceiver-Frequenzpakete.
--- a/github_docs/en-AirScout-Integration.md
+++ b/github_docs/en-AirScout-Integration.md
@@ -48,7 +48,8 @@ In AirScout, enable the UDP interface:
 In KST4Contest Preferences → **AirScout Settings**:
 - Enable AirScout communication
 - Leave IP and port at their default values (unless changed)
-![AirscoutStep3](as_plane_feed_3.png)
+
+![AirscoutStep3](as_plane_feed_3.png){ width=85% }



--- a/github_docs/en-Configuration.md
+++ b/github_docs/en-Configuration.md
@@ -9,7 +9,9 @@ After the first start, the **settings window** opens – this is the central sta
 ---

 ## Station Settings
+
 ![Station Settings](client_settings_window_station.png)
+
 ### Login and Chat Categories

 Enter your ON4KST chat credentials here (callsign and password).
--- a/github_docs/en-Log-Sync.md
+++ b/github_docs/en-Log-Sync.md
@@ -5,6 +5,7 @@
 KST4Contest automatically marks worked stations in the chat user list. Two basic methods are available:

 ---
+
 ![Log Sync Settings Window](client_settings_window_logsync.png)

 ## Method 1: Universal File Based Callsign Interpreter (Simplelogfile)
@@ -33,6 +34,7 @@ When saving a QSO, the logging software sends a UDP packet to the broadcast addr
 ## Supported Logging Software

 ### UCXLog (DL7UCX)
+
 ![UCXLog Configuration](ucxlog_logsync.png)

 UCXLog sends QSO UDP packets and transceiver frequency packets.