PDF Export and Offline Documentation¶

MkDocs supports generating PDF versions of your documentation for offline reading and distribution. This feature is essential for creating printable manuals, archival copies, and offline-accessible documentation.

Overview¶

The PDF export functionality allows you to: - Generate a single PDF containing your entire documentation - Create individual PDFs for specific sections - Customize the appearance with print-specific CSS - Include cover pages and table of contents - Support for all MkDocs features in PDF format

Configuration¶

Basic Setup¶

Add the mkdocs-pdf-export-plugin to your configuration:

plugins:
  - pdf-export:
      enabled_if_env: ENABLE_PDF_EXPORT

Advanced Configuration¶

plugins:
  - pdf-export:
      verbose: true
      media_type: print
      enabled_if_env: ENABLE_PDF_EXPORT
      export_on_build: true

      # PDF Configuration
      combined: true               # Create single PDF for entire site
      combined_output_path: pdf/documentation.pdf

      # Cover Page
      cover: true
      cover_title: "Your Documentation Title"
      cover_subtitle: "Complete Reference Guide"
      cover_logo: assets/logo.svg

      # Table of Contents
      toc_title: "Table of Contents"
      heading_shift: 0
      toc_level: 3
      ordered_chapter_level: 2

      # Content Options
      exclude_pages:
        - 'blog/'
        - 'includes/'
      two_columns_level: 3

      # Rendering Options
      render_js: false
      headless_chrome_path: "/usr/bin/chromium"

Generating PDFs¶

During Build¶

To generate PDFs during the build process:

export ENABLE_PDF_EXPORT=1
mkdocs build

On-Demand Generation¶

Generate PDFs without rebuilding the entire site:

mkdocs build --dirty

Individual Page PDFs¶

Configure per-page PDF generation:

plugins:
  - pdf-export:
      combined: false  # Generate individual PDFs

Styling PDFs¶

Print-Specific CSS¶

Create custom styles for PDF output:

@media print {
    /* Page setup */
    @page {
        size: A4;
        margin: 2cm;
    }

    /* Hide navigation elements */
    .md-header,
    .md-nav,
    .md-footer {
        display: none !important;
    }

    /* Typography adjustments */
    body {
        font-size: 11pt;
        line-height: 1.6;
    }

    /* Page breaks */
    h1 {
        page-break-before: always;
    }

    pre, table, figure {
        page-break-inside: avoid;
    }
}

Custom Cover Page¶

Create a custom cover page template:

<!-- overrides/pdf-cover.html -->
<div class="pdf-cover">
    <img loading="lazy" src="{{ config.theme.logo }}" class="logo">
    <h1>{{ config.site_name }}</h1>
    <p class="subtitle">{{ config.site_description }}</p>
    <p class="date">Generated: {{ build_date }}</p>
</div>

Features Support¶

Supported Elements¶

The following features work well in PDFs:

Feature	Support	Notes
Text content	✅ Full	All formatting preserved
Code blocks	✅ Full	Syntax highlighting included
Tables	✅ Full	Responsive tables converted
Images	✅ Full	Embedded in PDF
Admonitions	✅ Full	Styled appropriately
Lists	✅ Full	All list types supported
Links	✅ Partial	External links shown as URLs
Math	✅ Full	Rendered equations

Limited Support¶

Some features have limitations in PDF:

Interactive elements - Tabs show all content
Animations - Static representation only
Videos - Shows placeholder or link
Search - Not available in PDF
Navigation - Standard PDF bookmarks

Best Practices¶

1. Content Organization¶

Structure your content for both web and print:

# Chapter Title {.print-page-break-before}

## Section One

Content that works well in both formats...

<div class="web-only">
This content only appears on the website.
</div>

<div class="print-only">
This content only appears in the PDF.
</div>

2. Image Handling¶

Optimize images for print:

<img loading="lazy" src="diagrams/architecture.png" alt="High-res diagram">{.print-full-width}

3. Link Management¶

Make links print-friendly:

@media print {
    /* Show URLs for external links */
    a[href^="http"]:after {
        content: " (" attr(href) ")";
        font-size: 0.8em;
    }

    /* Hide URLs for internal links */
    a[href^="#"]:after,
    a[href^="/"]:after {
        content: none;
    }
}

4. Table of Contents¶

Configure TOC depth for readability:

plugins:
  - pdf-export:
      toc_level: 2  # Only show h1 and h2 in PDF TOC

Offline Documentation Bundle¶

Creating an Offline Bundle¶

Generate a complete offline package:

#!/bin/bash
# build-offline.sh

# Build the site
export ENABLE_PDF_EXPORT=1
mkdocs build

# Create offline bundle
mkdir -p offline-docs
cp -r site/* offline-docs/
cp site/pdf/*.pdf offline-docs/

# Create index for offline viewing
cat > offline-docs/index.html << EOF
<!DOCTYPE html>
<html>
<head>
    <title>Offline Documentation</title>
</head>
<body>
    <h1>Documentation</h1>
    <ul>
        <li><a href="index.html">Web Version</a></li>
        <li><a href="pdf/documentation.pdf">PDF Version</a></li>
    </ul>
</body>
</html>
EOF

# Package as zip
zip -r documentation-offline.zip offline-docs/

Distribution Options¶

USB/Physical Media
Include both HTML and PDF versions
Add a README with viewing instructions
Internal Networks
Host on local servers
No internet dependency
Email Distribution
PDF attachments for easy sharing
Compressed bundles for complete docs

Troubleshooting¶

Common Issues¶

Issue	Solution
PDF generation fails	Install system dependencies: `wkhtmltopdf` or `chromium`
Missing fonts	Install required fonts system-wide
Broken layouts	Check print CSS media queries
Large file sizes	Optimize images, exclude unnecessary pages
Memory errors	Increase memory limits or split into sections

Debug Mode¶

Enable verbose logging:

plugins:
  - pdf-export:
      verbose: true
      debug: true

Performance Tips¶

Exclude large sections during development
Cache generated PDFs to avoid regeneration
Use conditional generation with environment variables
Optimize images before PDF generation

Advanced Features¶

Custom PDF Plugins¶

Create post-processing scripts:

# scripts/post-process-pdf.py
import PyPDF2

def add_watermark(input_pdf, output_pdf, watermark_text):
    """Add watermark to PDF pages"""
    # Implementation here
    pass

def compress_pdf(input_pdf, output_pdf):
    """Compress PDF file size"""
    # Implementation here
    pass

Multiple PDF Outputs¶

Generate different versions:

# PDF for users
- pdf-export:
    combined_output_path: pdf/user-guide.pdf
    exclude_pages: ['api/', 'development/']

# PDF for developers  
- pdf-export:
    combined_output_path: pdf/developer-guide.pdf
    exclude_pages: ['tutorials/', 'getting-started/']

Integration with CI/CD¶

GitHub Actions Example¶

name: Build Documentation
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies
        run: |
          sudo apt-get install -y chromium-browser
          pip install -r requirements.txt

      - name: Build docs with PDF
        env:
          ENABLE_PDF_EXPORT: 1
        run: mkdocs build

      - name: Upload PDF artifact
        uses: actions/upload-artifact@v2
        with:
          name: documentation-pdf
          path: site/pdf/*.pdf

Summary¶

PDF export provides essential offline access to your documentation. With proper configuration and styling, you can create professional, print-ready documents that complement your online documentation.