feat(aggregator): enhancements and fixes

- The path of the aggregate PDF document is now configurable
- Covers behaviour is now configurable
  - 'none' to omit them
  - 'limits' to include only the first and last one
  - 'all' to include them all
- No longer writing the aggregated PDF document if it does not contain any pages

mkdocs.yml

@@ -55,6 +55,8 @@ plugins:
         headless: true
   - exporter-aggregator:
       enabled: true
+      output: .well-known/document.pdf
+      covers: limits
   - exporter-extras:
       buttons:
         - title: Download as PDF

mkdocs_exporter/plugins/aggregator/config.py

@@ -8,8 +8,11 @@ class Config(BaseConfig):
   enabled = c.Type(bool, default=True)
   """Is the plugin enabled?"""
 
-  stylesheets = c.ListOfItems(c.File(exists=True), default=[])
-  """A list of custom stylesheets to apply before rendering documents."""
+  metadata = c.Type(dict, default={})
+  """The metadata to append to the PDF."""
 
-  scripts = c.ListOfItems(c.File(exists=True), default=[])
-  """A list of custom scripts to inject before rendering documents."""
+  output = c.Type(str, default='site.pdf')
+  """The output file path."""
+
+  covers = c.Choice(['all', 'none', 'limits'], default='all')
+  """The way that cover pages will be handled."""

mkdocs_exporter/plugins/aggregator/plugin.py

@@ -40,22 +40,31 @@ def on_post_build(self, config, **kwargs):
     logger.info('[mkdocs-exporter.aggregator] Generating aggregated PDF document...')
 
     aggregate = PdfWriter()
-    destination = os.path.join(config['site_dir'], 'aggregate.pdf')
+    destination = os.path.join(config['site_dir'], self.config['output'])
+
+    os.makedirs(os.path.dirname(destination), exist_ok=True)
 
     for n, page in enumerate(self.pages):
       if 'pdf' not in page.formats:
         continue
 
       pages = None
       pdf = os.path.join(config['site_dir'], page.formats['pdf']['path'])
+      total = len(PdfReader(pdf).pages)
 
       if 'covers' in page.formats['pdf']:
-        pages = (0 if n == 0 else 1, len(PdfReader(pdf).pages) - (0 if n == (len(self.pages) - 1) else 1))
+        covers = page.formats['pdf']['covers']
+
+        if self.config['covers'] == 'none':
+          pages = (1 if covers['front'] else 0, (total - 1) if covers['back'] else total)
+        if self.config['covers'] == 'limits':
+          pages = (1 if n != 0 and covers['front'] else 0, (total - 1) if n != (len(self.pages) - 1) and covers['back'] else total)
 
       aggregate.append(pdf, pages=pages)
 
-    aggregate.add_metadata({'/Producer': 'MkDocs Exporter'})
-    aggregate.write(destination)
-    aggregate.close()
+    if len(aggregate.pages) > 0:
+      aggregate.add_metadata({'/Producer': 'MkDocs Exporter', **self.config['metadata']})
+      aggregate.write(destination)
+      logger.info("[mkdocs-exporter.aggregator] Aggregated PDF document written to '%s'!", destination)
 
-    logger.info("[mkdocs-exporter.aggregator] Aggregated PDF document written to '%s'!", destination)
+    aggregate.close()