From 57b849cffbf1c480522d246d14646cfaa1185d66 Mon Sep 17 00:00:00 2001 From: Adrien Brignon Date: Sun, 2 Jun 2024 15:15:58 +0200 Subject: [PATCH] chore: updated README --- README.md | 65 +++++++++++++++++++++++------------------------------- mkdocs.yml | 2 +- 2 files changed, 29 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 66339a7..68d6eba 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@
-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) @@ -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 @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml index 5f10331..24dc450 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,8 +61,8 @@ plugins: - exporter: formats: pdf: - concurrency: 16 enabled: !ENV [MKDOCS_EXPORTER_PDF, true] + concurrency: 16 stylesheets: - resources/stylesheets/pdf.scss covers: