MkDocs PDF Export Plugin

https://github.com/zhaoterryy/mkdocs-pdf-export-plugin
Admin
An MkDocs plugin that exports markdown pages as PDF files using WeasyPrint, supporting advanced...
Tokens:9,014
Snippets:61
Trust Score:8.5
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install MkDocs PDF Export Plugin

Source: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/README.md

Installs the mkdocs-pdf-export-plugin package using pip. This is the first step to enable PDF export functionality in MkDocs.

```bash
pip install mkdocs-pdf-export-plugin
```

--------------------------------

### Basic Mkdocs PDF Export Configuration

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This example shows a basic `mkdocs.yml` configuration for enabling the `pdf-export` plugin. It includes standard theme and plugin settings, resulting in individual PDF files for each page in the navigation.

```yaml
# mkdocs.yml
site_name: API Documentation
theme:
    name: material

plugins:
    - search
    - pdf-export

nav:
    - Home: index.md
    - API Reference: api.md
    - Examples: examples.md
```

--------------------------------

### Example Usage of Renderer for Single PDF Generation

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

Demonstrates how to use the Renderer class from the mkdocs_pdf_export_plugin to generate an individual PDF file from provided HTML content. It includes initializing the renderer and calling the write_pdf method with the HTML content, base URL, and output file path.

```python
# Example usage in custom script
from mkdocs_pdf_export_plugin.renderer import Renderer

# Create renderer
renderer = Renderer(combined=False, theme='material')

# Generate single PDF from HTML content
html_content = """
<!DOCTYPE html>
<html>
<head><title>My Page</title></head>
<body><h1>Hello World</h1></body>
</html>
"""
base_url = 'file:///home/user/docs/'
renderer.write_pdf(html_content, base_url, '/tmp/output.pdf')

# Result: /tmp/output.pdf created

```

--------------------------------

### Custom CSS for PDF Output

Source: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/README.md

Provides an example of custom CSS that can be used to style the generated PDF files. This CSS defines page size, margins, font, and header/footer content using CSS paged media module features.

```css
@page {
    size: a4 portrait;
    margin: 25mm 10mm 25mm 10mm;
    counter-increment: page;
    font-family: "Roboto","Helvetica Neue",Helvetica,Arial,sans-serif;
    white-space: pre;
    color: grey;
    @top-left {
        content: '© 2018 My Company';
    }
    @top-center {
        content: string(chapter);
    }
    @top-right {
        content: 'Page ' counter(page);
    }
}
```

--------------------------------

### Filter Documents for PDF Export using Regex

Source: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/docs/docs/options.md

This option allows you to specify a regular expression pattern to include only certain document names in the PDF export. Documents not matching the pattern will be excluded. The example filters for documents starting with 'article' or 'resume*'.

```yaml
plugins:
    - pdf-export:
        filter: 'article|resume*'
```

--------------------------------

### Advanced CSS for PDF Styling with MkDocs

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

Custom CSS rules for PDF generation, including page setup, headers, footers, typography, and elements like tables and code blocks. Supports watermarks and chapter titles.

```css
/* extra-pdf-styles.css */
@page {
    size: a4 portrait;
    margin: 25mm 10mm 25mm 10mm;
    counter-increment: page;
    font-family: "Roboto", "Helvetica Neue", Helvetica, Arial, sans-serif;

    @top-left {
        content: '© 2024 My Company';
        font-size: 9pt;
        color: grey;
    }

    @top-center {
        content: string(chapter);
        font-size: 9pt;
        color: grey;
    }

    @top-right {
        content: 'Page ' counter(page);
        font-size: 9pt;
        color: grey;
    }

    @bottom-center {
        content: 'Confidential';
        font-size: 8pt;
        color: red;
    }
}

/* Set chapter name from h1 elements */
h1 {
    string-set: chapter content();
    page-break-before: always;
}

/* Prevent breaking inside code blocks */
pre, code {
    page-break-inside: avoid;
}

/* Control table breaking */
table {
    page-break-inside: avoid;
}

/* Add borders to tables */
table {
    border-collapse: collapse;
    width: 100%;
}

table th, table td {
    border: 1px solid #ddd;
    padding: 8px;
}

/* Watermark */
@page {
    background: url('logo.png') no-repeat center center;
    background-size: 50%;
    opacity: 0.1;
}

```

--------------------------------

### Example: Transforming Relative Asset URLs to Absolute

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

A Python code snippet demonstrating the use of `replace_asset_hrefs` to convert relative links in an HTML string to absolute URLs. This is crucial for PDF rendering engines like WeasyPrint to locate and include assets correctly.

```python
from mkdocs_pdf_export_plugin.preprocessor.links.util import replace_asset_hrefs
from bs4 import BeautifulSoup

html = """
<html>
<head>
    <link rel="stylesheet" href="css/style.css">
</head>
<body>
    <img src="images/logo.png">
    <img src="https://example.com/banner.jpg">
</body>
</html>
"""

soup = BeautifulSoup(html, 'html.parser')
base_url = 'file:///home/user/docs/site/'
soup = replace_asset_hrefs(soup, base_url)

# Result:
# <link rel="stylesheet" href="file:///home/user/docs/site/css/style.css">
# <img src="file:///home/user/docs/site/images/logo.png">
# <img src="https://example.com/banner.jpg">  # Already absolute, unchanged

```

--------------------------------

### Mkdocs Selective PDF Export with Filter

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This configuration uses the `filter` option in `pdf-export` to generate PDFs only for pages matching a specific regex pattern. The example demonstrates filtering for 'whitepaper', 'report', or 'article'.

```yaml
# mkdocs.yml
site_name: Documentation Portal
theme:
    name: material

plugins:
    - search
    - pdf-export:
        filter: 'whitepaper|report|article'
        combined: false

nav:
    - Home: index.md
    - Articles:
        - Research Article: article-2024.md
        - Technical Whitepaper: whitepaper-cloud.md
    - Blog:
        - Post 1: blog/post-1.md
        - Post 2: blog/post-2.md
    - Reports:
        - Q4 Report: report-q4-2024.md
```

--------------------------------

### Set Custom Theme Handler Path for PDF Export

Source: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/docs/docs/options.md

This configuration allows specifying a custom Python module for handling themes in the PDF export process. The `theme_handler_path` must be relative to the project root. The example shows setting the path to `theme-handler.py`.

```yaml
plugins:
    - pdf-export:
        theme_handler_path: theme-handler.py
```

--------------------------------

### Mkdocs CLI Build Command for Basic PDF Export

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

Demonstrates the command-line execution of `mkdocs build` for a project configured with the `pdf-export` plugin. The output indicates the build process and lists the generated HTML and PDF files.

```bash
# Build documentation
mkdocs build

# Output:
# INFO    -  Building documentation...
# INFO    -  Converting 3 files to PDF took 4.2s

# Generated files:
ls site/
# index.html  index.pdf
# api.html    api.pdf
# examples.html  examples.pdf

# Each page has corresponding PDF
# Links between pages work correctly
```

--------------------------------

### Configure PDF Export Plugin Options

Source: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/README.md

Demonstrates how to configure various options for the pdf-export plugin in mkdocs.yml. Options include verbosity, media type, environment variable enablement, combined PDF output, and custom theme handler paths.

```yaml
plugins:
    - pdf-export:
        verbose: true
        media_type: print
        enabled_if_env: ENABLE_PDF_EXPORT
```

```yaml
plugins:
    - pdf-export:
        combined: true
        combined_output_path: pdf/combined.pdf
```

```yaml
plugins:
    - pdf-export:
        theme_handler_path: theme-handler.py
```

--------------------------------

### Renderer Class for PDF Generation using WeasyPrint

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

Implements a Renderer class responsible for generating PDFs from HTML content using the WeasyPrint library. It supports both individual PDF file generation and combined PDF creation. The class handles theme integration, page numbering injection, and preprocessing of HTML content for PDF output.

```python
# mkdocs_pdf_export_plugin/renderer.py
from weasyprint import HTML
from bs4 import BeautifulSoup

class Renderer:
    def __init__(self, combined: bool, theme: str, theme_handler_path: str = None):
        self.theme = self._load_theme_handler(theme, theme_handler_path)
        self.combined = combined
        self.page_order = []
        self.pgnum = 0
        self.pages = []

    def write_pdf(self, content: str, base_url: str, filename: str):
        # Generate and write individual PDF file
        doc = self.render_doc(content, base_url)
        doc.write_pdf(filename)

    def render_doc(self, content: str, base_url: str, rel_url: str = None):
        # Parse HTML content
        soup = BeautifulSoup(content, 'html.parser')

        # Inject page number counter CSS
        self.inject_pgnum(soup)

        # Add theme-specific stylesheet
        stylesheet = self.theme.get_stylesheet()
        if stylesheet:
            style_tag = soup.new_tag('style')
            style_tag.string = stylesheet
            soup.head.append(style_tag)

        # Preprocess links for PDF
        if self.combined:
            soup = prep_combined(soup, base_url, rel_url)
        else:
            soup = prep_separate(soup, base_url)

        # Render with WeasyPrint
        html = HTML(string=str(soup))
        return html.render()

    def write_combined_pdf(self, output_path: str):
        # Render all pages and combine
        rendered_pages = []
        for p in self.pages:
            render = self.render_doc(p[0], p[1], p[2])
            self.pgnum += len(render.pages)
            rendered_pages.append(render)

        # Flatten all pages and write combined PDF
        flatten = lambda l: [item for sublist in l for item in sublist]
        all_pages = flatten([p.pages for p in rendered_pages if p != None])
        rendered_pages[0].copy(all_pages).write_pdf(output_path)

    def inject_pgnum(self, soup):
        # Add CSS for continuous page numbering
        pgnum_counter = soup.new_tag('style')
        pgnum_counter.string = '''
        @page :first {{
            counter-reset: __pgnum__ {};
        }}
        @page {{
            counter-increment: __pgnum__;
        }}
        '''.format(self.pgnum)
        soup.head.append(pgnum_counter)

```

--------------------------------

### Mkdocs CLI Build Command for Combined PDF Export

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This command builds the Mkdocs project with PDF export enabled via an environment variable. The output confirms the combined PDF export and indicates the time taken for conversion, showing the single generated PDF file.

```bash
# Development build (no PDF)
mkdocs build
# Output: PDF export is disabled

# Production build (with PDF)
ENABLE_PDF_EXPORT=1 mkdocs build
# Output: Combined PDF export is enabled
# Output: Converting 6 files to PDF took 14.8s

ls site/downloads/
# complete-manual.pdf  # Single 50-page PDF with all content

# All pages link to same combined PDF
# Continuous page numbering
# Table of contents preserved
# Internal links work as anchors
```

--------------------------------

### Configure Material Theme PDF Export (YAML)

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This YAML configuration demonstrates how to integrate the PDF export plugin with the Material theme in MkDocs. It specifies the Material theme and includes the PDF export plugin, causing a PDF download button to appear on each page.

```yaml
theme:
    name: material

plugins:
    - search
    - pdf-export

# Material theme automatically detected
# PDF download button appears in each page
```

--------------------------------

### Material Theme CSS and Button (Python)

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This Python code provides functions to handle Material theme specific PDF customizations. `get_stylesheet` returns CSS to fix Material theme display issues in PDF output. `modify_html` inserts a PDF download button into each page based on the given theme configuration.

```python
from bs4 import BeautifulSoup

def get_stylesheet() -> str:
    # Return CSS to fix Material theme issues in PDF
    return """
    h1, h2, h3 {
         string-set: chapter content();
    }

    .md-container {
        display: block;
        padding-top: 0;
    }

    .md-main {
        display: block;
        height: inherit;
    }

    .md-typeset .admonition {
        display: block;
        border-top: .1rem solid rgba(0,0,0,.07);
        border-right: .1rem solid rgba(0,0,0,.07);
        border-bottom: .1rem solid rgba(0,0,0,.07);
        page-break-inside: avoid;
    }

    .md-typeset table {
        border: .1rem solid rgba(0,0,0,.07);
    }
    """

def modify_html(html: str, href: str) -> str:
    # Add PDF download button for Material theme
    a_tag = "<a class=\"md-content__button md-icon\" download href=\"%s\" title=\"PDF Export\">" % href
    icon = '<svg style="height: 1.2rem; width: 1.2rem;" viewBox="0 0 384 512"...'
    button_tag = a_tag + icon + "</a>"

    # Insert button into article
    insert_point = "<article class=\"md-content__inner md-typeset\">"
    html = html.replace(insert_point, insert_point + button_tag)

    return html
```

--------------------------------

### Mkdocs CLI Build Command for Selective PDF Export

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This command builds the Mkdocs project with the PDF export filter applied. The output shows which pages matched the filter and were converted to PDF, contrasting with pages that were excluded.

```bash
# Build with filter
mkdocs build

# Output:
# pdf export filter is : whitepaper|report|article. Matching pages are : ['article-2024', 'whitepaper-cloud', 'report-q4-2024']
# Converting 3 files to PDF took 5.1s

ls site/
# index.html (no PDF)
# article-2024.html  article-2024.pdf  ✓
# whitepaper-cloud.html  whitepaper-cloud.pdf  ✓
# blog/post-1.html (no PDF)
# blog/post-2.html (no PDF)
# report-q4-2024.html  report-q4-2024.pdf  ✓

# Only matching pages have PDFs
# Saves build time and storage
```

--------------------------------

### Enable PDF Export Plugin in mkdocs.yml

Source: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/README.md

Enables the pdf-export plugin within the MkDocs configuration file (mkdocs.yml). It also shows how to explicitly enable the search plugin, which is often desired.

```yaml
plugins:
    - search
    - pdf-export
```

--------------------------------

### MkDocs Configuration for Custom Theme Handler

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

YAML configuration for MkDocs to enable and specify a custom theme handler script. This tells the pdf-export plugin where to find your custom Python file for styling and modifications.

```yaml
# mkdocs.yml - Use custom theme handler
plugins:
    - pdf-export:
        theme_handler_path: theme-handler.py

```

--------------------------------

### Python Utility for Absolute Asset URLs

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

A Python function to convert relative asset URLs (like images and stylesheets) to absolute URLs. It uses WeasyPrint's URL utilities and `os.path.isabs` to handle different base URLs and ensure assets are correctly referenced by the PDF renderer.

```python
# mkdocs_pdf_export_plugin/preprocessor/links/util.py
from weasyprint import urls
from bs4 import BeautifulSoup
import os

def abs_asset_href(href: str, base_url: str):
    # Convert relative URLs to absolute for WeasyPrint
    if urls.url_is_absolute(href) or os.path.isabs(href):
        return href

    return urls.iri_to_uri(urls.urljoin(base_url, href))

def replace_asset_hrefs(soup: BeautifulSoup, base_url: str):
    # Make all asset links absolute
    for link in soup.find_all('link', href=True):
        link['href'] = abs_asset_href(link['href'], base_url)

    for asset in soup.find_all(src=True):
        asset['src'] = abs_asset_href(asset['src'], base_url)

    return soup

```

--------------------------------

### MkDocs Plugin Configuration and Page Post-Processing

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

Defines the PdfExportPlugin for MkDocs, handling configuration options such as media type, verbosity, environment-based enabling, and combined output settings. It also processes pages after HTML generation, conditionally enabling PDF export based on configuration and environment variables, and rendering individual or combined PDFs using a Renderer.

```python
from mkdocs.plugins import BasePlugin
from mkdocs.config import config_options
import os
import re

class PdfExportPlugin(BasePlugin):
    config_scheme = (
        ('media_type', config_options.Type(str, default='print')),
        ('verbose', config_options.Type(bool, default=False)),
        ('enabled_if_env', config_options.Type(str)),
        ('combined', config_options.Type(bool, default=False)),
        ('combined_output_path', config_options.Type(str, default="pdf/combined.pdf")),
        ('theme_handler_path', config_options.Type(str)),
        ('filter', config_options.Type(str))
    )

    def on_config(self, config):
        # Check if plugin should be enabled via environment variable
        if 'enabled_if_env' in self.config:
            env_name = self.config['enabled_if_env']
            if env_name:
                self.enabled = os.environ.get(env_name) == '1'

        # Configure WeasyPrint logging
        from weasyprint.logger import LOGGER
        import logging
        if self.config['verbose']:
            LOGGER.setLevel(logging.DEBUG)
        else:
            LOGGER.setLevel(logging.ERROR)
        return config

    def on_post_page(self, output_content, page, config):
        # Process each page after HTML generation
        # Check filter regex
        match = re.search(self.config['filter'], page.file.name)
        if not self.enabled or not match:
            return output_content

        # Generate PDF for this page
        abs_dest_path = page.file.abs_dest_path
        path = os.path.dirname(abs_dest_path)
        filename = os.path.splitext(os.path.basename(page.file.src_path))[0]
        pdf_file = filename + '.pdf'

        if self.combined:
            # Add to combined PDF
            self.renderer.add_doc(output_content, base_url, page.file.url)
        else:
            # Write individual PDF
            self.renderer.write_pdf(output_content, base_url, os.path.join(path, pdf_file))

        return output_content

```

--------------------------------

### Configure MkDocs PDF Export Plugin Options

Source: https://github.com/zhaoterryy/mkdocs-pdf-export-plugin/blob/master/docs/docs/options.md

This snippet shows how to configure the MkDocs PDF Export plugin in the `mkdocs.yml` file. It demonstrates setting options like `verbose`, `media_type`, and `enabled_if_env` to control PDF generation behavior.

```yaml
plugins:
    - pdf-export:
        verbose: true
        media_type: print
        enabled_if_env: ENABLE_PDF_EXPORT
```

--------------------------------

### Custom Theme Handler for MkDocs PDF Export

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

A Python script to define custom CSS and modify HTML for PDF generation. It uses BeautifulSoup for HTML parsing and defines specific page layouts and content for PDF output. This handler can be configured in mkdocs.yml.

```python
from bs4 import BeautifulSoup

def get_stylesheet() -> str:
    # Custom CSS for PDF rendering
    return """
    @page {
        size: a4 portrait;
        margin: 25mm 10mm 25mm 10mm;
        @top-left {
            content: '© 2024 My Company';
        }
        @top-center {
            content: string(chapter);
        }
        @top-right {
            content: 'Page ' counter(page);
        }
    }

    body {
        font-family: 'Arial', sans-serif;
    }

    h1 {
        string-set: chapter content();
        page-break-before: always;
    }
    """

def modify_html(html: str, href: str) -> str:
    # Add download link in custom location
    soup = BeautifulSoup(html, 'html.parser')

    # Find main content div
    main = soup.find('main', class_='content')
    if main:
        # Create download link
        link = soup.new_tag('a', href=href, download=True)
        link.string = 'Download PDF'
        link['class'] = 'pdf-download-link'

        # Insert at beginning of content
        main.insert(0, link)

    return str(soup)

```

--------------------------------

### Mkdocs Combined PDF Export Configuration

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This `mkdocs.yml` configuration enables `pdf-export` with `combined: true`, specifying a `combined_output_path` for a single PDF file. It also demonstrates conditional enabling via `enabled_if_env` and custom CSS for styling.

```yaml
# mkdocs.yml
site_name: Product Documentation
theme:
    name: material
    palette:
        primary: indigo

extra_css:
    - css/pdf-styles.css

plugins:
    - search
    - pdf-export:
        verbose: false
        combined: true
        combined_output_path: downloads/complete-manual.pdf
        enabled_if_env: ENABLE_PDF_EXPORT

nav:
    - Home: index.md
    - Getting Started:
        - Installation: getting-started/installation.md
        - Configuration: getting-started/configuration.md
    - User Guide:
        - Basics: guide/basics.md
        - Advanced: guide/advanced.md
    - API Reference: api/reference.md
```

--------------------------------

### Python PDF Preprocessing Functions

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

These Python functions preprocess HTML content for PDF export. `get_combined` transforms IDs and links for a unified PDF, while `get_separate` prepares links for individual PDFs. Both functions ensure asset links are absolute.

```python
from bs4 import BeautifulSoup
from .links import transform_href, transform_id, get_body_id, replace_asset_hrefs
import urls
import os

def get_combined(soup: BeautifulSoup, base_url: str, rel_url: str):
    # Transform all IDs to be unique across combined PDF
    for id in soup.find_all(id=True):
        id['id'] = transform_id(id['id'], rel_url)

    # Transform all internal links to anchors
    for a in soup.find_all('a', href=True):
        if urls.url_is_absolute(a['href']) or os.path.isabs(a['href']):
            continue
        a['href'] = transform_href(a['href'], rel_url)

    # Set unique body ID for this page
    soup.body['id'] = get_body_id(rel_url)

    # Make asset links absolute
    soup = replace_asset_hrefs(soup, base_url)
    return soup

def get_separate(soup: BeautifulSoup, base_url: str):
    # Transform HTML links to PDF links
    for a in soup.find_all('a', href=True):
        a['href'] = rel_pdf_href(a['href'])

    # Make asset links absolute
    soup = replace_asset_hrefs(soup, base_url)
    return soup
```

--------------------------------

### MkDocs Configuration for Extra PDF Styles

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

YAML configuration for MkDocs to include custom CSS files for PDF exports. This allows integration of advanced styling defined in separate CSS files.

```yaml
# mkdocs.yml - Apply custom PDF styles
extra_css:
    - extra-pdf-styles.css

plugins:
    - pdf-export:
        media_type: print

```

--------------------------------

### Transform Links for Combined PDF (Python)

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This Python code provides functions for transforming links and IDs specifically for combined PDF generation. `transform_href` converts internal and external links into internal anchors, while `transform_id` prefixes element IDs with the page path for proper linking within the combined PDF.

```python
def transform_href(href: str, rel_url: str):
    # Transform links for combined PDF (all pages in one file)
    head, tail = os.path.split(href)
    num_hashtags = tail.count('#')

    if tail.startswith('#'):
        # Internal link: #section
        head, section = os.path.split(rel_url)
        section = os.path.splitext(section)[0]
        id = tail[1:]
    elif num_hashtags == 1:
        # Link with fragment: page.html#section
        section, ext = tuple(os.path.splitext(tail))
        id = str.split(ext, '#')[1]

        if head == '..':
            href = normalize_href(href, rel_url)
            return '#{}:{}'.format(href, id)

    # Return normalized anchor link
    return '#{}{}:{}'.format(head, section, id)

def transform_id(id: str, rel_url: str):
    # Transform element IDs for combined PDF
    head, tail = os.path.split(rel_url)
    section, _ = os.path.splitext(tail)

    if len(head) > 0:
        head += '/'

    # Prefix ID with page path: section -> guide/intro:section
    return '{}{}:{}'.format(head, section, id)
```

```python
from mkdocs_pdf_export_plugin.preprocessor.links.transform import transform_href, transform_id

# Links become internal anchors
current_page = 'guide/intro.html'
assert transform_href('#overview', current_page) == '#guide/intro:overview'
assert transform_href('api.html', current_page) == '#guide/api:'
assert transform_href('api.html#functions', current_page) == '#guide/api:functions'

# IDs get prefixed with page path
assert transform_id('section1', 'guide/intro.html') == 'guide/intro:section1'
assert transform_id('header', 'api.html') == 'api:header'
```

--------------------------------

### Convert HTML Links to PDF Links (Python)

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This Python code defines functions to transform HTML links to PDF links. The `is_doc` function checks if a given href is a relative HTML document. The `rel_pdf_href` function converts relative HTML links to their PDF counterparts, changing extensions from .html to .pdf.

```python
from weasyprint import urls
import os

def is_doc(href: str):
    # Check if href is a relative HTML document
    tail = os.path.basename(href)
    _, ext = os.path.splitext(tail)

    absurl = urls.url_is_absolute(href)
    abspath = os.path.isabs(href)
    htmlfile = ext.startswith('.html')

    if absurl or abspath or not htmlfile:
        return False
    return True

def rel_pdf_href(href: str):
    # Transform HTML links to PDF links
    head, tail = os.path.split(href)
    filename, _ = os.path.splitext(tail)

    internal = href.startswith('#')
    if not is_doc(href) or internal:
        return href

    # Convert: ../guide/intro.html -> ../guide/intro.pdf
    return urls.iri_to_uri(os.path.join(head, filename + '.pdf'))
```

```python
from mkdocs_pdf_export_plugin.preprocessor.links.util import rel_pdf_href

# HTML links become PDF links
assert rel_pdf_href('guide.html') == 'guide.pdf'
assert rel_pdf_href('../api/reference.html') == '../api/reference.pdf'
assert rel_pdf_href('docs/getting-started.html') == 'docs/getting-started.pdf'

# Internal and external links unchanged
assert rel_pdf_href('#section') == '#section'
assert rel_pdf_href('https://example.com/page.html') == 'https://example.com/page.html'
assert rel_pdf_href('/absolute/path.html') == '/absolute/path.html'
```

--------------------------------

### Custom CSS for Combined PDF Export

Source: https://context7.com/zhaoterryy/mkdocs-pdf-export-plugin/llms.txt

This CSS file defines page layout and styling for PDFs generated by `mkdocs-pdf-export-plugin`. It sets A4 portrait size, margins, and includes a top-right running header with page numbers.

```css
/* css/pdf-styles.css */
@page {
    size: a4 portrait;
    margin: 20mm;

    @top-right {
        content: 'Product Manual v2.0 | Page ' counter(page);
        font-size: 8pt;
    }
}

h1 {
    string-set: chapter content();
    color: #3f51b5;
    page-break-before: always;
}
```
Tokens:
Raw