docs: updated documentation

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

@@ -81,6 +81,7 @@ Check out a [sample PDF generated by this plugin](examples/example.pdf), it incl
 ## 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.
 

docs/.pages

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

docs/assets/stylesheets/custom.css

@@ -29,3 +29,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 }}
+```