How PDF Generation Works in the HowToCook Repository: A Complete Technical Guide

The HowToCook repository generates its PDF documentation automatically using MkDocs with the mkdocs-with-pdf plugin, which renders the static site through WeasyPrint during the build process.

The Anduin2017/HowToCook project, a popular open-source cookbook for programmers, maintains its documentation as Markdown files that get transformed into both a static website and a downloadable PDF. Understanding the PDF generation architecture reveals how the repository maintains synchronized web and print documentation from a single source of truth.

The PDF Generation Architecture

MkDocs and the with-pdf Plugin

At the core of the PDF generation pipeline sits MkDocs, a static site generator designed for project documentation. The repository extends MkDocs functionality through the mkdocs-with-pdf plugin, which hooks into the build process after the standard HTML generation completes.

According to the source code in .github/templates/mkdocs_template.yml, the plugin activates with specific metadata and output settings:

plugins:
  - same-dir
  - search
  - with-pdf:
      author: GitHub Community
      copyright: The Unlicense
      cover_title: How To Cook
      cover_subtitle: 程序员做饭指南
      output_path: document.pdf

WeasyPrint Rendering Engine

The mkdocs-with-pdf plugin delegates the actual PDF creation to WeasyPrint, a visual rendering engine for HTML and CSS that converts web documents to PDF. This dependency appears in requirements.txt alongside the MkDocs plugin, ensuring the build environment contains the necessary libraries to transform the styled HTML into a paginated PDF document.

Configuring PDF Generation in MkDocs

The repository uses a template-based configuration system to maintain consistent PDF settings across builds. The file .github/templates/mkdocs_template.yml defines the with-pdf plugin configuration, specifying document metadata and the critical output_path: document.pdf parameter that determines where the final file appears in the built site.

When the build script runs, it processes this template to generate the active mkdocs.yml configuration file used by the MkDocs build command.

Build Pipeline and Automation

Dependency Management

PDF generation capabilities are declared in the project's requirements.txt file, which lists both mkdocs-with-pdf and weasyprint. Installing these dependencies prepares the environment for PDF output:

pip install -r requirements.txt

Configuration Generation

The repository employs a Node.js-based build script located at .github/readme-generate.js to orchestrate documentation generation. Triggered by npm run build as defined in package.json, this script dynamically generates both README.md and mkdocs.yml from the repository's Markdown recipe files and the templates in .github/templates/.

This automation ensures that the PDF configuration stays synchronized with the current state of the cookbook content.

CI/CD Integration

The GitHub Actions workflow defined in .github/workflows/build.yml executes the build script automatically during continuous integration. While the workflow generates the configuration files, the actual PDF compilation occurs when MkDocs processes the site, either through a subsequent deployment step or manual build command that invokes the with-pdf plugin.

Generating the PDF Locally

Developers and contributors can generate the PDF cookbook locally using the following workflow:

1. Install dependencies including the PDF generation libraries:

pip install -r requirements.txt

2. Generate the MkDocs configuration from the template:

npm run build

3. Build the site and PDF using MkDocs:

mkdocs build

The generated PDF appears at site/document.pdf (or the configured output directory) and is also accessible via http://127.0.0.1:8000/document.pdf when running mkdocs serve.

Summary

• The HowToCook repository generates PDFs using the MkDocs static site generator with the mkdocs-with-pdf plugin.
• WeasyPrint serves as the underlying rendering engine that converts HTML to PDF.
• Configuration resides in .github/templates/mkdocs_template.yml, specifying output_path: document.pdf and document metadata.
• The build pipeline uses .github/readme-generate.js (triggered by npm run build) to generate the active mkdocs.yml configuration.
• Dependencies are managed through requirements.txt, which includes both mkdocs-with-pdf and weasyprint.

Frequently Asked Questions

What tool does HowToCook use for PDF generation?

The repository uses MkDocs with the mkdocs-with-pdf plugin to generate PDF documentation. This plugin integrates with WeasyPrint, a Python library that renders HTML and CSS into paginated PDF documents, allowing the cookbook to produce a print-ready version of the website content automatically during the build process.

How can I generate the PDF locally?

To generate the PDF locally, first install the Python dependencies with pip install -r requirements.txt, then run npm run build to generate the mkdocs.yml configuration file. Finally, execute mkdocs build to compile both the static site and the PDF, which will be available at site/document.pdf in your local directory.

Where is the PDF output path configured?

The PDF output path is configured in the output_path parameter within the with-pdf plugin section of the MkDocs configuration. In the HowToCook repository, this setting is defined in the template file .github/templates/mkdocs_template.yml with the value document.pdf, which the build script propagates to the generated mkdocs.yml file.

Is the PDF generation automated in CI/CD?

Yes, the PDF generation process is integrated into the continuous integration pipeline through the GitHub Actions workflow defined in .github/workflows/build.yml. The workflow executes npm run build to generate the necessary configuration files, and when MkDocs builds the site during deployment, the with-pdf plugin automatically produces the PDF as part of the standard build output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}