MkDocs TeXSmith Plugin

mkdocs-texsmith turns any MkDocs project into a set of LaTeX sources ready for high-quality PDF production. The plugin reuses the TeXSmith rendering pipeline to transform the pages that MkDocs renders into TeX, keeping navigation structure, numbering, cross references, and assets in sync.

Highlights

• Export one or many "books" from the same MkDocs site, each with its own metadata and output folder.
• Reuse TeXSmith templates or override individual blocks to match your house style.
• Combine global .bib files, per-book bibliographies, inline citations, and DOI lookups into a single bibliography.
• Copy and prune assets automatically so only referenced images end up in the LaTeX project.
• Optional HTML snapshots for debugging, plus Material for MkDocs specific tweaks out of the box.

Installation

pip install mkdocs-texsmith

The package targets Python 3.12+. If you manage dependencies with uv, run:

uv add mkdocs-texsmith

Quick Start

1. Add the plugin to your mkdocs.yml.

   plugins:
     - search
     - texsmith:
         build_dir: press # where LaTeX sources are written
         template: book # TeXSmith template to use
         bibliography:
           - docs/references.bib
   

2. Build your site as usual:

   mkdocs build
   

3. The LaTeX project for each configured book is created under press/. Compile the resulting index.tex with your preferred tool (latexmk, tectonic, etc.) to produce the PDF.

Configuration

All plugin options are declared under the texsmith plugin entry.

• enabled (bool): turns the plugin on or off; automatically disabled during mkdocs serve.
• build_dir (str): output root for generated LaTeX projects. Defaults to press.
• template (str): default TeXSmith template name. Falls back to book.
• parser (str): HTML parser backend used by TeXSmith (lxml by default).
• copy_assets (bool): copy images and other assets referenced by the book into the build directory.
• clean_assets (bool): remove unused files from the generated assets/ folder after rendering.
• language (str): override auto-detected language for templates and hyphenation.
• bibliography (list[str]): global .bib files applied to every book.
• books (list[dict]): per-book configuration (see below).
• template_overrides (dict[str, str]): map of template block names to override files.

Multiple books

The books list lets you export distinct artefacts from the same site. Each entry accepts BookConfig fields plus book-specific extras (template, template_overrides, bibliography):

plugins:
  - texsmith:
      books:
        - title: "User Guide"
          root: "Guide"
          folder: "user-guide"
          template: book
          bibliography:
            - docs/guide.bib
        - title: "API Reference"
          root: "Reference"
          base_level: 2
          copy_files:
            docs/appendix/*.tex: backmatter/

If you do not declare any books, the plugin creates one automatically using the first navigation page as the root section.

Bibliography sources

• Global bibliography files apply to every book.
• Book-level bibliography entries augment or override the global list.
• YAML front matter can declare inline bibliography entries, including DOI links. DOIs are resolved at build time; failures are logged but do not stop the build.
• Per-book .bib files are emitted with the LaTeX project, and an assets_map.yml manifest records the asset locations used by the renderer.

Templates and overrides

TeXSmith templates bundle LaTeX, Jinja, and formatter fragments. Set template globally or per book, then override specific fragments via template_overrides:

plugins:
  - texsmith:
      template: book
      template_overrides:
        heading: overrides/heading.j2
      books:
        - title: "Whitepaper"
          template_overrides:
            cover: overrides/custom_cover.tex.j2

Assets and HTML snapshots

• copy_assets: true copies images and other referenced files into <build_dir>/<book>/assets/.
• clean_assets: true prunes unused files after rendering, keeping the LaTeX project tidy.
• The exact Markdown each page was exported from is written under <build_dir>/<book>/sources/, which is the first place to look when a page renders differently in the PDF.

Development

1. Clone the repository and install dependencies:

   uv sync
   

2. Run the documentation site locally:

   uv run mkdocs serve
   

3. Use pytest or uv run pytest to execute tests before contributing patches.

The repository maintains a Makefile shortcut (make deps) that mirrors the uv sync step.

License

The project is distributed under the MIT License. See LICENSE.md for the full text.