Add PDF export, migrate to uv, and add CI markdown linting

.github/workflows/ci-cd.yml

@@ -20,7 +20,25 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install markdownlint-cli
+        run: npm install -g [email protected]
+
+      - name: Lint markdown
+        run: markdownlint '**/*.md'
+
   build-and-deploy:
+    needs: lint
     runs-on: ubuntu-latest
     name: Build Documentation
     outputs:
@@ -29,27 +47,19 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Cache pip dependencies
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
 
-      - name: Install Python dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -r requirements.txt
+      - name: Install dependencies
+        run: uv sync
 
+      - name: Install WeasyPrint system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz-subset0
 
       - name: Build MkDocs documentation
-        run: mkdocs build --verbose --clean
+        env:
+          ENABLE_PDF_EXPORT: "1"
+        run: uv run mkdocs build --verbose --clean
 
       - name: Check if deployment needed
         id: check-deploy

.markdownlint.yaml

@@ -0,0 +1,26 @@
+---
+# Markdownlint configuration for RHCE study guide
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+default: true
+
+# Disable line length — study materials have long command examples
+MD013: false
+
+# Allow duplicate headings — repeated section titles across modules
+MD024: false
+
+# Allow inline HTML — MkDocs uses <details>, <summary>, etc.
+MD033: false
+
+# Allow emphasis as heading — used intentionally in study materials
+MD036: false
+
+# Allow non-sequential ordered list prefixes — intentional numbering
+MD029: false
+
+# Disable fenced code language requirement — some blocks are plain text
+MD040: false
+
+# Disable table column style — tables are readable as-is
+MD060: false

.markdownlintignore

@@ -12,3 +12,9 @@ site/
 
 # External copyrighted materials
 sources/
+
+# Python virtual environment
+.venv/
+
+# Vendored Ansible collections (third-party code)
+vagrant/collections/

.pre-commit-config.yaml

@@ -32,8 +32,8 @@ repos:
 
   # Markdown linting (for documentation quality)
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.44.0
+    rev: v0.45.0
     hooks:
       - id: markdownlint
-        args:
-          - --config=.mdl_config.yaml
+        args: ["--fix"]
+        files: \.md$

docs/index.md

@@ -2,6 +2,8 @@
 
 Welcome to the comprehensive Red Hat Certified Engineer (RHCE) certification study repository! This resource provides complete coverage of all RHCE exam objectives with practical automation focus for passing the EX294 exam.
 
+> **PDF Download**: [Download the complete study guide as PDF](pdf/rhce-study-guide.pdf)
+
 ## 🎯 About the RHCE Certification
 
 The Red Hat Certified Engineer (RHCE) certification demonstrates your ability to use Ansible for enterprise automation, configuration management, and orchestration. The EX294 exam focuses on:

mkdocs.yml

@@ -46,6 +46,19 @@ nav:
       - 'RHCE Acronyms & Glossary': rhce_acronyms_glossary.md
       - 'Knowledge Gaps Checklist': knowledge_gaps_checklist.md
 
+# Plugins
+plugins:
+  - search
+  - to-pdf:
+      cover: true
+      cover_title: "RHCE Certification Study Guide"
+      cover_subtitle: "Comprehensive Study Materials for Red Hat Certified Engineer Exam"
+      toc_title: "Table of Contents"
+      toc_level: 3
+      ordered_chapter_level: 2
+      output_path: pdf/rhce-study-guide.pdf
+      enabled_if_env: ENABLE_PDF_EXPORT
+
 # Markdown extensions
 markdown_extensions:
   - toc:

pdf_event_hook.py

@@ -0,0 +1,20 @@
+"""Hook module for mkdocs-to-pdf plugin.
+
+Works around a bug in mkdocs-to-pdf 0.10.1 where the generic theme handler's
+inject_link() signature doesn't match what the event_hook caller passes.
+See: https://github.com/domWalters/mkdocs-to-pdf/issues
+"""
+
+from bs4 import BeautifulSoup
+
+
+def inject_link(html, href, page, logger):
+    soup = BeautifulSoup(html, 'html.parser')
+    if soup.head:
+        link = soup.new_tag(
+            'link', href=href, rel='alternate',
+            title='PDF', type='application/pdf'
+        )
+        soup.head.append(link)
+        return str(soup)
+    return html

pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "rhce-docs"
+version = "0.1.0"
+description = "RHCE certification study guide documentation"
+requires-python = ">=3.9"
+dependencies = [
+    "mkdocs",
+    "mkdocs-to-pdf",
+]

requirements.txt

@@ -1,5 +1,6 @@
 # MkDocs and dependencies for RHCE documentation site
 mkdocs
+mkdocs-to-pdf
 
 # Ansible and automation tools for development and testing
 ansible

templates/styles.scss

@@ -0,0 +1,42 @@
+/* Custom PDF styles for mkdocs-to-pdf */
+
+/* Reset the readthedocs theme's inline code styling when inside pre blocks.
+   The theme applies color:#e74c3c, font-size:75%, white-space:nowrap to all
+   <code> elements, which breaks code blocks in PDF output. */
+pre code,
+pre code span {
+  color: inherit !important;
+  font-size: inherit !important;
+  white-space: inherit !important;
+  background: none !important;
+  border: none !important;
+  padding: 0 !important;
+  font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono",
+    "Courier New", Courier, monospace !important;
+}
+
+pre {
+  white-space: pre-wrap !important;
+  word-wrap: break-word;
+  overflow-x: auto;
+  font-size: 9pt;
+  line-height: 1.4;
+  padding: 12px;
+  background-color: #f8f8f8;
+  border: 1px solid #e1e4e5;
+  border-radius: 3px;
+  color: #333;
+  font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono",
+    "Courier New", Courier, monospace;
+}
+
+/* Pygments syntax highlighting tokens */
+.c1, .c, .cm { color: #6a737d; }         /* comments */
+.k, .kn, .kp, .kr { color: #d73a49; }    /* keywords */
+.nb, .bp { color: #005cc5; }             /* builtins */
+.s, .s1, .s2, .sb, .sc, .se { color: #032f62; } /* strings */
+.m, .mi, .mf, .mh, .mo { color: #005cc5; }      /* numbers */
+.o, .ow { color: #d73a49; }              /* operators */
+.nf, .nc { color: #6f42c1; }             /* functions/classes */
+.nv, .vi, .vm { color: #e36209; }        /* variables */
+.w { color: transparent; }               /* whitespace token - invisible */