Update documentation with info on PDF and HTML export

.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/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 and script 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 'your website name'
+```
+
+??? 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();
+    })();
+    ```

docs/index.md

@@ -29,3 +29,9 @@ plugins:
 > :warning: Make sure to put `print-site` to the **bottom** of the plugin list. This is because other plugins might alter your site (like the navigation), and you want these changes included in the print page.
 
 > 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](how-to/export-HTML.html))
+- Export to PDF using your browser using *File > Print > Save as PDF*  (see [export to PDF](how-to/export-PDF.html))

docs/options.md

@@ -52,19 +52,19 @@ plugins:
 :   Default `true`. This will add numbering to all figure captions (for example "Figure 1: <caption>"). Works especially well with [mkdocs-img2fig-plugin](https://github.com/stuebersystems/mkdocs-img2fig-plugin).
 
 `add_cover_page`
-:   Default `false`. When enabled, a cover page is added to the print page, displaying the `site_title` and other information from the `mkdocs.yml` file. See also [Customizing the cover page](customization/cover_page.md)
+:   Default `false`. When enabled, a cover page is added to the print page, displaying the `site_title` and other information from the `mkdocs.yml` file. See also [Customizing the cover page](how-to/cover_page.md)
 
 `cover_page_template`
-:   Default `""`. The path to a custom cover page template to use. See [Customizing the Cover Page](customization/cover_page.md) for more info.
+:   Default `""`. The path to a custom cover page template to use. See [Customizing the Cover Page](how-to/cover_page.md) for more info.
 
 `add_print_site_banner`
 :   Default `false`. When enabled, a banner is added to the top of the HTML print page, explaining to users the current page contains all site pages.
 
 `print_site_banner_template`
-:   Default `""`. The path to a custom print site banner template to use. See [Customizing the print site banner](customization/banner.md) for more info.
+:   Default `""`. The path to a custom print site banner template to use. See [Customizing the print site banner](how-to/banner.md) for more info.
 
 `path_to_pdf`
-: Default is empty. Option to make it easier to add a link to the PDF version of the site on each page. See [Adding a PDF button](customization/pdf_button.md) for more info.
+: Default is empty. Option to make it easier to add a link to the PDF version of the site on each page. See [Adding a PDF button](how-to/pdf_button.md) for more info.
 
 `enabled`
 : Default is `true`. Enables you to deactivate this plugin. A possible use case is local development where you might want faster build times. It's recommended to use this option with an environment variable together with a default fallback (introduced in `mkdocs` v1.2.1, see [docs](https://www.mkdocs.org/user-guide/configuration/#environment-variables)). Example:
@@ -84,4 +84,4 @@ plugins:
     ```
 
 `exclude`
-: Default is empty. Allows to specify a list of page source paths that should not be included in the print page. See [Do Not Print](customization/do_not_print.md#ignoring-an-entire-page) for more info.
+: Default is empty. Allows to specify a list of page source paths that should not be included in the print page. See [Do Not Print](how-to/do_not_print.md#ignoring-an-entire-page) for more info.

mkdocs.yml

@@ -24,17 +24,23 @@ plugins:
 nav:
     - Home: index.md
     - Options: options.md
-    - Customization:
-        - customization/print_button.md
-        - customization/pdf_button.md
-        - customization/cover_page.md
-        - customization/do_not_print.md
+    - How to guides:
+        - Export to PDF: how-to/export-PDF.md
+        - Export to HTML: how-to/export-HTML.md
+        - Add a print button: how-to/print_button.md
+        - Add a PDF button: how-to/pdf_button.md
+        - Add a cover page: how-to/cover_page.md
+        - Add a banner: how-to/banner.md
+        - Exclude content: how-to/do_not_print.md
     - Demo Content: demo_content.md
     - Contributing: contributing.md
 
 theme:
     name: material
     custom_dir: docs/overrides
+    icon:
+        admonition:
+            example: fontawesome/solid/flask
     palette:
         - media: "(prefers-color-scheme: light)"
           scheme: default

setup.py

@@ -10,7 +10,7 @@
 setup(
     name="mkdocs-print-site-plugin",
     version="1.3.0",
-    description="MkDocs plugin that adds a page with all site pages, enabling printing to PDF for users.",
+    description="MkDocs plugin that combines all pages into one, allowing for easy export to PDF and standalone HTML.",
     long_description=long_description,
     long_description_content_type="text/markdown",
     keywords="mkdocs plugin print pdf",