├── .codecov.yml ├── .github ├── FUNDING.yml └── workflows │ ├── pythonpublish.yml │ ├── unittests.yml │ └── unittests_codecov.yml ├── .gitignore ├── .pre-commit-config.yaml ├── LICENSE ├── MANIFEST.in ├── README.md ├── docs ├── contributing.md ├── demo_content.md ├── how-to │ ├── banner.md │ ├── cover_page.md │ ├── do_not_print.md │ ├── export-HTML.md │ ├── export-PDF.md │ ├── pdf_button.md │ └── print_button.md ├── index.md ├── javascripts │ └── config.js ├── options.md └── overrides │ └── main.html ├── mkdocs.yml ├── pyproject.toml ├── src └── mkdocs_print_site_plugin │ ├── __init__.py │ ├── css │ ├── print-site-material.css │ ├── print-site-mkdocs.css │ ├── print-site-readthedocs.css │ └── print-site.css │ ├── exclude.py │ ├── js │ └── print-site.js │ ├── plugin.py │ ├── renderer.py │ ├── templates │ ├── cover_page.tpl │ └── print_site_banner.tpl │ ├── urls.py │ └── utils.py ├── tests ├── __init__.py ├── fixtures │ └── projects │ │ ├── bad_headings │ │ ├── docs │ │ │ ├── a.md │ │ │ ├── empty.md │ │ │ ├── index.md │ │ │ ├── section.md │ │ │ ├── subsection1.md │ │ │ ├── subsection2.md │ │ │ └── z.md │ │ └── mkdocs.yml │ │ ├── basic │ │ ├── docs │ │ │ ├── a.md │ │ │ ├── empty.md │ │ │ ├── ignore_content.md │ │ │ ├── index.md │ │ │ ├── section.md │ │ │ ├── subfolder │ │ │ │ └── anotherpage.md │ │ │ ├── subsection1.md │ │ │ ├── subsection2.md │ │ │ └── z.md │ │ ├── mkdocs.yml │ │ ├── mkdocs_addtonav_false.yml │ │ ├── mkdocs_do_not_print.yml │ │ ├── mkdocs_material_disabled.yml │ │ ├── mkdocs_material_instant_loading.yml │ │ ├── mkdocs_material_with_enum_plugin.yml │ │ ├── mkdocs_material_with_git_plugin.yml │ │ ├── mkdocs_no_directory_urls.yml │ │ ├── mkdocs_no_toc.yml │ │ ├── mkdocs_readthedocs.yml │ │ ├── mkdocs_toc_depth.yml │ │ ├── mkdocs_toc_permalink.yml │ │ ├── mkdocs_weird_nav.yml │ │ ├── mkdocs_windmill.yml │ │ ├── mkdocs_with_enum.yml │ │ ├── mkdocs_with_nav.yml │ │ ├── mkdocs_with_nav_addtonav_false.yml │ │ └── mkdocs_with_nav_and_theme.yml │ │ ├── mkdocs_material_tags │ │ ├── docs │ │ │ └── index.md │ │ └── mkdocs.yml │ │ ├── nested_sections │ │ ├── docs │ │ │ ├── index.md │ │ │ ├── info.md │ │ │ ├── page1.md │ │ │ ├── page2.md │ │ │ ├── page3.md │ │ │ ├── page4.md │ │ │ ├── page5.md │ │ │ ├── page6.md │ │ │ ├── page7.md │ │ │ └── page8.md │ │ ├── mkdocs.yml │ │ └── mkdocs_basetheme.yml │ │ ├── relative_images │ │ ├── docs │ │ │ ├── About.md │ │ │ ├── Chapter1 │ │ │ │ ├── Section1.md │ │ │ │ ├── Section2.md │ │ │ │ └── img │ │ │ │ │ ├── Picture1-1.png │ │ │ │ │ └── Picture1-2.png │ │ │ ├── Chapter2 │ │ │ │ ├── Section1.md │ │ │ │ ├── Section2.md │ │ │ │ ├── files │ │ │ │ │ └── dummy.txt │ │ │ │ └── img │ │ │ │ │ └── Picture2-2.png │ │ │ ├── github-octocat.png │ │ │ ├── img │ │ │ │ └── Picture0.png │ │ │ └── index.md │ │ ├── mkdocs.yml │ │ ├── mkdocs_img2fig.yml │ │ └── mkdocs_no_dir_urls.yml │ │ ├── snippets │ │ ├── docs │ │ │ └── index.md │ │ ├── includes │ │ │ ├── bla.md │ │ │ └── content.html │ │ └── mkdocs.yml │ │ ├── tables │ │ ├── docs │ │ │ ├── index.md │ │ │ ├── long.md │ │ │ └── wide.md │ │ └── mkdocs.yml │ │ └── with_markdown_ext │ │ ├── docs │ │ ├── appendix.md │ │ ├── extensions │ │ │ ├── admonition.md │ │ │ ├── codehilite.md │ │ │ ├── footnotes.md │ │ │ ├── metadata.md │ │ │ ├── permalinks.md │ │ │ └── pymdown.md │ │ ├── folder │ │ │ ├── img │ │ │ │ └── github-octocat.png │ │ │ ├── subfolder │ │ │ │ └── nested_file.md │ │ │ └── subpage.md │ │ ├── images.md │ │ ├── index.md │ │ ├── overrides │ │ │ └── main.html │ │ └── two.md │ │ ├── mkdocs.yml │ │ ├── mkdocs_diff_cover_page.yml │ │ ├── mkdocs_img2fig.yml │ │ ├── mkdocs_with_toc.yml │ │ └── other_cover_page.tpl ├── test_building.py ├── test_exclude.py └── test_urls.py └── uv.lock /.codecov.yml: -------------------------------------------------------------------------------- 1 | comment: false 2 | 3 | coverage: 4 | status: 5 | project: 6 | default: 7 | # Commits pushed to master should not make the overall 8 | # project coverage decrease by more than x%: 9 | target: auto 10 | threshold: 20% 11 | patch: 12 | default: 13 | # Be tolerant on slight code coverage diff on PRs to limit 14 | # noisy red coverage status on github PRs. 15 | # Note: The coverage stats are still uploaded 16 | # to codecov so that PR reviewers can see uncovered lines 17 | target: auto 18 | threshold: 20% 19 | 20 | codecov: 21 | notify: 22 | # Prevent coverage status to upload multiple times for parallel and long 23 | # running CI pipelines. This configuration is particularly useful on PRs 24 | # to avoid confusion. Note that this value is set to the number of Azure 25 | # Pipeline jobs uploading coverage reports. 26 | after_n_builds: 6 -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: [timvink] 4 | -------------------------------------------------------------------------------- /.github/workflows/pythonpublish.yml: -------------------------------------------------------------------------------- 1 | name: Upload Python Package 2 | 3 | on: 4 | workflow_dispatch: 5 | release: 6 | types: [created] 7 | 8 | jobs: 9 | deploy: 10 | runs-on: ubuntu-latest 11 | environment: release 12 | permissions: 13 | # IMPORTANT: this permission is mandatory for trusted publishing 14 | id-token: write 15 | contents: write 16 | steps: 17 | - uses: actions/checkout@v4 18 | with: 19 | fetch-depth: '0' 20 | - name: Set up Python 21 | uses: actions/setup-python@v5 22 | with: 23 | python-version: '3.x' 24 | - name: Install uv 25 | uses: astral-sh/setup-uv@v5 26 | 27 | - name: Make sure unit tests succeed 28 | run: | 29 | git config --global user.name "Github Action" 30 | git config --global user.email "githubaction@gmail.com" 31 | uv run pytest 32 | 33 | - name: Build 34 | run: | 35 | uv build 36 | 37 | # See https://docs.pypi.org/trusted-publishers/using-a-publisher/ 38 | - name: Publish package distributions to PyPI 39 | uses: pypa/gh-action-pypi-publish@release/v1 40 | -------------------------------------------------------------------------------- /.github/workflows/unittests.yml: -------------------------------------------------------------------------------- 1 | name: Unit tests 2 | on: [pull_request] 3 | jobs: 4 | run: 5 | name: Run unit tests 6 | runs-on: ${{ matrix.os }} 7 | env: 8 | USING_COVERAGE: '3.10' 9 | strategy: 10 | matrix: 11 | os: [ubuntu-latest, macos-latest, windows-latest] 12 | python-version: [3.8, 3.9, "3.10", "3.11", "3.12"] 13 | steps: 14 | - uses: actions/checkout@master 15 | 16 | - name: Install uv and set the python version 17 | uses: astral-sh/setup-uv@v5 18 | with: 19 | python-version: ${{ matrix.python-version }} 20 | 21 | - name: Run unit tests 22 | run: | 23 | git config --global user.name "Github Action" 24 | git config --global user.email "githubaction@gmail.com" 25 | uv run pytest --cov=mkdocs_print_site_plugin --cov-report=xml 26 | -------------------------------------------------------------------------------- /.github/workflows/unittests_codecov.yml: -------------------------------------------------------------------------------- 1 | name: pytest 2 | on: 3 | # Trigger the workflow on push or pull request, 4 | # but only for the master branch 5 | push: 6 | branches: 7 | - master 8 | pull_request: 9 | branches: 10 | - master 11 | jobs: 12 | run: 13 | name: Run unit tests with codecov upload 14 | runs-on: ${{ matrix.os }} 15 | env: 16 | USING_COVERAGE: '3.10' 17 | strategy: 18 | matrix: 19 | os: [ubuntu-latest, macos-latest, windows-latest] 20 | python-version: [3.8, 3.9, "3.10", "3.11", "3.12", "3.13"] 21 | steps: 22 | - uses: actions/checkout@master 23 | 24 | - name: Install uv and set the python version 25 | uses: astral-sh/setup-uv@v5 26 | with: 27 | python-version: ${{ matrix.python-version }} 28 | 29 | - name: Generate coverage report 30 | run: | 31 | git config --global user.name "Github Action" 32 | git config --global user.email "githubaction@gmail.com" 33 | uv run pytest --cov=mkdocs_print_site_plugin --cov-report=xml 34 | 35 | - name: Upload coverage to Codecov 36 | if: "contains(env.USING_COVERAGE, matrix.python-version)" 37 | uses: codecov/codecov-action@v4 38 | with: 39 | files: ./coverage.xml 40 | flags: unittests 41 | fail_ci_if_error: false 42 | env: 43 | CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} 44 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | repos: 2 | - repo: local 3 | hooks: 4 | - id: mypy 5 | name: mypy 6 | entry: mypy 7 | language: system 8 | types: [python] 9 | args: [--ignore-missing-imports, --namespace-packages, --show-error-codes, --pretty] 10 | 11 | # D100 requires all Python files (modules) to have a "public" docstring even if all functions within have a docstring. 12 | # D104 requires __init__ files to have a docstring 13 | # D212 14 | # D200 15 | # D412 No blank lines allowed between a section header and its content 16 | # E203 17 | # W293 blank line contains whitespace 18 | # W503 line break before binary operator (for compatibility with black) 19 | # W605 invalid escape sequence '\/' 20 | # E722 do not use bare 'except' -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Tim Vink 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include mkdocs_print_site_plugin/css/*.css 2 | include mkdocs_print_site_plugin/js/*.js 3 | include mkdocs_print_site_plugin/templates/*.tpl -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [![Actions Status](https://github.com/timvink/mkdocs-print-site-plugin/workflows/pytest/badge.svg)](https://github.com/timvink/mkdocs-print-site-plugin/actions) 2 | ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-print-site-plugin) 3 | ![PyPI](https://img.shields.io/pypi/v/mkdocs-print-site-plugin) 4 | ![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-print-site-plugin) 5 | [![codecov](https://codecov.io/gh/timvink/mkdocs-print-site-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/timvink/mkdocs-print-site-plugin) 6 | ![GitHub contributors](https://img.shields.io/github/contributors/timvink/mkdocs-print-site-plugin) 7 | ![PyPI - License](https://img.shields.io/pypi/l/mkdocs-print-site-plugin) 8 | 9 | # mkdocs-print-site-plugin 10 | 11 | [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). 12 | 13 | ## Features :star2: 14 | 15 | - Support for [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme, including features like instant loading, dark color themes and certain plugins (f.e. the [tags](https://squidfunk.github.io/mkdocs-material/plugins/tags/) plugin) 16 | - Support for [readthedocs](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) theme 17 | - Support for pagination in PDFs. 18 | - Many options to customize appearance 19 | - Option to add a cover page 20 | - Lightweight, no dependencies. 21 | 22 | ## Setup 23 | 24 | Install the plugin using `pip3`: 25 | 26 | ```bash 27 | pip3 install mkdocs-print-site-plugin 28 | ``` 29 | 30 | Next, add the following lines to your `mkdocs.yml`: 31 | 32 | ```yml 33 | plugins: 34 | - search 35 | - print-site 36 | ``` 37 | 38 | > ⚠️ 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. 39 | 40 | > 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. 41 | 42 | ## Usage 43 | 44 | - Navigate to `/print_page/` or `print_page.html` 45 | - Export to standalone HTML (see [export to HTML](https://timvink.github.io/mkdocs-print-site-plugin/how-to/export-HTML.html)) 46 | - 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)) 47 | 48 | ## Documentation 49 | 50 | Available at [timvink.github.io/mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/). 51 | 52 | ## Contributing 53 | 54 | Contributions are very welcome! Start by reading the [contribution guidelines](https://timvink.github.io/mkdocs-print-site-plugin/contributing.html). 55 | -------------------------------------------------------------------------------- /docs/contributing.md: -------------------------------------------------------------------------------- 1 | # Contribution Guidelines 2 | 3 | Thanks for considering to contribute to this project! Some guidelines: 4 | 5 | - 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. 6 | - 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. 7 | - 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. 8 | - 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. 9 | 10 | ## Unit Tests 11 | 12 | We use [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage python: 13 | 14 | ```bash 15 | uv run pytest --cov=mkdocs_print_site_plugin --cov-report term-missing tests/ 16 | ``` 17 | 18 | If it makes sense, writing tests for your PRs is always appreciated and will help get them merged. 19 | 20 | You can also apply formatting using: 21 | 22 | ```bash 23 | uv run --with ruff ruff format src/ 24 | ``` 25 | 26 | ## Manual testing 27 | 28 | To quickly serve a website with your latest changes to the plugin use the sites in our tests suite. For example: 29 | 30 | ```bash 31 | uv run mkdocs serve -f tests/fixutures/basic/mkdocs.yml 32 | ``` 33 | 34 | 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/). 35 | 36 | ## Code Style 37 | 38 | 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 [Ruff](https://github.com/astral-sh/ruff) to automatically format your code. 39 | 40 | We use google-style docstrings. 41 | 42 | ## Documentation 43 | 44 | Is in `docs/`. To [deploy the docs](https://www.mkdocs.org/user-guide/deploying-your-docs/), run: 45 | 46 | ```bash 47 | uv run mkdocs gh-deploy 48 | ``` 49 | 50 | Note: there is no automated github action for this currently. -------------------------------------------------------------------------------- /docs/demo_content.md: -------------------------------------------------------------------------------- 1 | # Demo Content 2 | 3 | This content is here to demonstrate what it looks like while printing. 4 | 5 | :point_right: Go ahead and visit the [print page](print_page.html) and check it out! 6 | 7 | ## Links to other pages 8 | 9 | `mkdocs-print-site-plugin` will fix internal links when combining all the pages into one. Try navigating to other site pages using these internal links: 10 | 11 | - [Home](index.md) 12 | - [Options](options.md) 13 | - [Contributing](contributing.md) 14 | 15 | ## Links to other sections 16 | 17 | When combining all pages into one, `mkdocs-print-site-plugin` will also ensure anchor links keep working (also to anchor links on other pages). Try them out: 18 | 19 | - [Dummy section](#dummy-section) lower down this demo page 20 | - The [Manual Testing](contributing.md#manual-testing) in the contributing guide 21 | 22 | ## Charts 23 | 24 | From the [mkdocs-charts-plugin](https://timvink.github.io/mkdocs-charts-plugin/): 25 | 26 | ```vegalite 27 | { 28 | "description": "A simple bar chart with embedded data.", 29 | "data": { 30 | "values": [ 31 | {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43}, 32 | {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53}, 33 | {"a": "G", "b": 19}, {"a": "H", "b": 87}, {"a": "I", "b": 52} 34 | ] 35 | }, 36 | "mark": {"type": "bar", "tooltip": true}, 37 | "encoding": { 38 | "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}}, 39 | "y": {"field": "b", "type": "quantitative"} 40 | } 41 | } 42 | ``` 43 | 44 | ## Magic links 45 | 46 | **Magic links and emails:** turned to links as recognized 47 | 48 | | Output | Code | 49 | | --------------------- | ----------------------- | 50 | | http://www.google.com | `http://www.google.com` | 51 | | johndoe@gmail.com | `johndoe@gmail.com` | 52 | | www.google.com | `www.google.com` | 53 | 54 | 55 | ## Markdown extensions 56 | 57 | MkDocs has support for many markdown extensions (see [mkdocs-material reference](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)). Below is a quick showcase so you can see how they print. 58 | 59 | !!! note "Phasellus posuere in sem ut cursus" 60 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod 61 | nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor 62 | massa, nec semper lorem quam in massa. 63 | 64 | !!! note "" 65 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod 66 | nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor 67 | massa, nec semper lorem quam in massa. 68 | 69 | !!! note 70 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod 71 | nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor 72 | massa, nec semper lorem quam in massa. 73 | 74 | ``` python 75 | def bubble_sort(items): 76 | for i in range(len(items)): 77 | for j in range(len(items) - 1 - i): 78 | if items[j] > items[j + 1]: 79 | items[j], items[j + 1] = items[j + 1], items[j] 80 | ``` 81 | 82 | Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in 83 | sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. 84 | Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim. 85 | 86 | ??? note 87 | This is a collapsible block, that is collapsed by default. 88 | 89 | [Example of a button](#){: .md-button } 90 | 91 | [Primary button](#){: .md-button .md-button--primary } 92 | 93 | [With icon :fontawesome-solid-paper-plane:](#){: .md-button .md-button--primary } 94 | 95 | ``` python 96 | import tensorflow as tf 97 | ``` 98 | 99 | ``` python linenums="1" 100 | def bubble_sort(items): 101 | for i in range(len(items)): 102 | for j in range(len(items) - 1 - i): 103 | if items[j] > items[j + 1]: 104 | items[j], items[j + 1] = items[j + 1], items[j] 105 | ``` 106 | 107 | ``` python hl_lines="2 3" 108 | def bubble_sort(items): 109 | for i in range(len(items)): 110 | for j in range(len(items) - 1 - i): 111 | if items[j] > items[j + 1]: 112 | items[j], items[j + 1] = items[j + 1], items[j] 113 | ``` 114 | 115 | The `#!python range()` function is used to generate a sequence of numbers. 116 | 117 | ++ctrl+alt+del++ 118 | 119 | === "C" 120 | 121 | ``` c 122 | #include 123 | 124 | int main(void) { 125 | printf("Hello world!\n"); 126 | return 0; 127 | } 128 | ``` 129 | 130 | === "C++" 131 | 132 | ``` c++ 133 | #include 134 | 135 | int main(void) { 136 | std::cout << "Hello world!" << std::endl; 137 | return 0; 138 | } 139 | ``` 140 | 141 | Another tabbed content 142 | 143 | === "Unordered list" 144 | 145 | * Sed sagittis eleifend rutrum 146 | * Donec vitae suscipit est 147 | * Nulla tempor lobortis orci 148 | 149 | === "Ordered list" 150 | 151 | 1. Sed sagittis eleifend rutrum 152 | 2. Donec vitae suscipit est 153 | 3. Nulla tempor lobortis orci 154 | 155 | Embedding content: 156 | 157 | !!! example 158 | 159 | === "Unordered List" 160 | 161 | _Example_: 162 | 163 | ``` markdown 164 | * Sed sagittis eleifend rutrum 165 | * Donec vitae suscipit est 166 | * Nulla tempor lobortis orci 167 | ``` 168 | 169 | _Result_: 170 | 171 | * Sed sagittis eleifend rutrum 172 | * Donec vitae suscipit est 173 | * Nulla tempor lobortis orci 174 | 175 | === "Ordered List" 176 | 177 | _Example_: 178 | 179 | ``` markdown 180 | 1. Sed sagittis eleifend rutrum 181 | 2. Donec vitae suscipit est 182 | 3. Nulla tempor lobortis orci 183 | ``` 184 | 185 | _Result_: 186 | 187 | 1. Sed sagittis eleifend rutrum 188 | 2. Donec vitae suscipit est 189 | 3. Nulla tempor lobortis orci 190 | 191 | | Method | Description | 192 | | ----------- | ------------------------------------ | 193 | | `GET` | :material-check: Fetch resource | 194 | | `PUT` | :material-check-all: Update resource | 195 | | `DELETE` | :material-close: Delete resource | 196 | 197 | Footnotes in a text: Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2] 198 | 199 | [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. 200 | [^2]: 201 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod 202 | nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor 203 | massa, nec semper lorem quam in massa. 204 | 205 | * :material-account-circle: – `.icons/material/account-circle.svg` 206 | * :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg` 207 | * :octicons-octoface-16: – `.icons/octicons/octoface-16.svg` 208 | * :fontawesome-brands-medium:{: .medium } – Medium 209 | * :fontawesome-brands-twitter:{: .twitter } – Twitter 210 | * :fontawesome-brands-facebook:{: .facebook } – Facebook 211 | 212 | :smile: 213 | 214 | ### Images 215 | 216 | `mkdocs-print-site-plugin` supports enumerating figure captions (which can be added easily using the [img2fig](https://github.com/stuebersystems/mkdocs-img2fig-plugin) plugin): 217 | 218 |
219 | 220 |
Image caption
221 |
222 | 223 |
224 | 225 |
Another image caption
226 |
227 | 228 | ![](https://play-lh.googleusercontent.com/JHDqEqU0QNC8vsa5_UsPAws5X1OvTVPcfDVLnV1WXhoYrEX81sE6fL7cmamStPrK_A=w1440-h620-rw "A cat playing") 229 | 230 | ![](https://play-lh.googleusercontent.com/tKuOgQBwDTjhZg3DjCdZVTSVa9X9iMrtrM_1JDH6Ky_YyQeKw_bnFDy0tj1aZ39TDnI=w1440-h620-r "Another cat playing") 231 | 232 | ![](https://play-lh.googleusercontent.com/4CPahw1_E0b61tZKq4QI1bw_dqR6bYy0aDiNWrn-MCoz9Wq5bNyhKywfVlK01nNKR-A=w1440-h620-r "More cats that play") 233 | 234 | ![](https://play-lh.googleusercontent.com/5DeXBFITrh81XB68XxvJGvat5bwVj2ELVdSXNb6mGdvohZtnUoUl5kkPLPSrgtN9XHk=w1440-h620-r "The internet loves cats") 235 | 236 | 237 | ### Lists 238 | 239 | 1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis 240 | sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis 241 | nulla. Vivamus a pharetra leo. 242 | 243 | 1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet 244 | quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a 245 | ultricies libero efficitur sed. 246 | 247 | 2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet 248 | rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a. 249 | 250 | 1. Mauris dictum mi lacus 251 | 2. Ut sit amet placerat ante 252 | 3. Suspendisse ac eros arcu 253 | 254 | `Lorem ipsum dolor sit amet` 255 | : Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus 256 | tellus non sem sollicitudin, quis rutrum leo facilisis. 257 | 258 | `Cras arcu libero` 259 | : Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin 260 | ut eros sed sapien ullamcorper consequat. Nunc ligula ante. 261 | 262 | Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. 263 | Nam vulputate tincidunt fringilla. 264 | Nullam dignissim ultrices urna non auctor. 265 | 266 | * [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit 267 | * [ ] Vestibulum convallis sit amet nisi a tincidunt 268 | * [x] In hac habitasse platea dictumst 269 | * [x] In scelerisque nibh non dolor mollis congue sed et metus 270 | * [ ] Praesent sed risus massa 271 | * [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque 272 | 273 | $$ 274 | \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} 275 | $$ 276 | 277 | The homomorphism $f$ is injective if and only if its kernel is only the 278 | singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such 279 | that $f(a)=f(b)$00. 280 | 281 | ## Dummy section 282 | 283 | This section has an incoming anchor link, at the top of this page 284 | 285 | ## Some [lorem ipsum](https://www.lipsum.com/) 286 | 287 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut eget mi lacinia arcu ultrices rutrum eget a lacus. Etiam erat mi, sodales at nisl vel, bibendum tempor nunc. Cras in ultrices augue. Cras aliquam in mauris et semper. In hac habitasse platea dictumst. Proin dignissim scelerisque risus, consectetur ornare justo ultrices eu. Quisque tempus, elit eu ullamcorper interdum, metus augue pulvinar lectus, nec dictum mi dolor non turpis. Sed condimentum vulputate pretium. 288 | 289 | Nulla at nisl tortor. Praesent vitae turpis sit amet sem condimentum fermentum eget nec dolor. Maecenas et imperdiet ante, at ultrices orci. Nunc ornare sodales enim. Sed tempor vitae mi et faucibus. Nunc aliquam est sit amet mauris tempus varius. Aenean blandit vel nibh nec sagittis. Sed vehicula nunc a nunc vehicula viverra. Proin risus justo, ullamcorper ac sem a, vulputate ornare justo. Sed facilisis pharetra elit, vitae dignissim nibh iaculis eu. Suspendisse potenti. Curabitur quis arcu ac est faucibus suscipit vel non lacus. 290 | 291 | Ut tincidunt sapien sed sem auctor, et pellentesque erat tristique. Nunc porttitor lacus diam, eu malesuada nibh venenatis in. Donec sit amet enim eget enim facilisis placerat nec eget tortor. Etiam imperdiet, felis ac posuere dignissim, nulla sapien auctor mauris, ac aliquam orci leo nec dui. Donec efficitur turpis quis enim efficitur, eu ornare nisi consectetur. Sed ac arcu at orci pretium lobortis luctus non augue. Duis posuere purus at semper fringilla. Pellentesque facilisis libero vestibulum elit varius iaculis. Donec dapibus pretium scelerisque. 292 | 293 | Suspendisse non orci vitae lorem placerat pretium vitae a ex. Nunc facilisis aliquam risus in vehicula. Fusce sodales bibendum lectus id ultricies. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. In cursus blandit quam ac bibendum. Interdum et malesuada fames ac ante ipsum primis in faucibus. Ut commodo tellus vel interdum vulputate. Nulla in turpis tellus. Mauris at semper ex. Nulla varius leo eu libero placerat, quis euismod orci euismod. Phasellus pulvinar ut sapien nec elementum. Maecenas vel mi eros. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus volutpat massa vel purus interdum imperdiet. Curabitur congue turpis eget faucibus varius. Aenean eleifend placerat lorem vel vestibulum. 294 | 295 | Nullam in posuere urna. Sed cursus est porta maximus dignissim. Etiam id ante libero. Curabitur ac rhoncus turpis. Cras eu ipsum lacus. Aliquam ac rutrum elit. Donec pharetra in arcu feugiat interdum. Nam sed libero semper, sollicitudin urna vel, tincidunt nulla. Curabitur dapibus massa lectus, vulputate fermentum est finibus et. Ut efficitur velit nec justo varius tempor. Nullam aliquet commodo enim eget lobortis. Nullam sit amet nunc viverra, iaculis sem non, scelerisque mauris. Vivamus eu finibus lacus, dignissim luctus elit. -------------------------------------------------------------------------------- /docs/how-to/banner.md: -------------------------------------------------------------------------------- 1 | # Customize the print site banner 2 | 3 | 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. 4 | 5 | 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)). 6 | 7 | _Example_: 8 | 9 | === "mkdocs.yml" 10 | 11 | ```yaml 12 | plugins: 13 | - print-site: 14 | add_print_site_banner: true 15 | print_site_banner_template: "docs/assets/templates/custom_banner.tpl" 16 | ``` 17 | 18 | === "docs/assets/templates/custom_banner.tpl" 19 | 20 | ```jinja 21 |

22 | This box will disappear when printing 23 | mkdocs-print-site-plugin 24 |

25 |

This page has combined all site pages into one. You can export to PDF using File > Print > Save as PDF.

26 |

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).

27 | ``` 28 | 29 | 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). 30 | 31 | ## Adding configurable content 32 | 33 | You might want to add some content to your print banner that's not yet specified in your `mkdocs.yml` file. 34 | 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. }}`. 35 | 36 | _Example_: 37 | 38 | === "mkdocs.yml" 39 | 40 | ```yaml 41 | plugins: 42 | - print-site: 43 | add_print_site_banner: true 44 | print_site_banner_template: "docs/assets/templates/custom_banner.tpl" 45 | 46 | extra: 47 | banner_message: "Save this page using File > Print > Save as PDF" 48 | ``` 49 | 50 | === "docs/assets/templates/custom_banner.tpl" 51 | 52 | ```jinja 53 |

54 | This box will disappear when printing 55 | mkdocs-print-site-plugin 56 |

57 |

{{ config.extra.banner_message }}

58 | ``` 59 | 60 | 61 | -------------------------------------------------------------------------------- /docs/how-to/cover_page.md: -------------------------------------------------------------------------------- 1 | # Customize the cover page 2 | 3 | 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. 4 | 5 | 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)). 6 | 7 | _Example_: 8 | 9 | === "mkdocs.yml" 10 | 11 | ```yaml 12 | plugins: 13 | - print-site: 14 | add_cover_page: true 15 | cover_page_template: "docs/assets/templates/custom_cover_page.tpl" 16 | ``` 17 | 18 | === "docs/assets/templates/custom_cover_page.tpl" 19 | 20 | ```jinja 21 | {% if config.site_name %} 22 |

{{ config.site_name }}

23 | {% endif %} 24 |

This is my custom print cover page

25 | ``` 26 | 27 | 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). 28 | 29 | ## Adding images 30 | 31 | When adding images to your custom cover page template, make sure to define the image source as the hosted image path. The url for the image stored in `docs/assets/img/example.png` would be `/assets/img/example.png`. 32 | 33 | _Example_: 34 | 35 | === "docs/assets/templates/custom_cover_page.tpl" 36 | 37 | ```jinja 38 | {% if config.site_name %} 39 |

{{ config.site_name }}

40 | {% endif %} 41 | 42 | ``` 43 | 44 | 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). 45 | 46 | ## Adding configurable content 47 | 48 | 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. }}`. 49 | 50 | _Example_: 51 | 52 | === "mkdocs.yml" 53 | 54 | ```yaml 55 | plugins: 56 | - print-site: 57 | add_cover_page: true 58 | cover_page_template: "docs/assets/templates/custom_cover_page.tpl" 59 | 60 | extra: 61 | abstract: This is a report about a topic 62 | ``` 63 | 64 | === "docs/assets/templates/custom_cover_page.tpl" 65 | 66 | ```jinja 67 | {% if config.site_name %} 68 |

{{ config.site_name }}

69 | {% endif %} 70 |

{{ config.extra.abstract }}

71 | ``` 72 | 73 | ## Change the styling 74 | 75 | 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 `
`. You should use this in your CSS to ensure not affecting other pages. 76 | 77 | _Example_: 78 | 79 | === "mkdocs.yml" 80 | 81 | ```yaml 82 | plugins: 83 | - print-site: 84 | add_cover_page: true 85 | 86 | extra_css: 87 | - docs/assets/css/my_cover_page.css 88 | ``` 89 | 90 | === "docs/assets/css/my_cover_page.css" 91 | 92 | ```css 93 | #print-site-cover-page h1 { 94 | color: blue; 95 | } 96 | ``` 97 | -------------------------------------------------------------------------------- /docs/how-to/do_not_print.md: -------------------------------------------------------------------------------- 1 | # Exclude content from print 2 | 3 | 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. 4 | 5 | ## Ignoring elements in a page 6 | 7 | `mkdocs-print-site-plugin` offers the CSS class `.print-site-plugin-ignore`, that will ignore certain elements. 8 | 9 | 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`. 10 | 11 | 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. 12 | 13 | _Example_: 14 | 15 | === "mkdocs.yml" 16 | 17 | ```yaml 18 | plugins: 19 | - print-site 20 | 21 | markdown_extensions: 22 | - attr_list 23 | ``` 24 | 25 | === "docs/example.md" 26 | 27 | ```md 28 | # Example page 29 | 30 | This paragraph will not be part of the print site page. 31 | {: .print-site-plugin-ignore } 32 | 33 | ![ignored image](some/path/image.png){: .print-site-plugin-ignore } 34 | 35 | You can also use HTML to hide things from printing: 36 | hello 37 | ``` 38 | 39 | As another example, this paragraph will not be printed. Go have a look at the [print site page](/print_page.html) and you'll find it missing. 40 | {: .print-site-plugin-ignore } 41 | 42 | ## Ignoring admonitions 43 | 44 | 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. 45 | 46 | _Example_: 47 | 48 | ```markdown 49 | !!! info print-site-plugin-ignore 50 | 51 | As an example, this admonition will not be printed. Go have a look at the [print site page](/print_page.html) and you'll find it missing. 52 | ``` 53 | 54 | Which renders as: 55 | 56 | !!! info print-site-plugin-ignore 57 | 58 | As an example, this admonition will not be printed. Go have a look at the [print site page](/print_page.html) and you'll find it missing. 59 | 60 | 61 | ## Ignoring an entire page 62 | 63 | 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`. 64 | 65 | _Example_: 66 | 67 | ```yml 68 | # mkdocs.yml 69 | plugins: 70 | - print-site: 71 | exclude: 72 | - index.md 73 | - subfolder/page.md 74 | - another_page.md 75 | - folder/* 76 | ``` -------------------------------------------------------------------------------- /docs/how-to/export-HTML.md: -------------------------------------------------------------------------------- 1 | # Export to HTML 2 | 3 | After enabling the `print-site` plugin in your `mkdocs.yml`, you will have your entire site combined into a single page. 4 | 5 | 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. 6 | This works because all the resources the page uses, such images, stylesheets (CSS) and interactive elements (javascript) are embedded into in a single HTML file using [data URLs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs). 7 | 8 | You can create a .html file export using your internet browser (f.e. save as > webpage, single page). You can also do this programmatically, for example using the [htmlark](https://github.com/BitLooter/htmlark) python package: 9 | 10 | ```shell 11 | pip install htmlark[http,parsers] 12 | ``` 13 | 14 | To create the export: 15 | 16 | ```shell 17 | mkdocs build 18 | cd site/ 19 | 20 | # when mkdocs.yml has use_directory_urls: true (the default) 21 | htmlark print_page/index.html -o standalone.html 22 | 23 | # when mkdocs.yml has use_directory_urls: false 24 | htmlark print_page.html -o standalone.html 25 | ``` 26 | -------------------------------------------------------------------------------- /docs/how-to/export-PDF.md: -------------------------------------------------------------------------------- 1 | # Export to PDF 2 | 3 | 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*. 4 | 5 | If you want to automatically create PDFs of your mkdocs website, you can automate the process using a headless chrome plugin. 6 | 7 | If you need more control over the PDF layout, I recommend the [mkdocs-with-pdf](https://github.com/orzih/mkdocs-with-pdf) plugin. 8 | 9 | ??? warning "Avoid creating PDFs with Firefox" 10 | Firefox has some issues with print margins cutting of content, and anchors links not working properly. 11 | For more details see [mkdocs-print-site-plugin#56](https://github.com/timvink/mkdocs-print-site-plugin/issues/56) 12 | 13 | ## Automated export using nodejs and chrome 14 | 15 | We can use [nodejs](https://nodejs.org/en/) together with the [puppeteer](https://github.com/puppeteer/puppeteer) headless chrome node.js package: 16 | 17 | - Install [nodejs](https://nodejs.org/en/) 18 | - Download puppeteer in the root of your project using the node package manager: `npm i --save puppeteer` 19 | - Save the script `export_to_pdf.js` (see below) in the root of your project 20 | - Start a webserver with your site (`mkdocs serve`) 21 | - 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: 22 | 23 | ```shell 24 | node export_to_pdf.js http://localhost:8000/print_page.html out.pdf 'title' 25 | ``` 26 | 27 | ??? example "export_to_pdf.js" 28 | 29 | ```js 30 | // Credits for script: https://github.com/majkinetor/mm-docs-template/blob/master/source/pdf/print.js 31 | // Requires: npm i --save puppeteer 32 | 33 | const puppeteer = require('puppeteer'); 34 | var args = process.argv.slice(2); 35 | var url = args[0]; 36 | var pdfPath = args[1]; 37 | var title = args[2]; 38 | 39 | console.log('Saving', url, 'to', pdfPath); 40 | 41 | // date – formatted print date 42 | // title – document title 43 | // url – document location 44 | // pageNumber – current page number 45 | // totalPages – total pages in the document 46 | headerHtml = ` 47 |
48 | ${title} / 49 |
`; 50 | 51 | footerHtml = ` `; 52 | 53 | 54 | (async() => { 55 | const browser = await puppeteer.launch({ 56 | headless: true, 57 | executablePath: process.env.CHROME_BIN || null, 58 | args: ['--no-sandbox', '--headless', '--disable-gpu', '--disable-dev-shm-usage'] 59 | }); 60 | 61 | const page = await browser.newPage(); 62 | await page.goto(url, { waitUntil: 'networkidle2' }); 63 | await page.pdf({ 64 | path: pdfPath, // path to save pdf file 65 | format: 'A4', // page format 66 | displayHeaderFooter: true, // display header and footer (in this example, required!) 67 | printBackground: true, // print background 68 | landscape: false, // use horizontal page layout 69 | headerTemplate: headerHtml, // indicate html template for header 70 | footerTemplate: footerHtml, 71 | scale: 1, //Scale amount must be between 0.1 and 2 72 | margin: { // increase margins (in this example, required!) 73 | top: 80, 74 | bottom: 80, 75 | left: 30, 76 | right: 30 77 | } 78 | }); 79 | 80 | await browser.close(); 81 | })(); 82 | ``` 83 | 84 | -------------------------------------------------------------------------------- /docs/how-to/pdf_button.md: -------------------------------------------------------------------------------- 1 | # Adding a PDF button 2 | 3 | Having users create a PDF of your website requires them to navigate to the print page and *File > Print > Save as PDF* (see [export to PDF](export-PDF.md)). You can make downloading a PDF version of your website even easier for your users by including a 'PDF' button on every page (like the one in the right corner of this page 👆). 4 | 5 | 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. That will allow you to add a button to the top of every page. 6 | 7 | This plugin adds to the context a `page.url_to_print_page` which contains the relative link from a page to the print page. You can use `page.url_to_print_page` when customizing a theme: 8 | 9 | !!! info "Exporting to PDF is a separate step" 10 | While it might be easier for your users, using this option means you need to re-create the PDF everytime you make a change to your website. See [how to export to PDF](pdf_button.md). 11 | 12 | If you use this option and you are using version control like git, you might want to also [gitignore](https://git-scm.com/docs/gitignore) the PDF file. 13 | 14 | ## Adding a PDF button to mkdocs-material theme 15 | 16 | In the [mkdocs-material](https://squidfunk.github.io/mkdocs-material) theme you can create an override for `main.html` (see [customization](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks)). 17 | 18 | _Example_: 19 | 20 | === "mkdocs.yml" 21 | 22 | ```yaml 23 | theme: 24 | name: material 25 | custom_dir: docs/overrides 26 | 27 | plugins: 28 | - print-site: 29 | path_to_pdf: "assets/the_name_of_your_file.pdf" 30 | ``` 31 | 32 | === "docs/overrides/main.html" 33 | 34 | ```jinja 35 | {% extends "base.html" %} 36 | 37 | {% block content %} 38 | 39 | {% if page.url_to_pdf %} 40 | 41 | {% include ".icons/material/file-pdf-box.svg" %} 42 | 43 | {% endif %} 44 | 45 | {{ super() }} 46 | {% endblock content %} 47 | ``` 48 | 49 | 50 | ## Adding a print button to mkdocs theme 51 | 52 | You can also [customize](https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme) the base mkdocs theme, by overriding `main.html`. 53 | 54 | _Example_: 55 | 56 | === "mkdocs.yml" 57 | 58 | ```yaml 59 | theme: 60 | name: mkdocs 61 | custom_dir: docs/overrides 62 | 63 | plugins: 64 | - print-site: 65 | path_to_pdf: "assets/the_name_of_your_file.pdf" 66 | ``` 67 | 68 | === "docs/overrides/main.html" 69 | 70 | ```jinja 71 | {% extends "base.html" %} 72 | 73 | {% block repo %} 74 | {% if page.url_to_pdf %} 75 |
  • 76 | 77 | PDF 78 | 79 |
    • 80 | {% endif %} 81 | 82 | {{ super() }} 83 | {% endblock repo %} 84 | ``` 85 | -------------------------------------------------------------------------------- /docs/how-to/print_button.md: -------------------------------------------------------------------------------- 1 | # Adding a print button 2 | 3 | You might want to customize your site to include a 'print' button on every page that will lead to the print page. See the example in the top right corner of this page 👆. 4 | 5 | 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. That will allow you to add a button to the top of every page. 6 | 7 | This plugin adds to the context a `page.url_to_print_page` which contains the relative link from a page to the print page. You can use `page.url_to_print_page` when customizing a theme: 8 | 9 | ## Adding a print button to mkdocs-material theme 10 | 11 | In the [mkdocs-material](https://squidfunk.github.io/mkdocs-material) theme you can create an override for `main.html` (see [customization](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks)). 12 | 13 | _Example_: 14 | 15 | === "mkdocs.yml" 16 | 17 | ```yaml 18 | theme: 19 | name: material 20 | custom_dir: docs/overrides 21 | 22 | plugins: 23 | - print-site 24 | ``` 25 | 26 | === "docs/overrides/main.html" 27 | 28 | ```jinja 29 | {% extends "base.html" %} 30 | 31 | {% block content %} 32 | 33 | {% if page.url_to_print_page %} 34 | 35 | {% include ".icons/material/printer.svg" %} 36 | 37 | {% endif %} 38 | 39 | {{ super() }} 40 | {% endblock content %} 41 | ``` 42 | 43 | 44 | ## Adding a print button to mkdocs theme 45 | 46 | You can also [customize](https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme) the base mkdocs theme, by overriding `main.html`. 47 | 48 | _Example_: 49 | 50 | === "mkdocs.yml" 51 | 52 | ```yaml 53 | theme: 54 | name: mkdocs 55 | custom_dir: docs/overrides 56 | 57 | plugins: 58 | - print-site 59 | ``` 60 | 61 | === "docs/overrides/main.html" 62 | 63 | ```jinja 64 | {% extends "base.html" %} 65 | 66 | {% block repo %} 67 | {% if page.url_to_print_page %} 68 |
  • 69 | 70 | Print 71 | 72 |
    • 73 | {% endif %} 74 | 75 | {{ super() }} 76 | {% endblock repo %} 77 | ``` 78 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | [![Actions Status](https://github.com/timvink/mkdocs-print-site-plugin/workflows/pytest/badge.svg)](https://github.com/timvink/mkdocs-print-site-plugin/actions) 2 | ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-print-site-plugin) 3 | ![PyPI](https://img.shields.io/pypi/v/mkdocs-print-site-plugin) 4 | ![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-print-site-plugin) 5 | [![codecov](https://codecov.io/gh/timvink/mkdocs-print-site-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/timvink/mkdocs-print-site-plugin) 6 | ![GitHub contributors](https://img.shields.io/github/contributors/timvink/mkdocs-print-site-plugin) 7 | ![PyPI - License](https://img.shields.io/pypi/l/mkdocs-print-site-plugin) 8 | 9 | # mkdocs-print-site-plugin 10 | 11 | [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. 12 | 13 | ## Installation 14 | 15 | Install the plugin using `pip3`: 16 | 17 | ```bash 18 | pip3 install mkdocs-print-site-plugin 19 | ``` 20 | 21 | Next, add the following lines to your `mkdocs.yml`: 22 | 23 | ```yaml 24 | plugins: 25 | - search 26 | - print-site 27 | ``` 28 | 29 | > :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. 30 | 31 | > 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. 32 | 33 | ## Usage 34 | 35 | - Navigate to `/print_page/` or `print_page.html` 36 | - Export to standalone HTML (see [export to HTML](how-to/export-HTML.md)) 37 | - Export to PDF using your browser using *File > Print > Save as PDF* (see [export to PDF](how-to/export-PDF.md)) 38 | -------------------------------------------------------------------------------- /docs/javascripts/config.js: -------------------------------------------------------------------------------- 1 | window.MathJax = { 2 | tex: { 3 | inlineMath: [["\\(", "\\)"]], 4 | displayMath: [["\\[", "\\]"]], 5 | processEscapes: true, 6 | processEnvironments: true 7 | }, 8 | options: { 9 | ignoreHtmlClass: ".*|", 10 | processHtmlClass: "arithmatex" 11 | } 12 | }; 13 | -------------------------------------------------------------------------------- /docs/options.md: -------------------------------------------------------------------------------- 1 | # Options 2 | 3 | You can customize `mkdocs-print-site-plugin` in your `mkdocs.yml` with the following settings: 4 | 5 | ```yaml 6 | plugins: 7 | - print-site: 8 | add_to_navigation: false 9 | print_page_title: 'Print Site' 10 | print_page_basename: 'print_page' 11 | add_print_site_banner: false 12 | # Table of contents 13 | add_table_of_contents: true 14 | toc_title: 'Table of Contents' 15 | toc_depth: 6 16 | # Content-related 17 | add_full_urls: false 18 | enumerate_headings: true 19 | enumerate_figures: true 20 | add_cover_page: true 21 | cover_page_template: "" 22 | path_to_pdf: "" 23 | include_css: true 24 | enabled: true 25 | exclude: 26 | ``` 27 | 28 | `add_to_navigation` 29 | : Default is `false`. Adds a link 'Print Site' to your site navigation. You can also set to `false` and explicitly include the link in your navigation (`/print_page` or `/print_page.html`). 30 | 31 | `print_page_title` 32 | : Default is `'Print Site'`. When `add_to_navigation` is set to `true` this setting controls the name of the print page in the navigation of the site. This setting is ignored when `add_to_navigation` is set to `false`. 33 | 34 | `print_page_basename` 35 | : Default is `'print_page'`. Can be used to cutomized the path to the print page in the URL. 36 | 37 | `add_table_of_contents` 38 | : Default is `true`. Adds a table of contents section at the beginning of the print page (in print version, the HTML version has a different sidebar ToC). 39 | 40 | `toc_title` 41 | : Default is `'Table of Contents'`. When `add_table_of_contents` is set to `true` this setting controls the name of the table of contents of the print version of the print page. This setting is ignored when `add_table_of_contents` is set to `false`. 42 | 43 | `toc_depth` 44 | : Default is `3`. When `add_table_of_contents` is set to `true` this setting controls the depth of the table of contents in the print version of the print page. This setting is ignored when `add_table_of_contents` is set to `false`. 45 | 46 | `add_full_urls` 47 | : Default is `false`. When printing a page, you cannot see the target of a link. This option adds the target url in parenthesis behind a link. 48 | 49 | For example "[google.com](https://www.google.com)" will be replaced by "[google.com](https://www.google.com) (https://www.google.com)" 50 | 51 | `enumerate_headings` 52 | : Default `true`. This will add numbering (enumeration) to all headings and sections, as well as the table of contents. Note this will only enumerate the print site page; if you want to enumerate the entire site, you can use [mkdocs-enumerate-headings-plugin](https://github.com/timvink/mkdocs-enumerate-headings-plugin). 53 | 54 | Example "1.2 A chapter subsection". 55 | 56 | `enumerate_headings_depth` 57 | : Default `6`. If `enumerate_headings`, the depth until which headings and sections are enumerated. 58 | 59 | `enumerate_figures` 60 | : Default `true`. This will add numbering to all figure captions (for example "Figure 1: "). Works especially well with [mkdocs-img2fig-plugin](https://github.com/stuebersystems/mkdocs-img2fig-plugin). 61 | 62 | `add_cover_page` 63 | : 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) 64 | 65 | `cover_page_template` 66 | : Default `""`. The path to a custom cover page template to use. See [Customizing the Cover Page](how-to/cover_page.md) for more info. 67 | 68 | `add_print_site_banner` 69 | : 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. See [Customizing the print site banner](how-to/banner.md) for more info. 70 | 71 | `print_site_banner_template` 72 | : 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. 73 | 74 | `path_to_pdf` 75 | : 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. 76 | 77 | `include_css` 78 | : Default is `true`. When disabled the [print-site stylesheets](https://github.com/timvink/mkdocs-print-site-plugin/tree/master/mkdocs_print_site_plugin/css) are not included. This makes it easy to overwrite the CSS with your own stylesheets, using the [extra_css](https://www.mkdocs.org/user-guide/configuration/#extra_css) option in your `mkdocs.yml` file. 79 | 80 | `enabled` 81 | : 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: 82 | 83 | ```yaml 84 | # mkdocs.yml 85 | plugins: 86 | - print-site: 87 | enabled: !ENV [ENABLED_PRINT_SITE, True] 88 | ``` 89 | 90 | Which enables you do disable the plugin locally using: 91 | 92 | ```bash 93 | export ENABLED_PRINT_SITE=false 94 | mkdocs serve 95 | ``` 96 | 97 | `exclude` 98 | : Default is empty. Allows to specify a list of page source paths that should not be included in the print page. Supports [glob](https://docs.python.org/3/library/glob.html)-like syntax such as `folder/` or `folder/*`. See [Do Not Print](how-to/do_not_print.md#ignoring-an-entire-page) for more info on excluding pages. -------------------------------------------------------------------------------- /docs/overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | {% block content %} 4 | {% if page.url_to_print_page %} 5 | 6 | {% include ".icons/material/printer.svg" %} 7 | 8 | {% endif %} 9 | {% if page.url_to_pdf %} 10 | 11 | {% include ".icons/material/file-pdf-box.svg" %} 12 | 13 | {% endif %} 14 | 15 | {{ super() }} 16 | {% endblock content %} -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Documentation mkdocs-print-site-plugin 2 | repo_url: https://github.com/timvink/mkdocs-print-site-plugin 3 | site_url: https://timvink.github.io/mkdocs-print-site-plugin/ 4 | site_description: MkDocs Plugin allowing your site visitors to *File > Print > Save as PDF* the entire site. 5 | site_author: Tim Vink 6 | copyright: Copyright © 2024 Maintained by Tim Vink. 7 | 8 | use_directory_urls: false 9 | 10 | plugins: 11 | - search 12 | - charts 13 | - git-revision-date-localized: 14 | type: timeago 15 | timezone: Europe/Amsterdam 16 | locale: en 17 | fallback_to_build_date: false 18 | enable_creation_date: true 19 | - print-site: 20 | add_to_navigation: true 21 | add_full_urls: false 22 | add_table_of_contents: true 23 | toc_title: "Table of Contents" 24 | toc_depth: 2 25 | enumerate_headings: true 26 | enumerate_figures: true 27 | add_cover_page: true 28 | path_to_pdf: "assets/site.pdf" 29 | 30 | 31 | nav: 32 | - Home: index.md 33 | - Options: options.md 34 | - How to guides: 35 | - Export to PDF: how-to/export-PDF.md 36 | - Export to HTML: how-to/export-HTML.md 37 | - Add a print button: how-to/print_button.md 38 | - Add a PDF button: how-to/pdf_button.md 39 | - Add a cover page: how-to/cover_page.md 40 | - Add a banner: how-to/banner.md 41 | - Exclude content: how-to/do_not_print.md 42 | - Demo Content: demo_content.md 43 | - Contributing: contributing.md 44 | 45 | theme: 46 | name: material 47 | custom_dir: docs/overrides 48 | icon: 49 | admonition: 50 | example: fontawesome/solid/flask 51 | palette: 52 | - media: "(prefers-color-scheme: light)" 53 | scheme: default 54 | toggle: 55 | icon: material/toggle-switch-off-outline 56 | name: Switch to dark mode 57 | primary: blue 58 | accent: blue 59 | - media: "(prefers-color-scheme: dark)" 60 | scheme: slate 61 | toggle: 62 | icon: material/toggle-switch 63 | name: Switch to light mode 64 | primary: blue 65 | accent: blue 66 | 67 | markdown_extensions: 68 | - codehilite: 69 | linenums: false 70 | guess_lang: false 71 | - attr_list 72 | - def_list 73 | - admonition 74 | - footnotes 75 | - pymdownx.details 76 | - pymdownx.tabbed 77 | - pymdownx.superfences: 78 | custom_fences: 79 | - name: vegalite 80 | class: vegalite 81 | format: !!python/name:mkdocs_charts_plugin.fences.fence_vegalite 82 | - pymdownx.keys 83 | - pymdownx.magiclink 84 | - pymdownx.snippets 85 | - pymdownx.emoji: 86 | emoji_index: !!python/name:material.extensions.emoji.twemoji 87 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 88 | - pymdownx.inlinehilite 89 | - pymdownx.highlight: 90 | use_pygments: true 91 | - pymdownx.critic: 92 | mode: view 93 | - pymdownx.betterem: 94 | smart_enable: all 95 | - pymdownx.tasklist: 96 | custom_checkbox: true 97 | - pymdownx.tasklist: 98 | clickable_checkbox: true 99 | - pymdownx.arithmatex: 100 | generic: true 101 | - pymdownx.caret 102 | - pymdownx.mark 103 | - pymdownx.tilde 104 | - pymdownx.smartsymbols 105 | - toc: 106 | permalink: ↵ 107 | 108 | extra_javascript: 109 | - javascripts/config.js 110 | - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js 111 | - https://cdn.jsdelivr.net/npm/vega@5 112 | - https://cdn.jsdelivr.net/npm/vega-lite@5 113 | - https://cdn.jsdelivr.net/npm/vega-embed@6 114 | 115 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools>=70.0", "setuptools-scm>=8.0"] 3 | build-backend = "setuptools.build_meta" 4 | 5 | [project.entry-points."mkdocs.plugins"] 6 | "print-site" = "mkdocs_print_site_plugin.plugin:PrintSitePlugin" 7 | 8 | [project] 9 | name="mkdocs-print-site-plugin" 10 | keywords = ["mkdocs", "plugin","print","pdf"] 11 | authors = [ 12 | { name = "Tim Vink", email = "vinktim@gmail.com" } 13 | ] 14 | license = { text = "MIT" } 15 | 16 | description="MkDocs plugin that combines all pages into one, allowing for easy export to PDF and standalone HTML." 17 | readme = { file = "README.md", content-type = "text/markdown" } 18 | 19 | requires-python=">=3.8" 20 | 21 | classifiers=[ 22 | "Operating System :: OS Independent", 23 | "Programming Language :: Python", 24 | "Programming Language :: Python :: 3", 25 | "Programming Language :: Python :: 3.8", 26 | "Programming Language :: Python :: 3.9", 27 | "Programming Language :: Python :: 3.10", 28 | "Programming Language :: Python :: 3.11", 29 | "License :: OSI Approved :: MIT License", 30 | "Topic :: Documentation", 31 | "Topic :: Text Processing", 32 | ] 33 | 34 | dynamic = ["version"] 35 | dependencies = [ 36 | "mkdocs-material>=7.3.0", 37 | ] 38 | 39 | [project.urls] 40 | "Homepage" = "https://github.com/timvink/mkdocs-print-site-plugin" 41 | 42 | [tool.setuptools.dynamic] 43 | version = {attr = "mkdocs_print_site_plugin.__version__"} 44 | 45 | [tool.pytest.ini_options] 46 | markers = [ 47 | "integration: marks tests as integration, meaning they use databases (deselect with '-m \"not integration\"')", 48 | "serial", 49 | "no_temp_caching", 50 | ] 51 | 52 | # https://github.com/charliermarsh/ruff 53 | [tool.ruff] 54 | 55 | # Rules to apply 56 | lint.select= ["E", "F", "I", "UP"] 57 | 58 | # Exclude rules 59 | lint.ignore = ['D104' 60 | ,'D212' 61 | ,'D200' 62 | ,'D412' 63 | ,'E731' 64 | ,'E501' 65 | ,'E722' 66 | ,'D104' 67 | ,'E402' 68 | ,"UP038" # UP038 Use `X | Y` in `isinstance` call instead of `(X, Y)` 69 | ] 70 | 71 | # Exclude files in tests dir 72 | lint.exclude = [ 73 | ".bzr", 74 | ".direnv", 75 | ".eggs", 76 | ".git", 77 | ".hg", 78 | ".mypy_cache", 79 | ".nox", 80 | ".pants.d", 81 | ".pytype", 82 | ".ruff_cache", 83 | ".svn", 84 | ".tox", 85 | ".venv", 86 | "__pypackages__", 87 | "_build", 88 | "buck-out", 89 | "build", 90 | "dist", 91 | "node_modules", 92 | "venv", 93 | ] 94 | 95 | # Set line length, keep same as black 96 | line-length = 120 97 | 98 | extend-exclude = [ 99 | "*.yml", 100 | "*.toml", 101 | "*.md", 102 | ".json", 103 | "Makefile", 104 | "*.txt", 105 | ] 106 | 107 | #supported for python 3.10 108 | target-version = "py310" 109 | 110 | # Always autofix 111 | fix = true 112 | 113 | [dependency-groups] 114 | dev = [ 115 | "click>=8.1.8", 116 | "mkdocs>=1.6.1", 117 | "mkdocs-charts-plugin>=0.0.12", 118 | "mkdocs-git-revision-date-localized-plugin>=1.4.4", 119 | "mkdocs-img2fig-plugin>=0.9.3", 120 | "mkdocs-material>=9.6.7", 121 | "mkdocs-windmill>=1.0.5", 122 | "mypy>=1.14.1", 123 | "pytest>=8.3.5", 124 | "pytest-cov>=5.0.0", 125 | "ruff>=0.9.10", 126 | ] 127 | 128 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/__init__.py: -------------------------------------------------------------------------------- 1 | __version__ = "2.7.3" 2 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/css/print-site-material.css: -------------------------------------------------------------------------------- 1 | /* print styles for mkdocs material theme 2 | https://github.com/squidfunk/mkdocs-material */ 3 | 4 | 5 | /* Table of Contents styling */ 6 | #print-site-page ul.toc-section-line-border { 7 | border-left: 5px solid var(--md-default-fg-color--lightest); 8 | } 9 | 10 | 11 | /* Box shadows don't do well in PDFs */ 12 | #print-site-page table { 13 | border: 1px solid hsla(200, 18%, 26%, 1); /* #EFEFEF */ 14 | box-shadow: none !important; 15 | } 16 | 17 | @media print { 18 | #print-site-page td { 19 | word-wrap: break-word; 20 | } 21 | 22 | } 23 | 24 | @page { 25 | 26 | size: A4 portrait; 27 | margin: 4em 1.5em 4em 1.5em; 28 | padding: 0em 0em 0em 0em; 29 | counter-increment: page; 30 | 31 | @bottom-center { 32 | content: string(chapter); 33 | } 34 | @bottom-right { 35 | content: 'Page ' counter(page); 36 | } 37 | 38 | } -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/css/print-site-mkdocs.css: -------------------------------------------------------------------------------- 1 | /* Print styles for default MkDocs theme */ 2 | 3 | #print-site-banner { 4 | padding-top: 1em; 5 | } 6 | 7 | 8 | /* Table of contents, proper padding */ 9 | .print-page-toc-title { 10 | padding-bottom: 0em; 11 | margin-bottom: 1em; 12 | } 13 | /* Table of contents, compatible with dark theme */ 14 | #print-site-page ul.toc-section-line-border { 15 | border-left: 5px solid rgb(225, 225, 225); 16 | } 17 | 18 | @media print { 19 | 20 | /* Hide side TOC banner 21 | Note the side will also disappear when printing other pages, 22 | but it doesn't print well so I see this as acceptable behaviour 23 | */ 24 | .col-md-3 { display: none !important; } 25 | } 26 | 27 | @page { 28 | 29 | /* 30 | Note this CSS file is added to all MkDocs pages 31 | So this @page logic will affect print of all pages 32 | */ 33 | 34 | size: a4 portrait; 35 | margin: 15mm 10mm 15mm 10mm; 36 | counter-increment: page; 37 | 38 | @bottom-center { 39 | content: string(chapter); 40 | } 41 | @bottom-right { 42 | content: 'Page ' counter(page); 43 | } 44 | } -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/css/print-site-readthedocs.css: -------------------------------------------------------------------------------- 1 | /* Print styles for readthedocs theme */ 2 | 3 | #print-site-banner { 4 | padding-top: 1em; 5 | } 6 | 7 | 8 | /* Table of contents, proper padding */ 9 | .print-page-toc-title { 10 | padding-bottom: 0em; 11 | margin-bottom: 1em; 12 | } 13 | /* Table of contents, compatible with dark theme */ 14 | #print-site-page ul.toc-section-line-border { 15 | border-left: 5px solid rgb(225, 225, 225); 16 | } 17 | 18 | @page { 19 | 20 | /* 21 | Note this CSS file is added to all MkDocs pages 22 | So this @page logic will affect print of all pages 23 | */ 24 | 25 | size: a4 portrait; 26 | margin: 15mm 10mm 15mm 10mm; 27 | counter-increment: page; 28 | 29 | @bottom-center { 30 | content: string(chapter); 31 | } 32 | @bottom-right { 33 | content: 'Page ' counter(page); 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/css/print-site.css: -------------------------------------------------------------------------------- 1 | 2 | /* 3 | The print-site banner 4 | */ 5 | #print-site-banner { 6 | border:2px; 7 | border-style:solid; 8 | border-color:#000000; 9 | padding: 0em 1em 0em 1em; 10 | margin-bottom: 2em; 11 | } 12 | #print-site-banner h3 { 13 | margin-top: 1rem; 14 | } 15 | 16 | /* Enumerate figures */ 17 | .print-site-enumerate-figures figcaption:before { 18 | counter-increment: figurecounter; 19 | content: "Figure " counter(figurecounter) ": "; 20 | } 21 | 22 | 23 | /* Print URLS: 24 | Change a 'link' to 'link (target)' */ 25 | div.print-site-add-full-url section.print-page a[href^="http"]::after{ 26 | content: " (" attr(href) ") "; 27 | } 28 | 29 | 30 | /* Do some nice animations when clicking on a ToC link */ 31 | #print-site-page h1:target, 32 | #print-site-page h2:target, 33 | #print-site-page h3:target, 34 | #print-site-page h4:target, 35 | #print-site-page h5:target, 36 | #print-site-page h6:target { 37 | animation: highlight 1.5s ease; 38 | } 39 | #print-site-page .print-page:target h1 { 40 | animation: highlight 1.5s ease; 41 | } 42 | @keyframes highlight { 43 | from { color: orange; } 44 | to { color: none; } 45 | } 46 | 47 | 48 | /* 49 | Print site table of contents styling 50 | */ 51 | /* Don't display the table of contents in HTML version */ 52 | #print-page-toc { display: none } 53 | 54 | 55 | .print-page-toc-nav { 56 | padding-bottom: 2em; 57 | } 58 | 59 | #print-page-toc ul { 60 | list-style-position: inside; 61 | list-style-type: none; 62 | } 63 | 64 | #print-site-page ul { 65 | margin-left: 0em; 66 | } 67 | 68 | /* Be able to not print certain elements */ 69 | #print-site-page .print-site-plugin-ignore { display: none;} 70 | 71 | @media print { 72 | 73 | /* included bookmarks on h1 and h2 74 | Doesn't work, but included In case Chrome gets support 75 | for these experimental CSS features that define PDF bookmarks */ 76 | /* #print-site-page h1 { 77 | bookmark-level: 1; 78 | bookmark-label: content(); 79 | -ah-bookmark-level: 1; 80 | -ro-pdf-bookmark-level: 1; 81 | } 82 | #print-site-page h2 { 83 | bookmark-level: 2; 84 | bookmark-label: content(); 85 | -ah-bookmark-level: 2; 86 | -ro-pdf-bookmark-level: 2; 87 | } */ 88 | 89 | /* Be able to not print certain elements */ 90 | .print-site-plugin-ignore { display: none; } 91 | 92 | /* Remove print site banner */ 93 | #print-site-banner { display: none; } 94 | 95 | /* display the table of contents in print version */ 96 | #print-page-toc { display: block } 97 | 98 | /* PDF page breaks on each MkDocs page, except the first one */ 99 | #print-site-page section.print-page { 100 | page-break-before: always; 101 | } 102 | #print-site-page > section.print-page:first-of-type { 103 | page-break-before: avoid; 104 | } 105 | 106 | /* PDF page breaks - separate title page for each section */ 107 | #print-site-page section.print-page.md-section > h1 { 108 | align-content: center; 109 | text-align: center; 110 | vertical-align: middle; 111 | padding: 5rem 0rem; 112 | font-size: 2.5em; 113 | } 114 | 115 | #print-site-page p, 116 | #print-site-page pre, 117 | #print-site-page blockquote, 118 | #print-site-page .tabbed-set { 119 | page-break-inside: avoid; 120 | } 121 | 122 | /* Avoid a page break immediately after a heading */ 123 | /* Credits https://stackoverflow.com/a/9238898/5525118 */ 124 | #print-site-page h1 { 125 | page-break-inside: avoid; 126 | } 127 | #print-site-page h1::after { 128 | content: ""; 129 | /* display: block; */ 130 | height: 100px; 131 | margin-bottom: -100px; 132 | } 133 | 134 | #print-site-page footer { display : none; } 135 | 136 | #print-site-cover-page { 137 | display: block; 138 | width:100%; 139 | text-align: center; 140 | } 141 | #print-site-cover-page h1 { 142 | font-size: 300%; 143 | } 144 | } 145 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/exclude.py: -------------------------------------------------------------------------------- 1 | """ 2 | Module to assist exclude certain files being processed by plugin. 3 | 4 | Inspired by https://github.com/apenwarr/mkdocs-exclude 5 | """ 6 | 7 | import os 8 | import fnmatch 9 | from typing import List 10 | 11 | 12 | import fnmatch 13 | import os 14 | from typing import List 15 | 16 | 17 | def exclude(path: str, exclude_patterns: List[str]) -> bool: 18 | """ 19 | Check if a path should be excluded based on a list of patterns. 20 | 21 | Args: 22 | path: The path to check 23 | exclude_patterns: List of glob patterns to exclude 24 | 25 | Returns: 26 | True if the path should be excluded, False otherwise 27 | """ 28 | assert isinstance(path, str) 29 | assert isinstance(exclude_patterns, list) 30 | 31 | if not exclude_patterns: 32 | return False 33 | 34 | # Normalize path separators to handle both Windows and Unix paths 35 | path = path.replace("\\", "/") 36 | 37 | for pattern in exclude_patterns: 38 | # Normalize pattern separators 39 | pattern = pattern.replace("\\", "/") 40 | 41 | # Check for directory patterns (ending with /) 42 | if pattern.endswith("/"): 43 | if path.startswith(pattern) or path.startswith(pattern[:-1] + "/"): 44 | return True 45 | # Regular glob pattern matching 46 | elif fnmatch.fnmatch(path, pattern): 47 | return True 48 | # Check if path is in a directory that matches the pattern 49 | elif "/" in path: 50 | path_parts = path.split("/") 51 | for i in range(1, len(path_parts)): 52 | partial_path = "/".join(path_parts[:i]) 53 | if fnmatch.fnmatch(partial_path, pattern) or partial_path == pattern: 54 | return True 55 | 56 | return False 57 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/js/print-site.js: -------------------------------------------------------------------------------- 1 | /* 2 | Javascript functions to help make the print page more PDF friendly 3 | */ 4 | 5 | /* 6 | Copy the table of contents from the sidebar's. 7 | Only called when print-site-plugin option 'add_table_of_contents' is set to true 8 | */ 9 | function generate_toc() { 10 | const sidebar = document.body.getElementsByClassName("md-sidebar--secondary")[0] ?? 11 | document.getElementById("toc-collapse"); 12 | 13 | const sidebarToc = sidebar.getElementsByTagName("ul")[0]; 14 | 15 | var clonedToc = sidebarToc.cloneNode(true); 16 | clonedToc.removeAttribute("data-md-component"); 17 | document.querySelectorAll("#print-page-toc nav")[0].insertAdjacentHTML("beforeend", clonedToc.outerHTML); 18 | } 19 | 20 | 21 | function remove_material_navigation() { 22 | // Remove left sidebar on print page 23 | remove_element_by_classname("md-sidebar--primary") 24 | // Remove tabs navigation on print page 25 | remove_element_by_classname("md-tabs") 26 | // Remove search 27 | remove_element_by_classname("md-search") 28 | 29 | } 30 | 31 | function remove_mkdocs_theme_navigation() { 32 | // Remove top navigation bar 33 | remove_element_by_classname("navbar") 34 | } 35 | 36 | 37 | function remove_element_by_classname(class_name) { 38 | var el = document.getElementsByClassName(class_name); 39 | if( el.length > 0) { 40 | el[0].style.display = "none" 41 | } 42 | } 43 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/renderer.py: -------------------------------------------------------------------------------- 1 | import logging 2 | import re 3 | from typing import List, Tuple 4 | 5 | import jinja2 6 | from mkdocs.structure.toc import AnchorLink, TableOfContents 7 | 8 | from mkdocs_print_site_plugin.exclude import exclude 9 | from mkdocs_print_site_plugin.urls import ( 10 | fix_internal_links, 11 | get_page_key, 12 | ) 13 | from mkdocs_print_site_plugin.utils import get_section_id 14 | 15 | logger = logging.getLogger("mkdocs.plugins") 16 | 17 | 18 | class Renderer(object): 19 | """ 20 | Renders the print site page. 21 | """ 22 | 23 | def __init__( 24 | self, 25 | plugin_config, 26 | mkdocs_config=None, 27 | cover_page_template_path="", 28 | banner_template_path="", 29 | print_page=None, 30 | ): 31 | """ 32 | Inits the class. 33 | """ 34 | self.plugin_config = plugin_config 35 | self.mkdocs_config = mkdocs_config or {} 36 | self.cover_page_template_path = cover_page_template_path 37 | self.banner_template_path = banner_template_path 38 | self.print_page = print_page 39 | 40 | self.items = [] 41 | 42 | def _get_items(self): 43 | return [i for i in self.items if not i == self.print_page] 44 | 45 | def write_combined(self) -> Tuple[str, TableOfContents]: 46 | """ 47 | Generates the HTML of the page that combines all page into one, while filling 48 | a table of contents. 49 | """ 50 | enabled_classes = [] 51 | 52 | # Enable options via CSS 53 | if self.plugin_config.get("add_full_urls"): 54 | enabled_classes.append("print-site-add-full-url") 55 | 56 | if self.plugin_config.get("enumerate_headings"): 57 | enabled_classes.append("print-site-enumerate-headings") 58 | 59 | if self.plugin_config.get("enumerate_figures"): 60 | enabled_classes.append("print-site-enumerate-figures") 61 | 62 | # Wrap entire print page in a div 63 | # Enables CSS to be applied only to print-site-page 64 | html = '
    ' % " ".join(enabled_classes) 65 | 66 | # Enable options via HTML injection 67 | if self.plugin_config.get("add_cover_page"): 68 | html += self._cover_page() 69 | 70 | if self.plugin_config.get("add_print_site_banner"): 71 | html += self._print_site_banner() 72 | 73 | if self.plugin_config.get("add_table_of_contents"): 74 | html += self._toc() 75 | 76 | def get_html_and_anchor_links_from_items( 77 | items: list, 78 | dir_urls: bool, 79 | excluded_pages: list, 80 | level: int = 0, 81 | prefix: str = "", 82 | heading_styles: List[str] = [], 83 | ) -> Tuple[str, List[AnchorLink]]: 84 | """ 85 | Get all the HTML and anchor links from the pages. 86 | """ 87 | items_html = "" 88 | anchor_links = [] 89 | 90 | for i, item in enumerate(items): 91 | my_prefix = f"{prefix}{i + 1}" 92 | item_id = None 93 | title = item.title 94 | if self.plugin_config.get("enumerate_headings"): 95 | title = f"{my_prefix} {title}" 96 | 97 | if item.is_page: 98 | # Do not include page in print page if excluded 99 | if exclude(item.file.src_path, excluded_pages): 100 | logging.debug(f"Excluding page '{item.file.src_path}'") 101 | continue 102 | 103 | item_id = get_page_key(item.url) 104 | anchor_links.append(AnchorLink(title, item_id, level)) 105 | heading_styles.append( 106 | f".print-site-enumerate-headings #{item_id} > h1:before {{ content: '{my_prefix} ' }}" 107 | ) 108 | 109 | # If you specify the same page twice in your navigation, it is only rendered once 110 | # so we need to check if the html attribute exists 111 | if hasattr(item, "html"): 112 | if item.html == "": 113 | logger.warning(f"[mkdocs-print-site] {item.file.src_path} is empty and will be ignored") 114 | continue 115 | 116 | item_html = item.html 117 | 118 | # Add missing h1 tag if the first heading is not a h1 119 | match = re.search(r"\{item.title}{item_html}' 123 | logger.warning( 124 | f"[mkdocs-print-site] '{item.file.src_path}' file is missing a leading h1 tag. Added to the print-page with title '{item.title}'" 125 | ) 126 | 127 | heading_styles.append(self._set_inner_heading_styles(item_id, my_prefix, level)) 128 | 129 | # Support mkdocs-material tags 130 | # See https://squidfunk.github.io/mkdocs-material/plugins/tags 131 | if hasattr(item, "meta") and item.meta.get("tags"): 132 | tags = item.meta["tags"] 133 | tags_html = "" 137 | item_html = tags_html + item_html 138 | 139 | # Update internal anchor links, image urls, etc 140 | items_html += fix_internal_links( 141 | item_html, item.url, directory_urls=dir_urls, heading_number=my_prefix 142 | ) 143 | 144 | if item.is_section: 145 | item_id = get_section_id(my_prefix) 146 | heading_styles.append( 147 | f".print-site-enumerate-headings #{item_id} > h1:before {{ content: '{my_prefix} ' }}" 148 | ) 149 | items_html += f""" 150 |
    151 |

    {item.title} 152 |

    153 | """ 154 | section_html, section_links = get_html_and_anchor_links_from_items( 155 | item.children, dir_urls, excluded_pages, level + 1, my_prefix + ".", heading_styles 156 | ) 157 | items_html += section_html 158 | section_link = AnchorLink(title, item_id, level) 159 | section_link.children = section_links 160 | anchor_links.append(section_link) 161 | 162 | items_html += "
    " 163 | 164 | return items_html, anchor_links 165 | 166 | heading_styles: List[str] = [] 167 | items_html, anchor_links = get_html_and_anchor_links_from_items( 168 | self._get_items(), 169 | dir_urls=self.mkdocs_config.get("use_directory_urls"), 170 | excluded_pages=self.plugin_config.get("exclude", []), 171 | heading_styles=heading_styles, 172 | ) 173 | 174 | html += items_html 175 | html += "
    " 176 | html += "" 177 | 178 | return html, TableOfContents(anchor_links) 179 | 180 | def _cover_page(self): 181 | """ 182 | Inserts the cover page. 183 | """ 184 | env = jinja2.Environment() 185 | env.globals = {"config": self.mkdocs_config, "page": self.print_page} 186 | 187 | with open(self.cover_page_template_path, "r", encoding="utf-8-sig", errors="strict") as f: 188 | cover_page_tpl = f.read() 189 | 190 | cover_page_html = env.from_string(cover_page_tpl).render() 191 | 192 | return ( 193 | """ 194 |
    195 | %s 196 |
    197 | """ 198 | % cover_page_html 199 | ) 200 | 201 | def _print_site_banner(self): 202 | """ 203 | Inserts the print site banner. 204 | """ 205 | env = jinja2.Environment() 206 | env.globals = {"config": self.mkdocs_config, "page": self.print_page} 207 | 208 | with open(self.banner_template_path, "r", encoding="utf-8-sig", errors="strict") as f: 209 | banner_tpl = f.read() 210 | 211 | banner_html = env.from_string(banner_tpl).render() 212 | 213 | return f""" 214 | 217 | """ 218 | 219 | def _toc(self): 220 | """ 221 | Inserts the table of contents. 222 | """ 223 | return f""" 224 |
    225 |
    226 | 229 |
    230 |
    231 | """ 232 | 233 | def _set_inner_heading_styles(self, id: str, prefix: str, level: int) -> str: 234 | """ 235 | By "inner heading" we mean that even if the heading numbers are fully determined by 236 | the nav's hierarchy, if a page has number 3.2.1, we will add a further numbering 237 | to headings such as h2 and h3 inside the page, so that the first h2 that appears is 238 | 3.2.1.1, the next one is 3.2.1.2, etc. In this case we will require that the number 239 | of items in this index be <= toc_depth, which is not the case in the ToC (as its depth 240 | is fully determined by the nav's depth). 241 | """ 242 | result = "" 243 | toc_depth = self.plugin_config.get("toc_depth") or 1 244 | # Start from h2's 245 | h_level = 2 246 | counter_names = [f"counter-{id}-{i}" for i in range(h_level, toc_depth - level + 1)] 247 | while h_level <= toc_depth - level: 248 | counters_to_reset = " ".join([f"{x} " for x in counter_names[h_level - 1 :]]) 249 | counter_reset = f" counter-reset: {counters_to_reset}; " if len(counters_to_reset) > 0 else "" 250 | counters_to_display = " '.' ".join([f"counter({x})" for x in counter_names[: h_level - 1]]) 251 | result += f""" 252 | .print-site-enumerate-headings #{id} h{h_level}:before {{ content: '{prefix}.' {counters_to_display} ' ' }} 253 | .print-site-enumerate-headings #{id} h{h_level} {{ {counter_reset} counter-increment: counter-{id}-{h_level} }} 254 | """ 255 | h_level += 1 256 | 257 | return result 258 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/templates/cover_page.tpl: -------------------------------------------------------------------------------- 1 | 2 |
    3 | 4 | {% if config.site_name %} 5 |

    {{ config.site_name }}

    6 | {% endif %} 7 | 8 |
    9 | 10 | 11 | 12 | 13 | {% if config.site_description %} 14 | 15 | 16 | 17 | 18 | {% endif %} 19 | 20 | {% if config.site_author %} 21 | 22 | 23 | 24 | 25 | {% endif %} 26 | 27 | {% if config.repo_url %} 28 | 29 | 30 | 31 | 32 | {% endif %} 33 | 34 | {% if config.copyright %} 35 | 36 | 37 | 38 | 39 | {% endif %} 40 | 41 |
    Description{{ config.site_description }}
    Author(s){{ config.site_author }}
    Repository{{ config.repo_url }}
    Copyright{{ config.copyright }}
    42 | 43 | 44 | 45 | 46 | 47 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/templates/print_site_banner.tpl: -------------------------------------------------------------------------------- 1 |

    2 | This box will disappear when printing 3 | mkdocs-print-site-plugin 4 |

    5 |

    6 | This page has combined all site pages into one. You can export to PDF using File > Print > Save as PDF. 7 |

    8 |

    9 | See also export to PDF and export to standalone HTML. 10 |

    11 | -------------------------------------------------------------------------------- /src/mkdocs_print_site_plugin/urls.py: -------------------------------------------------------------------------------- 1 | """ 2 | Deal with URLs. 3 | 4 | Some brainstorming: 5 | 6 | Links to other external pages --> Do nothing 7 | Links to other internal pages 8 | Translate: Direct links with pages to anchor links 9 | Translate: link+anchor to anchor links 10 | Links to anchors 11 | Translate: from #anchor to #page+anchor 12 | 13 | So within a page: 14 | Add a new anchor at the start of the page with a id="#pagename" 15 | id="#anchor" to id="#pagename-anchor" 16 | href="#anchor" to href="#pagename-anchor" 17 | href="a/" to href="#a" 18 | href="a/#anchor" to href="#a-anchor"` 19 | 20 | 21 | # with use_directory_urls = True 22 | [p.url for p in self.pages] 23 | ['', 'z/', 'a/'] 24 | 25 | # use_directory_urls = False 26 | [p.url for p in self.pages] 27 | ['index.html', 'z.html', 'a.html'] 28 | """ 29 | 30 | import re 31 | import os 32 | import html 33 | from os.path import splitext 34 | from urllib.parse import urlparse 35 | 36 | 37 | def is_external(url): 38 | """ 39 | Test if a url is external. 40 | """ 41 | prefixes = ("http", "www", "mailto:", "tel:", "skype:", "ftp:") 42 | return url.startswith(prefixes) 43 | 44 | 45 | def is_base64_image(url): 46 | """ 47 | Test if a url is a base64 data image. 48 | """ 49 | prefixes = "data:image" 50 | return url.startswith(prefixes) 51 | 52 | 53 | def is_attachment(url): 54 | """ 55 | If URL points to an attachment. 56 | """ 57 | path = urlparse(url).path 58 | ext = splitext(path)[1] 59 | return ext not in ["", ".html", ".md"] 60 | 61 | 62 | def get_page_key(page_url): 63 | """ 64 | Get the page key. 65 | 66 | Used to prepend a unique key to internal anchorlinks, 67 | so when we combine all pages into one, we don't get conflicting (duplicate) URLs 68 | 69 | Works the same when use_directory_urls is set to true or false in mkdocs.yml 70 | 71 | Examples 72 | get_page_key('index.html') --> 'index' 73 | get_page_key('/') --> 'index' 74 | get_page_key('abc/') --> 'abc' 75 | get_page_key('abc.html') --> 'abc' 76 | 77 | Args: 78 | page_url (str): The MkDocs url of the page 79 | """ 80 | page_key = page_url.lower().strip().rstrip("/").replace(".html", "").replace("/", "-").lstrip("-") 81 | if len(page_key) > 0: 82 | return page_key 83 | else: 84 | return "index" 85 | 86 | 87 | def fix_href_links(page_html, page_key, page_url, directory_urls=False): 88 | """ 89 | Changes internal href HTML links to (anchor) links within the print page. 90 | """ 91 | # Loop over href links (example in https://regex101.com/r/rMAHrE/520) 92 | href_regex = re.compile(r"]*?\s+)?href=\"(.*?)\"", flags=re.IGNORECASE) 93 | matches = re.finditer(href_regex, page_html) 94 | 95 | for m in matches: 96 | url = m.group(2) 97 | url = html.unescape(url) 98 | 99 | if is_external(url): 100 | continue 101 | elif is_attachment(url): 102 | url = get_url_from_root(url, page_url) 103 | if directory_urls: 104 | url = os.path.join("..", url) 105 | if os.sep != "/": 106 | # For windows compat 107 | url = url.replace(os.sep, "/") 108 | elif url.startswith("#"): 109 | # This is an anchor link within a mkdocs page 110 | url = "#" + page_key + "-" + url[1:] 111 | else: 112 | # This is a link to another mkdocs page 113 | # url 'a/#anchor-link' becomes '#a-anchor-link' 114 | # url '../Section2' with page_url '/Chapter1/Section1/ becomes '/Chapter1/Section2/' 115 | 116 | url_from_root = get_url_from_root(url, page_url) 117 | 118 | # If there is an anchor appended, fix that also 119 | url_paths = url_from_root.split("#") 120 | assert len(url_paths) <= 2 121 | page_url_1 = url_paths[0] 122 | url = "#" + get_page_key(page_url_1) 123 | if len(url_paths) == 2: 124 | url += "-" + url_paths[1] 125 | 126 | # Insert back any HTML between '", 149 | flags=re.IGNORECASE, 150 | ) 151 | matches = re.finditer(href_regex, page_html) 152 | 153 | change_tags = ["h1", "h2", "h3", "h4", "h5", "h6", "sup", "li"] 154 | for m in matches: 155 | tag_text = m.group(1) 156 | if tag_text not in change_tags: 157 | continue 158 | id_text = m.group(2) 159 | match_text = m.group() 160 | new_text = match_text.replace(id_text, page_key + "-" + id_text) 161 | 162 | page_html = page_html.replace(match_text, new_text) 163 | 164 | return page_html 165 | 166 | 167 | def fix_tabbed_content(page_html, page_key): 168 | """ 169 | Tabbed content have and