chore: merge pull request #29 from adrienbrignon/develop

Releases `v6.1.0`

.github/workflows/documentation.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 1
+          fetch-depth: 0
       - name: Set up Poetry
         run: |
           pipx install poetry

.github/workflows/lint.yml

@@ -8,8 +8,8 @@ env:
   PYTHON_VERSION: '3.12'
 
 jobs:
-  lint:
-    name: Lint source code
+  flake8:
+    name: Flake8
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -33,6 +33,6 @@ jobs:
         run: |
           pip install poetry
           make install
-      - name: Run linter
+      - name: Run Flake8
         run: |
           poetry run flake8

.github/workflows/security.yml

@@ -0,0 +1,38 @@
+name: Security
+
+on:
+  workflow_dispatch:
+  push:
+
+env:
+  PYTHON_VERSION: '3.12'
+
+jobs:
+  bandit:
+    name: Bandit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+      - name: Set up Poetry
+        run: |
+          pipx install poetry
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: poetry
+      - name: Set up Poetry environment
+        env:
+          PYTHON_VERSION: ${{ env.PYTHON_VERSION }}
+        run: |
+          poetry env use ${PYTHON_VERSION}
+      - name: Install Python dependencies
+        run: |
+          pip install poetry
+          make install
+      - name: Run Bandit
+        run: |
+          poetry run bandit -r mkdocs_exporter

Makefile

@@ -3,6 +3,7 @@ ifeq ($(origin .RECIPEPREFIX), undefined)
 endif
 
 PDF = true
+PDF_AGGREGATOR = true
 DEBUG = false
 
 .RECIPEPREFIX = >
@@ -17,10 +18,10 @@ browser:
 > poetry run playwright install $(if $(FORCE),--force,) --with-deps
 
 build:
->@ MKDOCS_EXPORTER_PDF=$(PDF) poetry run mkdocs build
+>@ MKDOCS_EXPORTER_PDF=$(PDF) MKDOCS_EXPORTER_PDF_AGGREGATOR=$(PDF_AGGREGATOR) poetry run mkdocs build
 
 serve:
->@ MKDOCS_EXPORTER_PDF=$(PDF) poetry run mkdocs serve
+>@ MKDOCS_EXPORTER_PDF=$(PDF) MKDOCS_EXPORTER_PDF_AGGREGATOR=$(PDF_AGGREGATOR) poetry run mkdocs serve
 
 clean:
 > $(RM) -rf dist/

docs/configuration/generating-pdf-documents.md

@@ -251,4 +251,18 @@ plugins:
           aggregator:
             enabled: true
             output: documentation.pdf
+            covers: all
 ```
+
+#### Configuring cover pages behavior
+
+When aggregating PDF documents, you have the flexibility to configure the behavior of cover pages to suit your needs.  
+There are five available options for managing cover pages:
+
+- `all` (*default*): retains every cover page from all documents.
+- `none`: removes every cover page from the aggregated document, resulting in a compilation that includes only the main content of each PDF.
+- `limits`: retains the front cover of the first document and the back cover of the last document, while removing all other cover pages in between.
+- `front`: preserves every front cover page from all documents but removes all back cover pages.
+- `back`: preserves every back cover page from all documents but removes all front cover pages.
+
+Choose the behavior that best aligns with your document aggregation needs to ensure the final PDF meets your requirements.

docs/getting-started.md

@@ -3,8 +3,6 @@ hide:
   - navigation
 ---
 
-<div class="mkdocs-exporter" style="display: none;"></div>
-
 # Getting started
 
 ## Introduction
@@ -39,4 +37,4 @@ plugins:
   - exporter
 ```
 
-Check out the [configuration guides](configuration/generating-pdf-documents) for more details about how to use and configure the plugin.
+Check out the [configuration guides](../configuration/generating-pdf-documents) for more details about how to use and configure the plugin.

mkdocs.yml

@@ -47,7 +47,6 @@ extra:
 
 plugins:
   - privacy:
-      log_level: warn
   - mkdocstrings:
       handlers:
         python:
@@ -76,6 +75,9 @@ plugins:
   - social:
       cards_layout_options:
         background_color: '#EA2027'
+  - git-committers:
+      repository: adrienbrignon/mkdocs-exporter
+      branch: master
   - exporter:
       logging:
         level: debug
@@ -87,13 +89,13 @@ plugins:
             - resources/stylesheets/pdf.scss
           covers:
             front: resources/templates/covers/front.html.j2
+            back: resources/templates/covers/back.html.j2
           browser:
             debug: false
-            headless: true
           aggregator:
-            enabled: true
+            enabled: !ENV [MKDOCS_EXPORTER_PDF_AGGREGATOR, true]
             output: documentation.pdf
-            covers: limits
+            covers: front
       buttons:
         - title: View as PDF
           icon: material-file-move-outline
@@ -134,13 +136,13 @@ markdown_extensions:
 
 extra_css:
   - assets/stylesheets/custom.css
-  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css
 
 extra_javascript:
   - assets/scripts/katex.js
   - assets/scripts/mathjax.js
   - assets/scripts/mkdocs-exporter.js
-  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js
-  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/auto-render.min.js
   - https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.2/es5/tex-mml-chtml.min.js
-  - https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.6.1/mermaid.min.js
+  - https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js

mkdocs_exporter/formats/pdf/aggregator.py

@@ -4,6 +4,7 @@
 
 from pypdf import PdfWriter
 
+from mkdocs_exporter.page import Page
 from mkdocs_exporter.formats.pdf.renderer import Renderer
 from mkdocs_exporter.formats.pdf.preprocessor import Preprocessor
 
@@ -12,10 +13,11 @@ class Aggregator:
   """Aggregates PDF documents together."""
 
 
-  def __init__(self, renderer: Renderer):
+  def __init__(self, renderer: Renderer, config: dict = {}) -> None:
     """The constructor."""
 
-    self.total_pages = 0
+    self.pages = []
+    self.config = config
     self.renderer = renderer
 
 
@@ -25,20 +27,50 @@ def open(self, path: str) -> Aggregator:
     self.path = path
     self.writer = PdfWriter()
 
+    return self
+
+
+  def set_pages(self, pages: list[Page]) -> Aggregator:
+    """Sets the pages."""
 
-  def increment_total_pages(self, total_pages: int) -> Aggregator:
-    """Increments the total pages count."""
+    self.pages = pages
+    covers = self.config.get('covers', [])
 
-    self.total_pages = self.total_pages + total_pages
+    for index, page in enumerate(self.pages):
+      if covers == 'none':
+        self._skip(page, ['front', 'back'])
+      elif covers == 'front':
+        self._skip(page, ['back'])
+      elif covers == 'back':
+        self._skip(page, ['front'])
+      elif covers == 'limits':
+        if index == 0:
+          self._skip(page, ['back'])
+        elif index == (len(self.pages) - 1):
+          self._skip(page, ['front'])
+        else:
+          self._skip(page, ['front', 'back'])
+
+    return self
 
 
-  def preprocess(self, html: str, page_number: int = 1) -> str:
+  def preprocess(self, page: Page) -> str:
     """Preprocesses the page."""
 
     preprocessor = Preprocessor()
 
-    preprocessor.preprocess(html)
-    preprocessor.metadata({'page': page_number, 'pages': self.total_pages})
+    preprocessor.preprocess(self.renderer.preprocess(page, disable=['teleport']))
+
+    if 'front' not in page.formats['pdf']['covers']:
+      preprocessor.remove('div.mkdocs-exporter-front-cover')
+    if 'back' not in page.formats['pdf']['covers']:
+      preprocessor.remove('div.mkdocs-exporter-back-cover')
+
+    preprocessor.teleport()
+    preprocessor.metadata({
+      'page': sum(page.formats['pdf']['pages'] - page.formats['pdf']['skipped_pages'] for page in self.pages[:page.index]),
+      'pages': sum(page.formats['pdf']['pages'] - page.formats['pdf']['skipped_pages'] for page in self.pages),
+    })
 
     return preprocessor.done()
 
@@ -63,3 +95,14 @@ def save(self, metadata={}) -> Aggregator:
     self.writer = None
 
     return self
+
+
+  def _skip(self, page: Page, covers: list[str]) -> Aggregator:
+    """Skip cover pages."""
+
+    for cover in covers:
+      if cover in page.formats['pdf']['covers']:
+        page.formats['pdf']['covers'].remove(cover)
+        page.formats['pdf']['skipped_pages'] = page.formats['pdf']['skipped_pages'] + 1
+
+    return self

mkdocs_exporter/formats/pdf/browser.py

@@ -15,7 +15,8 @@ class Browser:
   args = [
     '--disable-background-timer-throttling',
     '--disable-renderer-backgrounding',
-    '--allow-file-access-from-files'
+    '--allow-file-access-from-files',
+    '--font-render-hinting=none'
   ]
   """The browser's arguments..."""
 
@@ -38,6 +39,7 @@ def __init__(self, options: dict = {}):
     self.debug = options.get('debug', False)
     self.headless = options.get('headless', True)
     self.timeout = options.get('timeout', 60_000)
+    self.args = self.args + options.get('args', [])
     self.levels = {
       'warn': 'warning',
       'error': 'error',
@@ -100,13 +102,10 @@ async def print(self, html: str) -> tuple[bytes, int]:
     pages = int(await context.locator('body').get_attribute('mkdocs-exporter-pages') or 0)
     pdf = await context.pdf(prefer_css_page_size=True, print_background=True, display_header_footer=False)
 
-    try:
-      os.unlink(file)
-    except Exception:
-      pass
-
     await context.close()
 
+    os.unlink(file.name)
+
     return (pdf, pages)
 
 

mkdocs_exporter/formats/pdf/config.py

@@ -14,6 +14,9 @@ class BrowserConfig(BaseConfig):
   timeout = c.Type(int, default=60_000)
   """The timeout when waiting for the PDF to render."""
 
+  args = c.ListOfItems(c.Type(str), default=[])
+  """Extra arguments to pass to the browser."""
+
 
 class CoversConfig(BaseConfig):
   """The cover's configuration."""
@@ -26,6 +29,7 @@ class CoversConfig(BaseConfig):
 
 
 class AggregatorConfig(BaseConfig):
+  """The aggregator's configuration."""
 
   enabled = c.Type(bool, default=False)
   """Is the aggregator enabled?"""
@@ -36,6 +40,9 @@ class AggregatorConfig(BaseConfig):
   metadata = c.Type(dict, default={})
   """Some metadata to append to the PDF document."""
 
+  covers = c.Choice(['all', 'none', 'limits', 'front', 'back'], default='all')
+  """The behavior of cover pages."""
+
 
 class Config(BaseConfig):
   """The plugin's configuration."""