feat: misc. fixes and enhancements

- Improved error handling when compiling SCSS files
- Fixed issues when using old plugin name (such as `mkdocs/exporter/extras`)
- Improved documentation
  - Enabled social cards
  - Minor documentation enhancements
- Updated dependencies

Makefile

@@ -2,7 +2,7 @@ ifeq ($(origin .RECIPEPREFIX), undefined)
   $(error This Make does not support .RECIPEPREFIX. Please use GNU Make 4.0 or later)
 endif
 
-PDF = false
+PDF = true
 DEBUG = false
 
 .RECIPEPREFIX = >
@@ -17,10 +17,10 @@ browser:
 > poetry run playwright install $(if $(FORCE),--force,) --with-deps
 
 build:
->@ poetry run mkdocs build
+>@ MKDOCS_EXPORTER_PDF=$(PDF) poetry run mkdocs build
 
 serve:
->@ poetry run mkdocs serve
+>@ MKDOCS_EXPORTER_PDF=$(PDF) poetry run mkdocs serve
 
 clean:
 > $(RM) -rf dist/

docs/setup/setting-up-documents.md

@@ -39,9 +39,11 @@ plugins:
     This architecture reduces code duplication and maintains a generic base that can be used to export
     your pages to formats other than PDF (although this is currently the only format supported).
 
-    To sum things up, the `exporter` should always be registered first as it provides a common ground for
+    To sum things up, the `exporter` plugin should always be registered first as it provides a common ground for
     other plugins to rely on.
 
+<div class="page-break"></div>
+
 ## Usage
 
 ### Toggling documents generation
@@ -67,8 +69,6 @@ Here's how cover pages are set up for this documentation.
 
     The following examples use the [`macros`](https://github.com/fralau/mkdocs_macros_plugin) plugin for *extra powerful* pages.
 
-<div class="page-break"></div>
-
 === "`mkdocs.yml`"
 
     ```yaml
@@ -86,6 +86,8 @@ Here's how cover pages are set up for this documentation.
 
     > :material-file-code: See the full content of this file [here](https://github.com/adrienbrignon/mkdocs-exporter/blob/master/mkdocs.yml).
 
+<div class="page-break"></div>
+
 === "`resources/templates/covers/front.html.j2`"
 
     ```html
@@ -129,6 +131,8 @@ Here's how cover pages are set up for this documentation.
 
     > :material-file-code: See the full content of this file [here](https://github.com/adrienbrignon/mkdocs-exporter/blob/master/resources/stylesheets/pdf.scss).
 
+<div class="page-break"></div>
+
 ### Increasing concurrency
 
 PDF are, by default, generated concurrently which greatly reduces the overall build time.  

mkdocs.yml

@@ -23,10 +23,12 @@ theme:
     - navigation.footer
     - navigation.indexes
     - navigation.instant
+    - navigation.instant.progress
     - navigation.sections
     - navigation.tabs
     - navigation.top
     - navigation.tracking
+    - navigation.prune
     - toc.follow
 
 extra:
@@ -42,6 +44,7 @@ plugins:
   - exporter:
   - exporter-pdf:
       concurrency: 16
+      enabled: !ENV [MKDOCS_EXPORTER_PDF, true]
       stylesheets:
         - resources/stylesheets/pdf.scss
       covers:
@@ -72,6 +75,9 @@ plugins:
         'index.md': 'getting-started.md'
   - minify:
       minify_html: true
+  - social:
+      cards_layout_options:
+        background_color: '#EA2027'
 
 markdown_extensions:
   - admonition

mkdocs_exporter/plugin.py

@@ -67,18 +67,18 @@ def on_post_build(self, **kwargs) -> None:
       content = None
 
       with open(stylesheet.abs_dest_path, 'r', encoding='utf-8') as reader:
-        content = self.theme.stylesheet(reader.read())
+        content = self.theme.stylesheet(stylesheet, reader.read())
       with open(stylesheet.abs_dest_path, 'w+', encoding='utf-8') as writer:
         writer.write(content)
 
 
-class PluginDeprecated(Plugin):
+class DeprecatedPlugin(Plugin):
   """Deprecated plugin, will be removed in the next major release."""
 
 
-  def on_config(self, config: dict) -> None:
+  def on_config(self, config: dict, **kwargs) -> None:
     """Invoked when the configuration has been loaded."""
 
     logger.warning("The plugin name 'mkdocs/exporter' will stop working soon, please replace it with 'exporter'")
 
-    super().on_config(config)
+    super().on_config(config, **kwargs)

mkdocs_exporter/plugins/extras/plugin.py

@@ -12,6 +12,12 @@ class Plugin(BasePlugin[Config]):
   """The plugin."""
 
 
+  def on_config(self, *args, **kwargs) -> None:
+    """Invoked when the configuration has been loaded."""
+
+    pass
+
+
   @event_priority(-85)
   def on_post_page(self, html: str, page: Page, config: dict, **kwargs) -> Optional[str]:
     """Invoked after a page has been built."""
@@ -40,13 +46,13 @@ def resolve(object):
     return preprocessor.done()
 
 
-class PluginDeprecated(Plugin):
+class DeprecatedPlugin(Plugin):
   """Deprecated plugin, will be removed in the next major release."""
 
 
-  def on_config(self, config: dict) -> None:
+  def on_config(self, *args, **kwargs) -> None:
     """Invoked when the configuration has been loaded."""
 
     logger.warning("The plugin name 'mkdocs/exporter/extras' will stop working soon, please replace it with 'exporter-extras'")
 
-    super().on_config(config)
+    super().on_config(*args, **kwargs)

mkdocs_exporter/plugins/pdf/plugin.py

@@ -170,13 +170,13 @@ def _enabled(self, page: Page = None) -> bool:
     return True
 
 
-class PluginDeprecated(Plugin):
+class DeprecatedPlugin(Plugin):
   """Deprecated plugin, will be removed in the next major release."""
 
 
-  def on_config(self, config: dict) -> None:
+  def on_config(self, config: dict, **kwargs) -> None:
     """Invoked when the configuration has been loaded."""
 
     logger.warning("The plugin name 'mkdocs/exporter/pdf' will stop working soon, please replace it with 'exporter-pdf'")
 
-    super().on_config(config)
+    super().on_config(config, **kwargs)

mkdocs_exporter/plugins/pdf/renderer.py

@@ -65,7 +65,7 @@ def preprocess(self, page: Page) -> str:
         preprocessor.stylesheet(file.read())
     for script in self.scripts:
       with open(script, 'r', encoding='utf-8') as file:
-        preprocessor.script(file.read())
+        preprocessor.script(file.read(), path=stylesheet)
 
     preprocessor.script(importlib_resources.files(js).joinpath('pdf.js').read_text(encoding='utf-8'))
     preprocessor.script(importlib_resources.files(js).joinpath('pagedjs.min.js').read_text(encoding='utf-8'))

mkdocs_exporter/preprocessor.py

@@ -4,6 +4,7 @@
 import sass
 
 from typing import Union
+from sass import CompileError
 from urllib.parse import urlparse
 from bs4 import BeautifulSoup, Tag
 
@@ -46,7 +47,7 @@ def teleport(self) -> Preprocessor:
     """Teleport elements to their destination."""
 
     for element in self.html.select('*[data-teleport]'):
-      selector = element.attrs['data-teleport']
+      selector = element.attrs.get('data-teleport')
       destination = self.html.select_one(selector)
       tag = Tag(None, name=element.name, attrs=element.attrs)
 
@@ -58,8 +59,7 @@ def teleport(self) -> Preprocessor:
 
         continue
 
-      element.attrs['data-teleport'] = None
-
+      element.attrs.pop('data-teleport', None)
       destination.append(element)
 
     return self
@@ -89,7 +89,15 @@ def script(self, script: str = None, type: str = 'text/javascript', **kwargs) ->
   def stylesheet(self, stylesheet: str, **kwargs) -> Preprocessor:
     """Appends a stylesheet to the document's head."""
 
-    css = sass.compile(string=stylesheet, output_style='compressed')
+    css = None
+
+    try:
+      css = sass.compile(string=stylesheet, output_style='compressed')
+    except CompileError as error:
+      logger.error(error)
+
+      return self
+
     element = self.html.new_tag('style', type='text/css', rel='stylesheet', **kwargs)
 
     element.string = css

mkdocs_exporter/resources/js/pdf.js

@@ -16,7 +16,7 @@ window.PagedConfig = {
         try {
           await window.MkDocsExporter.render(this);
         } catch (error) {
-          console.error('[mkdocs-exporter] Failed to invoke render function', error);
+          console.error('[mkdocs-exporter] Failed to invoke render function:', error);
         }
       }
     }
@@ -27,6 +27,6 @@ window.PagedConfig = {
    */
   after: () => {
     document.body.setAttribute('mkdocs-exporter', 'true');
-  },
+  }
 
 };

mkdocs_exporter/theme.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 from abc import abstractmethod
+from mkdocs.structure.files import File
 from mkdocs.theme import Theme as BaseTheme
 
 
@@ -26,7 +29,7 @@ def button(self, preprocessor, title: str, icon: str, attributes: dict = {}):
     raise NotImplementedError()
 
 
-  def stylesheet(self, css: str) -> str:
+  def stylesheet(self, stylesheet: File, content: str) -> str:
     """Transforms a stylesheet."""
 
-    return css
+    return content

mkdocs_exporter/themes/readthedocs/theme.py

@@ -3,6 +3,8 @@
 
 import importlib_resources
 
+from mkdocs.structure.files import File
+
 from mkdocs_exporter.resources import css
 from mkdocs_exporter.theme import Theme as BaseTheme
 from mkdocs_exporter.preprocessor import Preprocessor
@@ -37,7 +39,7 @@ def icon(self, name: str):
     return None
 
 
-  def stylesheet(self, css: str) -> str:
+  def stylesheet(self, stylesheet: File, content: str) -> str:
     """Transforms a stylesheet."""
 
-    return css.replace(':nth-of-type(3n+1)', ':nth-of-type(3n)')
+    return content.replace(':nth-of-type(3n+1)', ':nth-of-type(3n)')