Version 6

.gitattributes

@@ -1 +1 @@
-mkdocs_exporter/resources/**/* -diff
+mkdocs_exporter/**/resources/**/* -diff

.github/workflows/lint.yml

@@ -3,8 +3,6 @@ name: Lint
 on:
   workflow_dispatch:
   push:
-    branches:
-      - master
 
 env:
   PYTHON_VERSION: '3.12'

Dockerfile

@@ -21,7 +21,7 @@ RUN apt-get update \
 
 FROM base as builder
 
-ENV POETRY_VERSION=1.8.2 \
+ENV POETRY_VERSION=1.8.3 \
     PIP_NO_CACHE_DIR=1 \
     PIP_DEFAULT_TIMEOUT=100 \
     PIP_DISABLE_PIP_VERSION_CHECK=1
@@ -42,6 +42,6 @@ RUN . .venv/bin/activate \
  && make build
 
 
-FROM docker.io/nginx:1.25.4
+FROM docker.io/nginx:1.27.0
 
 COPY --from=builder /usr/src/app/dist /usr/share/nginx/html

README.md

@@ -19,29 +19,31 @@
 </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)
 - [Examples](./examples)
 
 ## Features
 
-- 🚀 **Fast** - PDF documents are generated concurrently!
+- 🚀 **Fast** - All 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)
+  - 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
-  - [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/))
   - 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,39 @@ 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))
+- [ ] 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
 
-Feel free to request additional features by submitting an issue or by contributing through a pull request.
+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
 

docs/.pages

@@ -1,5 +1,5 @@
 nav:
   - getting-started.md
-  - setup
+  - configuration
   - reference
   - samples

docs/assets/stylesheets/custom.css

@@ -13,6 +13,12 @@
   }
 }
 
+@page {
+  @bottom-center {
+    content: 'Page ' counter(page) ' of ' counter(pages);
+  }
+}
+
 .md-icon-spin {
   animation-name: spin;
   animation-duration: 3s;
@@ -29,3 +35,28 @@
   border-radius: 0.50em;
   border: 1px solid #ddd;
 }
+
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+a.external::after,
+a.autorefs-external::after {
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: currentColor;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}

docs/configuration/.pages

@@ -0,0 +1,4 @@
+nav:
+  - generating-pdf-documents.md
+  - adding-buttons-to-pages.md
+  - ...

docs/configuration/adding-buttons-to-pages.md

@@ -0,0 +1,87 @@
+---
+buttons:
+  - title: I'm Feeling Lucky
+    icon: material-star-outline
+    attributes:
+      class: md-content__button md-icon md-icon-spin
+      href: https://www.youtube.com/watch?v=dQw4w9WgXcQ
+      target: _blank
+---
+
+# Adding buttons to pages
+
+You can define custom buttons at the top of your pages.
+
+!!! example "Try it out"
+
+    A custom button is featured on this page, check it out!  
+    You can find its configuration [below](#adding-buttons-to-a-specific-page).
+
+## Usage
+
+### Adding a download button
+
+The following configuration excerpt will add a download button to pages that have a PDF document:
+
+```yaml
+plugins:
+  - exporter:
+      buttons:
+        - title: Download as PDF
+          icon: material-file-download-outline
+          enabled: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.enabled
+          attributes: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.attributes
+```
+
+### Defining a dynamic button
+
+As you saw in the previous example, Python functions can be used to dynamically resolve button attributes.  
+Now, let's write a button that, when clicked, initiates a Google search using the current page's title as the query.
+
+To begin with, let's write the function that will return the button's `href` attribute:
+
+```python
+from urllib.parse import urlencode
+from mkdocs_exporter.page import Page
+
+def href(page: Page, **kwargs) -> str:
+  """The button's 'href' attribute."""
+
+  return 'https://google.com/search?' + urlencode({'q': page.title})
+```
+
+Next, we can define the button and specify the path to the function previously defined (assuming it has been saved in the `button.py` file under the `my_module` module):
+
+```yaml
+plugins:
+  - exporter:
+      buttons:
+        - title: Download as PDF
+          icon: material-file-download-outline
+          attributes:
+            href: !!python/name:my_module.button.href
+```
+
+Repeat this process as needed; you can apply this method to any property of a button.
+
+### Adding buttons to a specific page
+
+You can add buttons to pages using the buttons field in your page's front matter, enabling you to define buttons specific to each page.
+
+Here's how it's configured for this page:
+
+```yaml
+---
+{% set button = page.meta.buttons[0] -%}
+
+buttons:
+  - title: {{ button.title }}
+    icon: {{ button.icon }}
+    attributes:
+      class: {{ button.attributes.class }}
+      href: {{ button.attributes.href }}
+      target: {{ button.attributes.target }}
+---
+
+# {{ page.title }}
+```