# MkDocs Exporter

<div>
  <a href="https://pypi.org/project/mkdocs-exporter">
    <img src="https://img.shields.io/pypi/v/mkdocs-exporter?color=blue">
  </a>
  <a href="https://pypi.org/project/mkdocs-exporter">
    <img src="https://img.shields.io/pypi/pyversions/mkdocs-exporter?color=blue">
  </a>
  <a href="https://pypi.org/project/mkdocs-exporter">
    <img src="https://img.shields.io/pypi/dm/mkdocs-exporter?color=blue">
  </a>
  <a href="https://github.com/adrienbrignon/mkdocs-exporter/blob/master/LICENSE">
    <img align="right" src="https://img.shields.io/github/license/adrienbrignon/mkdocs-exporter?color=white">
  </a>
</div>
<a href="https://adrienbrignon.github.io/mkdocs-exporter/getting-started/">
  <img src="https://github.com/adrienbrignon/mkdocs-exporter/assets/10183277/85c768f6-fe27-43a1-998c-ac89e926cba1" align="right" width="350">
</a>
<br />

A highly configurable plugin for [*MkDocs*](https://github.com/mkdocs/mkdocs) that exports your pages as PDF documents.  
Additionally, it can combine your entire documentation into a single PDF file.

- [Documentation](https://adrienbrignon.github.io/mkdocs-exporter)
- [PyPI](https://pypi.org/project/mkdocs-exporter)
- [Examples](./examples)

## Features

- 🚀 **Fast** - All PDF documents are generated concurrently!
- 🎨 **Customizable** - full control over the resulting documents
  - Combine all your pages into a single PDF document
  - Create [cover pages](https://adrienbrignon.github.io/mkdocs-exporter/setup/setting-up-documents/#setting-up-cover-pages)
  - Define custom scripts and stylesheets to customize your PDF documents
  - Add [buttons](https://adrienbrignon.github.io/mkdocs-exporter/setup/setting-up-buttons/) to the top of your pages ([example](https://adrienbrignon.github.io/mkdocs-exporter/setup/setting-up-buttons/))
  - Compatible with [`material`](https://github.com/squidfunk/mkdocs-material) and [`readthedocs`](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) themes
    - Check out sample PDF documents [here](./examples/themes)
- ⭐ **Powerful** - it uses a headless browser and some awesome libraries under the hood to generate PDF documents
  - [*Playwright*](https://github.com/microsoft/playwright-python) to automate browsers
  - [*Paged.js*](https://github.com/pagedjs/pagedjs) polyfills included (provide [Paged Media](https://www.w3.org/TR/css-page-3/) and [Generated Content](https://www.w3.org/TR/css-gcpm-3/) CSS modules)
  - [*Sass*](https://sass-lang.com/) support included for your stylesheets

## Prerequisites

- Python `>= 3.9`
- MkDocs `>= 1.4`

## Installation

The plugin is hosted on [*PyPI*](https://pypi.org/project/mkdocs-exporter/) and can be installed via `pip` (or your favourite package manager):

```bash
pip install mkdocs-exporter
```

## Usage

The following configuration excerpt from the [`mkdocs.yml`](./mkdocs.yml) configuration file used by this documentation should cover the basic functionalities of this plugin:

```yaml
plugins:
  - exporter:
      formats:
        pdf:
          enabled: !ENV [MKDOCS_EXPORTER_PDF, true]
          concurrency: 8
          stylesheets:
            - resources/stylesheets/pdf.scss
          covers:
            front: resources/templates/covers/front.html.j2
            back: resources/templates/covers/back.html.j2
          aggregator:
            enabled: true
            output: .well-known/site.pdf
            covers: all
```

Check out a [sample PDF generated by this plugin](examples/example.pdf), it includes custom CSS and features cover pages.

## Roadmap

- [x] Combine all pages into a single PDF document (✅ released in [`v6.0.0`](https://github.com/adrienbrignon/mkdocs-exporter/releases/tag/v6.0.0))
- [ ] Create a *GitHub* action that includes all dependencies to build the documentation and generate PDF documents

Feel free to request additional features by submitting an issue or contributing through a pull request.

## Contributing

We welcome contributions from the community to enhance MkDocs Exporter.  
Whether you want to report a bug, suggest a feature, improve the documentation, or contribute code, your help is appreciated!

## License

This project is licensed under the `MIT License (MIT)`, which you can read [here](LICENSE).
