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

> Discover how the HowToCook repository automatically generates PDFs with MkDocs and the mkdocs-with-pdf plugin. Learn the technical details of this efficient documentation process.

- Repository: [Anduin Xue/HowToCook](https://github.com/Anduin2017/HowToCook)
- Tags: deep-dive
- Published: 2026-02-27

---

**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`](https://github.com/Anduin2017/HowToCook/blob/main/.github/templates/mkdocs_template.yml), the plugin activates with specific metadata and output settings:

```yaml
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`](https://github.com/Anduin2017/HowToCook/blob/main/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`](https://github.com/Anduin2017/HowToCook/blob/main/.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`](https://github.com/Anduin2017/HowToCook/blob/main/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`](https://github.com/Anduin2017/HowToCook/blob/main/requirements.txt) file, which lists both `mkdocs-with-pdf` and `weasyprint`. Installing these dependencies prepares the environment for PDF output:

```bash
pip install -r requirements.txt

```

### Configuration Generation

The repository employs a Node.js-based build script located at [`.github/readme-generate.js`](https://github.com/Anduin2017/HowToCook/blob/main/.github/readme-generate.js) to orchestrate documentation generation. Triggered by `npm run build` as defined in [`package.json`](https://github.com/Anduin2017/HowToCook/blob/main/package.json), this script dynamically generates both [`README.md`](https://github.com/Anduin2017/HowToCook/blob/main/README.md) and [`mkdocs.yml`](https://github.com/Anduin2017/HowToCook/blob/main/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`](https://github.com/Anduin2017/HowToCook/blob/main/.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:

```bash
pip install -r requirements.txt

```

2. **Generate the MkDocs configuration** from the template:

```bash
npm run build

```

3. **Build the site and PDF** using MkDocs:

```bash
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`](https://github.com/Anduin2017/HowToCook/blob/main/.github/templates/mkdocs_template.yml), specifying `output_path: document.pdf` and document metadata.
- The build pipeline uses [`.github/readme-generate.js`](https://github.com/Anduin2017/HowToCook/blob/main/.github/readme-generate.js) (triggered by `npm run build`) to generate the active [`mkdocs.yml`](https://github.com/Anduin2017/HowToCook/blob/main/mkdocs.yml) configuration.
- Dependencies are managed through [`requirements.txt`](https://github.com/Anduin2017/HowToCook/blob/main/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`](https://github.com/Anduin2017/HowToCook/blob/main/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`](https://github.com/Anduin2017/HowToCook/blob/main/.github/templates/mkdocs_template.yml) with the value `document.pdf`, which the build script propagates to the generated [`mkdocs.yml`](https://github.com/Anduin2017/HowToCook/blob/main/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`](https://github.com/Anduin2017/HowToCook/blob/main/.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.