First working version

Author: timvink

.gitignore

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Tim Vink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -0,0 +1 @@
+mkdocs_print_site_plugin/css/*

MANIFEST.in

@@ -0,0 +1,66 @@
+**This plugin is under development and the first version has not yet been released**
+
+# 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.
+
+## Features :star2:
+
+- Allow visitors to create PDFs from MkDocs sites themselves
+- Support for pagination
+- Support for generic and [mkdocs-material](https://github.com/squidfunk/mkdocs-material) themes, but works on all themes
+- Lightweight, no dependencies
+
+Currently, there is no support for PDF bookmarks. Have a look at alternatives like [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`:
+
+```bash
+pip3 install mkdocs-print-site-plugin
+```
+
+Next, add the following lines to your `mkdocs.yml`:
+
+```yml
+plugins:
+  - search
+  - print-site
+```
+
+> 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.
+
+
+## TODO
+
+- Perhaps prevent the write file, by having the .md file be part of the package? Or put it in a tmp folder? See # https://github.com/greenape/mknotebooks/blob/master/mknotebooks/plugin.py#L126
+- Add a demo website
+- Try to get PDF bookmarks working. Standards: https://www.w3.org/TR/2014/WD-css-gcpm-3-20140513/#bookmarks , lessons https://print-css.rocks/lessons
+- Add print button to every page? See approach described at https://github.com/danielfrg/mkdocs-jupyter
+- Ensure order of pages is consistent with navigation order, by making sure the plugin has been added last in the list.
+- ensure this plugin is defined last (to allow other plugins to make any modifications first). Return a warning if this is not the case.
+- Add option to change the print page title.
+- Add option to insert a Table of contents page. Here is how to create the leader dots and page numbers using CSS https://www.smashingmagazine.com/2015/01/designing-for-print-with-css/
+- Add option to insert a frontcover page http://blog.michaelperrin.fr/2019/11/04/printing-the-web-part-2-html-and-css-for-printing-books/
+- Display current chapter title in the footer http://blog.michaelperrin.fr/2019/11/04/printing-the-web-part-2-html-and-css-for-printing-books/ 
+- check if appending print page does not break nested navigations (perhaps unit test?)
+- check tables with lots of columns, deal with overflow
+- Option to add print url after links? https://css-tricks.com/snippets/css/print-url-after-links/
+- support different anchor links, or at least throw warning if different than #
+  https://www.mkdocs.org/user-guide/writing-your-docs/
+    ```yml
+    markdown_extensions:
+        - toc:
+            permalink: "#"
+    ```
+- ensure support of 'use_directory_urls' settings https://www.mkdocs.org/user-guide/configuration/#use_directory_urls
+
+```python
+[p.url for p in self.pages]
+['index.html', 'z.html', 'a.html']
+```
+
+## Contributing
+
+Contributions are very welcome! Start by reading the [contribution guidelines](https://timvink.github.io/mkdocs-print-site-plugin/contributing.html).

README.md

@@ -0,0 +1,53 @@
+# Contribution Guidelines
+
+Thanks for considering to contribute to this project! Some guidelines:
+
+- Go through the issue list and if needed create a relevant issue to discuss the change design. On disagreements, maintainer(s) will have the final word.
+- You can expect a response from a maintainer within 7 days. If you haven’t heard anything by then, feel free to ping the thread.
+- This package tries to be as simple as possible for the user (hide any complexity from the user). Options are only added when there is clear value to the majority of users.
+- When issues or pull requests are not going to be resolved or merged, they should be closed as soon as possible. This is kinder than deciding this after a long period. Our issue tracker should reflect work to be done.
+
+## Unit Tests
+
+Make sure to install an editable version before running tests:
+
+```python
+pip install -r tests/test_requirements.txt
+pip install -e .
+pytest --cov=mkdocs_print_site_plugin --cov-report term-missing tests/
+```
+
+If it makes sense, writing tests for your PRs is always appreciated and will help get them merged.
+
+In addition, this project uses [pyflakes](https://pypi.org/project/pyflakes/) for static code checking:
+
+```python
+pip install pyflakes
+pyflakes tests/ mkdocs_print_site_plugin/
+```
+
+## Manual testing
+
+To quickly serve a website with your latest changes to the plugin use the sites in our tests suite. For example:
+
+```python
+pip install -r tests/test_requirements.txt
+pip install -e .
+mkdocs serve -f tests/fixutures/basic/mkdocs.yml
+```
+
+Tip: If you use google chrome, you can also view the print version of a page inside the browser [by setting the renderer](https://www.smashingmagazine.com/2018/05/print-stylesheets-in-2018/).
+
+## Code Style
+
+Make sure your code *roughly* follows [PEP-8](https://www.python.org/dev/peps/pep-0008/) and keeps things consistent with the rest of the code. I recommended using [black](https://github.com/psf/black) to automatically format your code.
+
+We use google-style docstrings.
+
+## Documentation
+
+Is in `docs/`. To [deploy the docs](https://www.mkdocs.org/user-guide/deploying-your-docs/), run:
+
+```bash
+mkdocs gh-deploy
+```

docs/contributing.md

@@ -0,0 +1,7 @@
+# Demo Content
+
+This content is here to demonstrate what it looks like while printing.
+
+Go ahead and visit the [print page](print_site.md) and check it out!
+
+## TODO

docs/demo_content.md

@@ -0,0 +1,21 @@
+# mkdocs-print-page-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.
+
+## Installation
+
+Install the plugin using `pip3`:
+
+```bash
+pip3 install mkdocs-print-site-plugin
+```
+
+Next, add the following lines to your `mkdocs.yml`:
+
+```yml
+plugins:
+  - search
+  - print-site
+```
+
+> 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.

docs/index.md

@@ -0,0 +1,13 @@
+# Options
+
+You can customize the plugin by setting options in `mkdocs.yml`. For example:
+
+```yml
+plugins:
+  - print-site:
+      add_to_navigation: false
+```
+
+## `add_to_navigation`
+
+Default is `true`. Adds a link 'Print Site' to your site navigation.

docs/options.md

@@ -0,0 +1,17 @@
+site_name: mkdocs-print-site-plugin Docs
+repo_url: https://github.com/timvink/mkdocs-print-site-plugin
+site_url: https://timvink.github.io/mkdocs-print-site-plugin/
+site_description: MkDocs Plugin allowing your site visitors to *File > Print > Save as PDF* the entire site.
+site_author: Tim Vink
+
+use_directory_urls: false
+
+plugins:
+    - print-site
+    - search
+ 
+nav:
+    - Home: index.md
+    - Options: options.md
+    - Demo Content: demo_content.md
+    - Contributing: contributing.md

mkdocs.yml

@@ -0,0 +1,21 @@
+/* print styles for mkdocs material theme 
+https://github.com/squidfunk/mkdocs-material */
+
+@media print {
+
+}
+
+@page {
+
+    size: a4 portrait;
+    margin: 15mm 10mm 25mm 10mm;
+    counter-increment: page;
+
+    @bottom-center {
+        content: string(chapter);
+    }
+    @bottom-right {
+        content: 'Page ' counter(page);
+    }
+
+}

mkdocs_print_site_plugin/css/material.css

@@ -0,0 +1,19 @@
+/* Print styles for default MkDocs theme  */
+
+@media print {
+    .col-md-3 { display: none !important; }
+}
+
+@page {
+
+    size: a4 portrait;
+    margin: 15mm 10mm 15mm 10mm;
+    counter-increment: page;
+
+    @bottom-center {
+        content: string(chapter);
+    }
+    @bottom-right {
+        content: 'Page ' counter(page);
+    }
+}

mkdocs_print_site_plugin/css/mkdocs.css

@@ -0,0 +1,63 @@
+
+#print-site-banner {
+    border:2px; 
+    border-style:solid; 
+    border-color:#000000; 
+    padding: 0em 1em 0em 1em; 
+    margin-bottom: 2em;
+}
+#print-site-banner h3 {
+    margin-top: 1rem;
+}
+
+
+@media print {    
+
+    /* included bookmarks on h1 and h2
+    Doesn't work, but included In case Chrome gets support 
+    for these experimental CSS features that define PDF bookmarks */
+    h1 {
+        bookmark-label: content(); 
+        -ah-bookmark-level: 1;
+        -ro-pdf-bookmark-level: 1;
+    }
+    h2 {
+        bookmark-label: content(); 
+        -ah-bookmark-level: 2;
+        -ro-pdf-bookmark-level: 2;
+    }
+
+    #print-site-banner { display: none; }
+
+    /* PDF page breaks on each MkDocs page, except the first one */
+    section.print-page {
+        page-break-before: always;
+    }
+    section.print-page:first-of-type {
+        page-break-before: avoid;
+    }
+
+    pre, blockquote {
+        page-break-inside: avoid;
+    }
+
+    /* Avoid a page break immediately after a heading */
+    /* Credits https://stackoverflow.com/a/9238898/5525118 */
+    h1 {
+        page-break-inside: avoid;
+    }
+    h1::after {
+        content: "";
+        display: block;
+        height: 100px;
+        margin-bottom: -100px;
+    }
+
+}
+
+@page {
+
+    /* Prevent image page overflow */
+    img { max-width: 500px !important; }
+
+}