Merge pull request #54 from timvink/version2

Version2

.github/workflows/pythonpublish.yml

@@ -8,9 +8,9 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v2
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v2
       with:
         python-version: '3.x'
     - name: Install dependencies
@@ -29,3 +29,7 @@ jobs:
       run: |
         python setup.py sdist bdist_wheel
         twine upload dist/*
+    - name: Deploy mkdocs site
+      run: | 
+        mkdocs gh-deploy --force
+

.gitignore

@@ -1,6 +1,10 @@
 
 docs/assets/*.pdf
+*.pdf
 
+# nodejs stuff
+package-lock.json
+package.json
 
 .vscode/
 

README.md

@@ -8,20 +8,16 @@
 
 # mkdocs-print-site-plugin
 
-[MkDocs](https://www.mkdocs.org/) plugin that adds a page to your site combining all pages, allowing your site visitors to *File > Print > Save as PDF* the entire site. See [demo](https://timvink.github.io/mkdocs-print-site-plugin/print_page.html).
+[MkDocs](https://www.mkdocs.org/) plugin that adds a print page to your site that combines the entire site, allowing for easy export to PDF and standalone HTML. See [demo](https://timvink.github.io/mkdocs-print-site-plugin/print_page.html).
 
 ## Features :star2:
 
-- Allow visitors to create PDFs from MkDocs sites.
+- Support for [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme, including features like instant loading and dark color themes.
 - Support for pagination in PDFs.
-- Works on all MkDocs themes.
-- Support for [mkdocs-material](https://github.com/squidfunk/mkdocs-material) features like instant loading and dark color themes.
-- Options to add table of contents and enumeration to headings and figures.
-- Option to add a cover page.
+- Many options to customize appearance
+- Option to add a cover page
 - Lightweight, no dependencies.
 
-If you need to create PDFs programmatically, have a look at alternatives like [mkdocs-pdf-export-plugin](https://github.com/zhaoterryy/mkdocs-pdf-export-plugin) and [mkdocs-pdf-with-js-plugin](https://github.com/smaxtec/mkdocs-pdf-with-js-plugin).
-
 ## Setup
 
 Install the plugin using `pip3`:
@@ -42,6 +38,12 @@ plugins:
 
 > If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set.
 
+## Usage
+
+- Navigate to `/print_page/` or `print_page.html`
+- Export to standalone HTML (see [export to HTML](https://timvink.github.io/mkdocs-print-site-plugin/how-to/export-HTML.html))
+- Export to PDF using your browser using *File > Print > Save as PDF*  (see [export to PDF](https://timvink.github.io/mkdocs-print-site-plugin/how-to/export-PDF.html))
+
 ## Documentation
 
 Available at [timvink.github.io/mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/).

docs/how-to/banner.md

@@ -0,0 +1,60 @@
+# Customize the print site banner
+
+When a user visits the print page, it might not be immediately obvious how to use it. You can set the `add_print_site_banner` option to `true` to add a banner to the top of the HTML print page that will be hidden when printing.
+
+You might want to customize this banner, for example by translating it to your language. You can do that by specifying the path to a custom banner template in the `mkdocs.yml` file. This file should be a standard [jinja2 template](https://jinja.palletsprojects.com/en/2.11.x/templates/) where you can combine HTML and jinja2 variables. The information specified in `mkdocs.yml` will already by available as jinja2 variables (see [mkdocs project information](https://www.mkdocs.org/user-guide/configuration/#project-information)).
+
+_Example_:
+
+=== "mkdocs.yml"
+
+    ```yaml
+    plugins:
+        - print-site:
+            add_print_site_banner: true
+            print_site_banner_template: "docs/assets/templates/custom_banner.tpl"
+    ```
+
+=== "docs/assets/templates/custom_banner.tpl"
+
+    ```jinja
+    <p>
+        <em>This box will disappear when printing</em>
+        <span style="float: right"><a href="https://timvink.github.io/mkdocs-print-site-plugin/">mkdocs-print-site-plugin</a></span>
+    </p>
+    <p>This page has combined all site pages into one. You can export to PDF using <b>File > Print > Save as PDF</b>.</p>
+    <p>See also [export to PDF](https://timvink.github.io/mkdocs-print-site-plugin/how-to/export-PDF.html) and [export to standalone HTML](https://timvink.github.io/mkdocs-print-site-plugin/how-to/export-HTML.html).</p>
+    ```
+
+As an example, have a look at the default [print_site_banner.tpl](https://github.com/timvink/mkdocs-print-site-plugin/tree/master/mkdocs_print_site_plugin/templates/print_site_banner.tpl).
+
+## Adding configurable content
+
+You might want to add some content to your cover page that's not yet specified in your `mkdocs.yml` file.
+Of course you could just hard-code it in your custom template file, but you could also make use of MkDocs's [extra context](https://www.mkdocs.org/user-guide/custom-themes/#extra-context) feature, allowing you to use custom variables from your config file with `{{ config.extra.<your variable> }}`.
+
+_Example_:
+
+=== "mkdocs.yml"
+
+    ```yaml
+    plugins:
+        - print-site:
+            add_print_site_banner: true
+            print_site_banner_template: "docs/assets/templates/custom_banner.tpl"
+
+    extra:
+        banner_message: "Save this page using File > Print > Save as PDF"
+    ```
+
+=== "docs/assets/templates/custom_banner.tpl"
+
+    ```jinja
+    <p>
+        <em>This box will disappear when printing</em>
+        <span style="float: right"><a href="https://timvink.github.io/mkdocs-print-site-plugin/">mkdocs-print-site-plugin</a></span>
+    </p>
+    <p>{{ config.extra.banner_message }}</p>
+    ```
+
+

docs/customization/cover_page.md → docs/how-to/cover_page.md

@@ -1,8 +1,8 @@
 # Customize the cover page
 
-When the `add_cover_page` option is set to true, `mkdocs-print-site-plugin` will generate a cover page when printing. This cover page is quite basic, and you might want to customize it.
+By default the `add_cover_page` option is set to `true`, which will add a cover page to the print page. You might want to customize it more to your liking.
 
-You can do that by specifying the path to a custom cover page template in the `mkdocs.yml` file. This file should be a standard [jinja2 template](https://jinja.palletsprojects.com/en/2.11.x/templates/) where you can combine HTML and jinja2 variables such as the information specified in `mkdocs.yml` (see [mkdocs project information](https://www.mkdocs.org/user-guide/configuration/#project-information)).
+You can do that by specifying the path to a custom cover page template in the `mkdocs.yml` file. This file should be a standard [jinja2 template](https://jinja.palletsprojects.com/en/2.11.x/templates/) where you can combine HTML and jinja2 variables. The information specified in `mkdocs.yml` will already by available as jinja2 variables (see [mkdocs project information](https://www.mkdocs.org/user-guide/configuration/#project-information)).
 
 _Example_:
 
@@ -24,7 +24,7 @@ _Example_:
     <h2>This is my custom print cover page</h2>
     ```
 
-As an example, have a look at the default [cover_page.tpl](https://github.com/timvink/mkdocs-print-site-plugin/tree/master/mkdocs_print_site_plugin/templates/cover_page.tpl).
+To get you started have a look at the default [cover_page.tpl](https://github.com/timvink/mkdocs-print-site-plugin/tree/master/mkdocs_print_site_plugin/templates/cover_page.tpl).
 
 ## Adding images
 
@@ -41,11 +41,11 @@ _Example_:
     <img src="/assets/img/example.png" />
     ```
 
-For a full example have a look at this [custom cover page with an image](https://github.com/timvink/mkdocs-print-site-plugin/blob/master/tests/fixtures/projects/with_markdown_ext/other_cover_page.tpl).
+For a full working example have a look at this [custom cover page with an image](https://github.com/timvink/mkdocs-print-site-plugin/blob/master/tests/fixtures/projects/with_markdown_ext/other_cover_page.tpl).
 
-## Adding extra content
+## Adding configurable content
 
-You might want to add some content to your cover page that's not yet specified in your `mkdocs.yml` file. Of course you could just hard-code it in your custom template file, but you could also make use of MkDocs's [extra context](https://www.mkdocs.org/user-guide/custom-themes/#extra-context) feature, allowing you to use `{{ config.extra.<your variable> }}`
+You might want to add some content to your cover page that's not yet specified in your `mkdocs.yml` file. Of course you could just hard-code it in your custom template file, but you could also make use of MkDocs's [extra context](https://www.mkdocs.org/user-guide/custom-themes/#extra-context) feature, allowing you to use custom variables from your config file with `{{ config.extra.<your variable> }}`.
 
 _Example_:
 
@@ -72,7 +72,7 @@ _Example_:
 
 ## Change the styling
 
-You'll likely also want to change the styling to your liking. You can add your own CSS file using the [extra_css](https://www.mkdocs.org/user-guide/configuration/#extra_css) option from MkDocs. `mkdocs-print-site-plugin` wraps the cover page in a `<section>` with id `print-site-cover-page`. You should use this in your CSS to ensure not affecting other pages.
+You'll likely also want to change the styling of the cover page to your liking. You can add your own CSS file using the [extra_css](https://www.mkdocs.org/user-guide/configuration/#extra_css) option from MkDocs. `mkdocs-print-site-plugin` wraps the cover page in a `<section id="print-site-cover-page">`. You should use this in your CSS to ensure not affecting other pages.
 
 _Example_:
 
@@ -93,4 +93,4 @@ _Example_:
     #print-site-cover-page h1 {
         color: blue;
     }
-    ```
+    ```

docs/customization/do_not_print.md → docs/how-to/do_not_print.md

@@ -1,14 +1,14 @@
-# Do not print
+# Exclude content from print
 
-You might want to exclude certain parts of you website from the print site page. This can be useful when you don't want to include large images, tables, certain [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) or appendixes to your site PDF.
+You might want to exclude certain parts of you website from the print site page. This can be useful when you don't want to include certain page, large images, tables, certain [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) or appendixes to your site exports.
 
-## Ignoring certain elements in a page
+## Ignoring elements in a page
 
 `mkdocs-print-site-plugin` offers the CSS class `.print-site-plugin-ignore`, that will ignore certain elements.
 
-The [Attribute Lists](https://python-markdown.github.io/extensions/attr_list/) extension, which is part of the standard Markdown library, allows to add HTML attributes and CSS classes to Markdown elements, and can be enabled via `mkdocs.yml`.
+The [Attribute Lists](https://python-markdown.github.io/extensions/attr_list/) extension, which is part of the standard Markdown library, allows to add HTML attributes and CSS classes to Markdown elements, and needs to be enabled in your `mkdocs.yml`.
 
-To apply the `.print-site-plugin-ignore` class to an element, you can add `{: .print-site-plugin-ignore }` to many markdown elements, as explained in the [attr_list docs](https://python-markdown.github.io/extensions/attr_list/). `attr_list` does not support all markdown elements (see [limitations](https://python-markdown.github.io/extensions/attr_list/#limitations)), but remember Markdown is a subset of HTML and anything which cannot be expressed in Markdown can always be expressed with raw HTML directly.
+To apply the `.print-site-plugin-ignore` class to an element you can use `{: .print-site-plugin-ignore }` on many different markdown elements, as explained in the [attr_list docs](https://python-markdown.github.io/extensions/attr_list/). `attr_list` does not support all markdown elements (see [limitations](https://python-markdown.github.io/extensions/attr_list/#limitations)), but remember Markdown is a subset of HTML and anything which cannot be expressed in Markdown can always be expressed with raw HTML directly.
 
 _Example_:
 
@@ -27,7 +27,7 @@ _Example_:
     ```md
     # Example page
 
-    This paragraph is not part of the print site page.
+    This paragraph will not be part of the print site page.
     {: .print-site-plugin-ignore }
 
     ![ignored image](some/path/image.png){: .print-site-plugin-ignore }
@@ -41,7 +41,9 @@ As another example, this paragraph will not be printed. Go have a look at the [p
 
 ## Ignoring admonitions
 
-Adding a class to [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) is not supported by `attr_list`. You can use the `.print-site-plugin-ignore` class directly on admonitions however:
+Adding a class to [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) is not supported by `attr_list`. You can use the `.print-site-plugin-ignore` class directly on admonitions however.
+
+_Example_:
 
 ```markdown
 !!! info print-site-plugin-ignore
@@ -58,7 +60,9 @@ Which renders as:
 
 ## Ignoring an entire page
 
-In the plugin configuration in `mkdocs.yml` you can specify a list of page source paths (one per line) that should not be included in the print page (excluded from processing by this plugin). This can be useful for example to exlude large appendixes that you only want to display on the web version. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude`: with `- subfolder/page.md`. Some examples:
+In the plugin configuration in `mkdocs.yml` you can specify a list of page source paths (one per line) that should not be included in the print page (excluded from processing by this plugin). This can be useful for example to exlude large appendixes that you only want to display on the web version. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude`: with `- subfolder/page.md`. 
+
+_Example_:
 
 ```yml
 # mkdocs.yml

docs/how-to/export-HTML.md

@@ -0,0 +1,18 @@
+# Export to HTML
+
+After enabling the `print-site` plugin in your `mkdocs.yml`, you will have your entire site combined into a single page. That allows you to create a standalone HTML page: a single self-contained file that has all images, styling and scripts embedded. This means you could send a site as an email attachment, a use case common within companies where deploying static sites might be more involved.
+
+In order to create a self-contained, standalone HTML file from the print page, we will need to embed images, CSS and javascript using [data URLs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs). We can do this quite easily using the [htmlark](https://github.com/BitLooter/htmlark) python package:
+
+
+```shell
+pip install http html5lib requests
+pip install htmlark
+```
+
+To create the export:
+
+```shell
+mkdocs build
+htmlark site/print_page.html -o standalone.html
+```

docs/how-to/export-PDF.md

@@ -0,0 +1,76 @@
+# Export to PDF
+
+After enabling the `print-site` plugin in your `mkdocs.yml`, exporting to PDF is as simple as browsing to `/print_page` or `/print_page.html` (url depends on your mkdocs setting `use_directory_urls`). From your browser you can use *File > Print > Save as PDF*.
+
+If you want to automatically create PDFs of your mkdocs website, you can automate the process using a headless chrome plugin.
+
+## Automated export using nodejs
+
+We can use [nodejs](https://nodejs.org/en/) together with the [puppeteer](https://github.com/puppeteer/puppeteer) headless chrome node.js package:
+
+- Install [nodejs](https://nodejs.org/en/) 
+- Download puppeteer in the root of your project using the node package manager: `npm i --save puppeteer`
+- Save the script `export_to_pdf.js` (see below) in the root of your project
+- Start a webserver with your site (`mkdocs serve`)
+- In a separate terminal window, you can now run the PDF export with `url` (to your print page), `pdfPath` (name of output file) and `title` arguments:
+
+```shell
+node exportpdf.js http://localhost:8000/print_page.html out.pdf 'title'
+```
+
+??? example "export_to_pdf.js"
+
+    ```js
+    // Credits for script: https://github.com/majkinetor/mm-docs-template/blob/master/source/pdf/print.js
+    // Requires: npm i --save puppeteer
+
+    const puppeteer = require('puppeteer');
+    var args = process.argv.slice(2);
+    var url = args[0];
+    var pdfPath = args[1];
+    var title = args[2];
+
+    console.log('Saving', url, 'to', pdfPath);
+
+    // date –  formatted print date
+    // title – document title
+    // url  – document location
+    // pageNumber – current page number
+    // totalPages – total pages in the document
+    headerHtml = `
+    <div style="font-size: 10px; padding-right: 1em; text-align: right; width: 100%;">
+        <span>${title}</span>  <span class="pageNumber"></span> / <span class="totalPages"></span>
+    </div>`;
+
+    footerHtml = ` `;
+
+
+    (async() => {
+        const browser = await puppeteer.launch({
+            headless: true,
+            executablePath: process.env.CHROME_BIN || null,
+            args: ['--no-sandbox', '--headless', '--disable-gpu', '--disable-dev-shm-usage']
+        });
+
+        const page = await browser.newPage();
+        await page.goto(url, { waitUntil: 'networkidle2' });
+        await page.pdf({
+            path: pdfPath, // path to save pdf file
+            format: 'A4', // page format
+            displayHeaderFooter: true, // display header and footer (in this example, required!)
+            printBackground: true, // print background
+            landscape: false, // use horizontal page layout
+            headerTemplate: headerHtml, // indicate html template for header
+            footerTemplate: footerHtml,
+            scale: 1, //Scale amount must be between 0.1 and 2
+            margin: { // increase margins (in this example, required!)
+                top: 80,
+                bottom: 80,
+                left: 30,
+                right: 30
+            }
+        });
+
+        await browser.close();
+    })();
+    ```