diff --git a/docs/customization.md b/docs/customization.md new file mode 100644 index 0000000..b94c092 --- /dev/null +++ b/docs/customization.md @@ -0,0 +1,60 @@ +# Customization + +You might want to customize your site to include a 'print' button on every page (like the one in the right corner of this page 👆) + +MkDocs supports [theme extension](https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir), an easy way to override parts of a theme. +You can use `page.url_to_print_page` to get the link to the site print page. + +## Adding a print button to mkdocs-material theme + +In `mkdocs-material` theme (see [customization](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks)), first create a directory for overrides and update your `mkdocs.yml`: + +```yml +theme: + name: material + custom_dir: docs/overrides +``` + +You can create the file `docs/overrides/main.html` as follows: + +``` +{% extends "base.html" %} + +{% block content %} +{% if page.url_to_print_page %} + + {% include ".icons/material/printer.svg" %} + +{% endif %} + +{{ super() }} +{% endblock content %} +``` + +## Adding a print button to mkdocs theme + +You can also [customize](https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme) the base mkdocs theme, by first creating an `overrides` directory: + +```yml +theme: + name: mkdocs + custom_dir: docs/overrides +``` + +And then adding a file `docs/overrides/main.html` with the following content: + +```html +{% extends "base.html" %} + +{% block repo %} + {% if page.url_to_print_page %} + + {% endif %} + +{{ super() }} +{% endblock repo %} +``` diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 0000000..d40335f --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,11 @@ +{% extends "base.html" %} + +{% block content %} +{% if page.url_to_print_page %} + + {% include ".icons/material/printer.svg" %} + +{% endif %} + +{{ super() }} +{% endblock content %} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e7165ce..d3533fe 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,11 +17,13 @@ plugins: nav: - Home: index.md - Options: options.md + - Customization: customization.md - Demo Content: demo_content.md - Contributing: contributing.md theme: name: material + custom_dir: docs/overrides palette: primary: indigo accent: blue diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index 09b1ee8..b2ef7a8 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -116,6 +116,10 @@ def on_page_context(self, context, page, config, nav): # And apply it to the print page as well (in on_post_build event) self.context = context + # Save relative link to print page + # This can be used to customize a theme and add a print button to each page + page.url_to_print_page = self.print_file.url_relative_to(page.file) + def on_post_build(self, config): # Add javascript file diff --git a/setup.py b/setup.py index 97faba3..b12400f 100644 --- a/setup.py +++ b/setup.py @@ -9,7 +9,7 @@ setup( name="mkdocs-print-site-plugin", - version="0.5.1", + version="0.5.2", description="MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to *File > Print > Save as PDF* the entire site.", long_description=long_description, long_description_content_type="text/markdown",