Skip to content

Commit

Permalink
chore: updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
adrienbrignon committed Jun 2, 2024
1 parent b3953aa commit 57b849c
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 38 deletions.
65 changes: 28 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@
</a>
<br />

A highly-configurable plugin for [*MkDocs*](https://github.com/mkdocs/mkdocs) that exports your pages to PDF files.
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)
Expand All @@ -29,19 +30,20 @@ A highly-configurable plugin for [*MkDocs*](https://github.com/mkdocs/mkdocs) th

- 🚀 **Fast** - PDF documents are generated concurrently!
- 🎨 **Customizable** - full control over the resulting documents
- [Cover pages](https://adrienbrignon.github.io/mkdocs-exporter/setup/setting-up-documents/#setting-up-cover-pages) (supports [`macros`](https://github.com/fralau/mkdocs_macros_plugin) plugin)
- 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
- [Define "buttons"](https://adrienbrignon.github.io/mkdocs-exporter/setup/setting-up-buttons/) at the top of your documentation pages ([example](https://adrienbrignon.github.io/mkdocs-exporter/setup/setting-up-buttons/))
- 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/))
- Combine all your pages into a single PDF document
- Compatible with [`material`](https://github.com/squidfunk/mkdocs-material) and [`readthedocs`](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) themes
- Check out some sample PDF documents [here](./examples/themes)
-**Powerful** - it uses a headless browser and some awesome libraries under the hood to generate PDF files
- 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 are included ([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 (via [`libsass`](https://github.com/sass/libsass-python)) for your stylesheets
- [*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.8`
- Python `>= 3.9`
- MkDocs `>= 1.4`

## Installation
Expand All @@ -54,44 +56,33 @@ pip install mkdocs-exporter

## Usage

Three plugins are currently available:

- `exporter` (*required*): base plugin which must precede the others
- `exporter-pdf` (*optional*): plugin that exports your pages as individual PDF documents
- `exporter-extras` (*optional*): provides extra functionalities (buttons, HTML utilities...)

### Example

The following configuration excerpt from [`mkdocs.yml`](./mkdocs.yml) should cover the basic functionalities of this plugin:
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
- exporter-pdf:
concurrency: 8
covers:
front: resources/templates/covers/front.html.j2
back: resources/templates/covers/back.html.j2
stylesheets:
- resources/stylesheets/pdf.scss
- exporter-extras:
buttons:
- title: Download as PDF
enabled: !!python/name:mkdocs_exporter.plugins.pdf.button.enabled
icon: !!python/name:mkdocs_exporter.plugins.pdf.button.icon
attributes:
href: !!python/name:mkdocs_exporter.plugins.pdf.button.href
download: !!python/name:mkdocs_exporter.plugins.pdf.button.download
- 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) from the default page of the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material) theme.
It has been built with some custom CSS and features cover pages.
Check out a [sample PDF generated by this plugin](examples/example.pdf), it includes custom CSS and features cover pages.
## Roadmap
- Combine all pages as one PDF
- [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))

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

## License

Expand Down
2 changes: 1 addition & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,8 @@ plugins:
- exporter:
formats:
pdf:
concurrency: 16
enabled: !ENV [MKDOCS_EXPORTER_PDF, true]
concurrency: 16
stylesheets:
- resources/stylesheets/pdf.scss
covers:
Expand Down

0 comments on commit 57b849c

Please sign in to comment.