From 965e73d0270d4677bd24b0b1e0f6101cd435c4ed Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 10:14:03 +0200 Subject: [PATCH 01/25] Add publish docs to deploy gh action --- .github/workflows/pythonpublish.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pythonpublish.yml b/.github/workflows/pythonpublish.yml index 218c1bc..a7a931e 100644 --- a/.github/workflows/pythonpublish.yml +++ b/.github/workflows/pythonpublish.yml @@ -8,9 +8,9 @@ jobs: deploy: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v2 - name: Set up Python - uses: actions/setup-python@v1 + uses: actions/setup-python@v2 with: python-version: '3.x' - name: Install dependencies @@ -29,3 +29,7 @@ jobs: run: | python setup.py sdist bdist_wheel twine upload dist/* + - name: Deploy mkdocs site + run: | + mkdocs gh-deploy --force + From 4fd5a396e68d8206e8c521d7152415b4e30eea62 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 10:19:16 +0200 Subject: [PATCH 02/25] New default: will not add print site to navigation by default --- mkdocs_print_site_plugin/plugin.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index 2298750..c7da8b5 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -23,7 +23,7 @@ class PrintSitePlugin(BasePlugin): """ config_scheme = ( - ("add_to_navigation", config_options.Type(bool, default=True)), + ("add_to_navigation", config_options.Type(bool, default=False)), ("print_page_title", config_options.Type(str, default="Print Site")), ("add_table_of_contents", config_options.Type(bool, default=True)), ("toc_title", config_options.Type(str, default="Table of Contents")), From 29660f270ef6e02e67f26c9139235a974f779469 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 11:12:53 +0200 Subject: [PATCH 03/25] Remove navigation side and top bars from print page --- mkdocs.yml | 1 + mkdocs_print_site_plugin/css/print-site.css | 1 - mkdocs_print_site_plugin/js/print-site.js | 26 +++++++++++++++++++++ mkdocs_print_site_plugin/plugin.py | 3 ++- 4 files changed, 29 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 093200c..e5cf184 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ use_directory_urls: false plugins: - search - print-site: + add_to_navigation: true add_full_urls: false add_table_of_contents: true toc_title: "Table of Contents" diff --git a/mkdocs_print_site_plugin/css/print-site.css b/mkdocs_print_site_plugin/css/print-site.css index 618e841..d40a98f 100644 --- a/mkdocs_print_site_plugin/css/print-site.css +++ b/mkdocs_print_site_plugin/css/print-site.css @@ -282,7 +282,6 @@ For now, we added them for use only in the table of contents */ line-height: 1.3; color: var(--md-default-fg-color--light); } - #print-site-page h1.nav-section-title-end, #print-site-page h2.nav-section-title-end, #print-site-page h3.nav-section-title-end, diff --git a/mkdocs_print_site_plugin/js/print-site.js b/mkdocs_print_site_plugin/js/print-site.js index c0983da..92bffff 100644 --- a/mkdocs_print_site_plugin/js/print-site.js +++ b/mkdocs_print_site_plugin/js/print-site.js @@ -120,4 +120,30 @@ function generate_toc() { document.querySelectorAll("#print-page-toc nav")[0].insertAdjacentHTML("beforeend", ToC); +} + + +function remove_material_navigation() { + + // Remove left sidebar on print page + remove_element_by_classname('md-sidebar--primary') + // Remove tabs navigation on print page + remove_element_by_classname('md-tabs') + // Remove search + remove_element_by_classname('md-search') + +} + +function remove_mkdocs_theme_navigation() { + + // Remove top navigation bar + remove_element_by_classname('navbar') +} + + +function remove_element_by_classname(class_name) { + var el = document.getElementsByClassName(class_name); + if( el.length > 0) { + el[0].style.display = "none" + } } \ No newline at end of file diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index c7da8b5..ecc499c 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -240,7 +240,8 @@ def on_post_build(self, config): html = template.render(self.context) # Determine calls to required javascript functions - js_calls = "" + js_calls = "remove_material_navigation();" + js_calls += "remove_mkdocs_theme_navigation();" if self.config.get("add_table_of_contents"): js_calls += "generate_toc();" From 50011c7d1802622a79c4995cc7182d6abd7ae914 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 14:46:39 +0200 Subject: [PATCH 04/25] Add a TOC sidebar to the HTML version of print page --- mkdocs_print_site_plugin/plugin.py | 2 ++ mkdocs_print_site_plugin/renderer.py | 45 +++++++++++++++++++++++++++- 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index ecc499c..564a302 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -231,6 +231,8 @@ def on_post_build(self, config): # Combine the HTML of all pages present in the navigation self.print_page.content = self.renderer.write_combined() + # Generate a TOC sidebar for HTML version of print page + self.print_page.toc = self.renderer.get_toc_sidebar() # Get the info for MkDocs to be able to apply a theme template on our print page env = config["theme"].get_env() diff --git a/mkdocs_print_site_plugin/renderer.py b/mkdocs_print_site_plugin/renderer.py index ade3ba2..ff6eda7 100644 --- a/mkdocs_print_site_plugin/renderer.py +++ b/mkdocs_print_site_plugin/renderer.py @@ -1,7 +1,9 @@ import jinja2 import logging -from mkdocs_print_site_plugin.urls import fix_internal_links +from mkdocs.structure.toc import AnchorLink, TableOfContents + +from mkdocs_print_site_plugin.urls import fix_internal_links, get_page_key from mkdocs_print_site_plugin.exclude import exclude logger = logging.getLogger("mkdocs.plugins") @@ -159,3 +161,44 @@ def _toc(self): """ + + def get_toc_sidebar(self) -> TableOfContents: + """ + Generate a MkDocs a navigation sidebar. + + We want to generate one for the print page also, so we can export HTML. + Here we go over each page with a toc. Then we fix the anchor links. + + See also https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/toc.py + """ + toc = [] + + for item in self.items: + if hasattr(item, "toc"): + page_key = get_page_key(item.url) + item_toc = item.toc + if hasattr(item_toc, "items"): + for toc_link in item.toc.items: + toc_link = update_toc_item(page_key, toc_link) + toc += [toc_link] + + return TableOfContents(toc) + + +def update_toc_item(page_key: str, toc_link: AnchorLink) -> AnchorLink: + """ + Updates a AnchorItem to work on the print page. + """ + # update the link to point to the anchor in print page instead of actual page + toc_link.id = f"{page_key}-{toc_link.id}" + + # MkDocs-material parses the TOC and does not display level 1 + # This is a small hack that will set all levels off by 1 + # Will work just fine in base mkdocs theme also + toc_link.level = toc_link.level - 1 + + if len(toc_link.children) > 0: + for link in toc_link.children: + update_toc_item(page_key, link) + + return toc_link From 5f121e96a5edfe761232759301794fcc759cbb2e Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 14:49:52 +0200 Subject: [PATCH 05/25] New default: print site banner is not displayed by default --- docs/options.md | 7 ++++--- mkdocs_print_site_plugin/plugin.py | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/options.md b/docs/options.md index 13d86c6..eeadb6f 100644 --- a/docs/options.md +++ b/docs/options.md @@ -5,8 +5,9 @@ You can customize `mkdocs-print-site-plugin` in your `mkdocs.yml` with the follo ```yaml plugins: - print-site: - add_to_navigation: true + add_to_navigation: false print_page_title: 'Print Site' + add_print_site_banner: false # Table of contents add_table_of_contents: true toc_title: 'Table of Contents' @@ -23,7 +24,7 @@ plugins: ``` `add_to_navigation` -: Default is `true`. 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`). +: 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`). `print_page_title` : 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`. @@ -57,7 +58,7 @@ plugins: : Default `""`. The path to a custom cover page template to use. See [Customizing the Cover Page](customization/cover_page.md) for more info. `add_print_site_banner` -: Default `true`. When enabled, a banner is added to the top of the print page, explaining to users the current page contains all site pages. +: Default `false`. When enabled, a banner is added to the top of the HTML print page, explaining to users the current page contains all site pages. `print_site_banner_template` : Default `""`. The path to a custom print site banner template to use. See [Customizing the print site banner](customization/banner.md) for more info. diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index 564a302..77b4671 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -33,7 +33,7 @@ class PrintSitePlugin(BasePlugin): ("enumerate_figures", config_options.Type(bool, default=False)), ("add_cover_page", config_options.Type(bool, default=False)), ("cover_page_template", config_options.Type(str, default="")), - ("add_print_site_banner", config_options.Type(bool, default=True)), + ("add_print_site_banner", config_options.Type(bool, default=False)), ("print_site_banner_template", config_options.Type(str, default="")), ("path_to_pdf", config_options.Type(str, default="")), ("enabled", config_options.Type(bool, default=True)), From 4e3a2351ab9f40b26f7f1d9dc8e88c07165a2096 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 14:55:43 +0200 Subject: [PATCH 06/25] Fix bug where setting 'add_print_site_banner' to false would lead to a 'No such file found' error --- mkdocs_print_site_plugin/renderer.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/mkdocs_print_site_plugin/renderer.py b/mkdocs_print_site_plugin/renderer.py index ff6eda7..0f8467b 100644 --- a/mkdocs_print_site_plugin/renderer.py +++ b/mkdocs_print_site_plugin/renderer.py @@ -20,7 +20,6 @@ def __init__( mkdocs_config={}, cover_page_template_path="", banner_template_path="", - insert_print_site_banner=True, print_page=None, ): """ @@ -30,7 +29,6 @@ def __init__( self.mkdocs_config = mkdocs_config self.cover_page_template_path = cover_page_template_path self.banner_template_path = banner_template_path - self.insert_print_site_banner = insert_print_site_banner self.print_page = print_page self.items = [] @@ -59,7 +57,7 @@ def write_combined(self): if self.plugin_config.get("add_cover_page"): html += self._cover_page() - if self.insert_print_site_banner: + if self.plugin_config.get("add_print_site_banner"): html += self._print_site_banner() if self.plugin_config.get("add_table_of_contents"): From eb2fdc26da57853f7b1854824233da2895959127 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 14:56:29 +0200 Subject: [PATCH 07/25] New default: toc_depth is now set to 3 instead of 6 --- docs/options.md | 2 +- mkdocs_print_site_plugin/plugin.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/options.md b/docs/options.md index eeadb6f..7e6118a 100644 --- a/docs/options.md +++ b/docs/options.md @@ -36,7 +36,7 @@ plugins: : Default is `'Table of Contents'`. When `add_table_of_contents` is set to `true` this setting controls the name of the table of contents. This setting is ignored when `add_table_of_contents` is set to `false`. `toc_depth` -: Default is `6`. When `add_table_of_contents` is set to `true` this setting controls the depth of the table of contents. This setting is ignored when `add_table_of_contents` is set to `false`. +: Default is `3`. When `add_table_of_contents` is set to `true` this setting controls the depth of the table of contents. This setting is ignored when `add_table_of_contents` is set to `false`. `add_full_urls` : 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. diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index 77b4671..d9105aa 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -27,7 +27,7 @@ class PrintSitePlugin(BasePlugin): ("print_page_title", config_options.Type(str, default="Print Site")), ("add_table_of_contents", config_options.Type(bool, default=True)), ("toc_title", config_options.Type(str, default="Table of Contents")), - ("toc_depth", config_options.Type(int, default=6)), + ("toc_depth", config_options.Type(int, default=3)), ("add_full_urls", config_options.Type(bool, default=False)), ("enumerate_headings", config_options.Type(bool, default=False)), ("enumerate_figures", config_options.Type(bool, default=False)), From d4d4fe3d2c83a08e53038bf9cddcbc7a26b5af4f Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 15:18:19 +0200 Subject: [PATCH 08/25] Make sure sidebar toc on print page HTML also respects TOC depth parameter --- mkdocs_print_site_plugin/renderer.py | 17 +++++++++++++++++ .../projects/basic/mkdocs_toc_depth.yml | 6 ++++++ 2 files changed, 23 insertions(+) create mode 100644 tests/fixtures/projects/basic/mkdocs_toc_depth.yml diff --git a/mkdocs_print_site_plugin/renderer.py b/mkdocs_print_site_plugin/renderer.py index 0f8467b..1ca3442 100644 --- a/mkdocs_print_site_plugin/renderer.py +++ b/mkdocs_print_site_plugin/renderer.py @@ -180,9 +180,26 @@ def get_toc_sidebar(self) -> TableOfContents: toc_link = update_toc_item(page_key, toc_link) toc += [toc_link] + # Make sure the sidebar ToC also respects + # the plugin's toc_depth parameter + toc = clear_children_up_to(self.plugin_config.get("toc_depth"), toc) + return TableOfContents(toc) +def clear_children_up_to(depth, items): + """ + Filters items in sidebar table of contents to a given depth. + """ + for toc_item in items: + # note the -1 is there because of the hack on levels in update_toc_item() + if toc_item.level == depth - 1: + toc_item.children = [] + else: + toc_item.children = clear_children_up_to(depth, toc_item.children) + return items + + def update_toc_item(page_key: str, toc_link: AnchorLink) -> AnchorLink: """ Updates a AnchorItem to work on the print page. diff --git a/tests/fixtures/projects/basic/mkdocs_toc_depth.yml b/tests/fixtures/projects/basic/mkdocs_toc_depth.yml new file mode 100644 index 0000000..4ef8f8b --- /dev/null +++ b/tests/fixtures/projects/basic/mkdocs_toc_depth.yml @@ -0,0 +1,6 @@ +site_name: Test + +plugins: + - print-site: + toc_depth: 1 + \ No newline at end of file From 436fbad0d57dd27f3c085f548b722772aa0b3027 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 15:31:49 +0200 Subject: [PATCH 09/25] The table of contents (when enabled) will now only be displayed in the print version --- docs/options.md | 2 +- mkdocs_print_site_plugin/css/print-site.css | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/options.md b/docs/options.md index 7e6118a..6b9bbe0 100644 --- a/docs/options.md +++ b/docs/options.md @@ -30,7 +30,7 @@ plugins: : 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`. `add_table_of_contents` -: Default is `true`. Adds a table of contents section at the beginning of the print page. +: Default is `true`. Adds a table of contents section at the beginning of the print page (in print version, not HTML version). `toc_title` : Default is `'Table of Contents'`. When `add_table_of_contents` is set to `true` this setting controls the name of the table of contents. This setting is ignored when `add_table_of_contents` is set to `false`. diff --git a/mkdocs_print_site_plugin/css/print-site.css b/mkdocs_print_site_plugin/css/print-site.css index d40a98f..e7515e7 100644 --- a/mkdocs_print_site_plugin/css/print-site.css +++ b/mkdocs_print_site_plugin/css/print-site.css @@ -196,6 +196,10 @@ div.print-site-add-full-url section.print-page a[href^="http"]::after{ /* Print site table of contents styling */ +/* Don't display the table of contents in HTML version */ +#print-page-toc { display: none } + + .print-page-toc-nav { padding-bottom: 2em; } @@ -321,6 +325,10 @@ For now, we added them for use only in the table of contents */ /* Remove print site banner */ #print-site-banner { display: none; } + /* display the table of contents in print version */ + #print-page-toc { display: block } + + /* Ensure all tabbed content is displayed and printed https://squidfunk.github.io/mkdocs-material/reference/content-tabs/ */ /* #print-site-page div.tabbed-content { display: block !important; } */ From b49b29b5508a09be12f019361eea57b4d361210e Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 16:30:28 +0200 Subject: [PATCH 10/25] Improve default cover page template --- .../templates/cover_page.tpl | 46 +++++++++++++------ 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/mkdocs_print_site_plugin/templates/cover_page.tpl b/mkdocs_print_site_plugin/templates/cover_page.tpl index 0907d2f..64f7bd8 100644 --- a/mkdocs_print_site_plugin/templates/cover_page.tpl +++ b/mkdocs_print_site_plugin/templates/cover_page.tpl @@ -1,28 +1,46 @@ -
+
{% if config.site_name %}

{{ config.site_name }}

{% endif %} - {% if config.site_description %} -

{{ config.site_description }}

- {% endif %} -
-{% if config.site_author %} -

Authors: {{ config.site_author }}

-{% endif %} -

- {% if config.site_url %} - Website: {{ config.site_url }}
+ + + {% if config.site_description %} + + + + + {% endif %} + + {% if config.site_author %} + + + + {% endif %} + {% if config.repo_url %} - Repo: {{ config.repo_url }}
+ + + + {% endif %} + {% if config.copyright %} - {{ config.copyright }}
+ + + + {% endif %} -

+ +
Description{{ config.site_description }}
Author(s){{ config.site_author }}
Repository{{ config.repo_url }}
Copyright{{ config.copyright }}
+ + + + + From 967d6837562395b3491f3ffa4483ca8f3ed02190 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 16:36:58 +0200 Subject: [PATCH 11/25] Cover page is now displayed also on HTML page --- mkdocs.yml | 2 +- mkdocs_print_site_plugin/css/print-site.css | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index e5cf184..5948b19 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: mkdocs-print-site-plugin Docs +site_name: Documentation mkdocs-print-site-plugin 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. diff --git a/mkdocs_print_site_plugin/css/print-site.css b/mkdocs_print_site_plugin/css/print-site.css index e7515e7..08e1f82 100644 --- a/mkdocs_print_site_plugin/css/print-site.css +++ b/mkdocs_print_site_plugin/css/print-site.css @@ -267,8 +267,6 @@ ul.print-site-toc-level-2 li a { -/* Don't display cover page when not in print mode */ -#print-site-cover-page { display: none; } /* Don't display the section headings that we added For now, we added them for use only in the table of contents */ From 06e64ecdd290e43ca97b8c4a8419f88bc8eee456 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 19:34:00 +0200 Subject: [PATCH 12/25] Prettier highlight of anchor when clicking link --- mkdocs_print_site_plugin/css/print-site.css | 35 ++++++++++++--------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/mkdocs_print_site_plugin/css/print-site.css b/mkdocs_print_site_plugin/css/print-site.css index 08e1f82..c34c5ce 100644 --- a/mkdocs_print_site_plugin/css/print-site.css +++ b/mkdocs_print_site_plugin/css/print-site.css @@ -193,6 +193,27 @@ div.print-site-add-full-url section.print-page a[href^="http"]::after{ } +/* Do some nice animations when clicking on a ToC link */ +#print-site-page h1:target, +#print-site-page h2:target, +#print-site-page h3:target, +#print-site-page h4:target, +#print-site-page h5:target, +#print-site-page h6:target { + animation: highlight 1.5s ease; +} +@keyframes highlight { + from { color: orange; } + to { color: none; } +} +/* Make sure to offset for the header when using anchor links */ +/* #print-site-page .headerlink::before { + content: ''; + display: block; + height: 180px; + margin-top: -180px; +} */ + /* Print site table of contents styling */ @@ -204,19 +225,6 @@ Print site table of contents styling padding-bottom: 2em; } -#print-site-page h1:target, -#print-site-page h2:target, -#print-site-page h3:target, -#print-site-page h4:target, -#print-site-page h5:target, -#print-site-page h6:target { - animation: highlight 1s ease; -} -@keyframes highlight { - from { background: yellow; } - to { background: white; } -} - #print-page-toc ul { /* margin-left: 1.6em; */ margin-top: 0; @@ -372,7 +380,6 @@ For now, we added them for use only in the table of contents */ #print-site-page footer { display : none; } - #print-site-cover-page { display: block; From 403a25b81974569269ed6ec9ab38eafb6afee73c Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 19:38:00 +0200 Subject: [PATCH 13/25] Bump mkdocs-material requirement to 7.2.6 --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 99975d9..d1cf4c3 100644 --- a/setup.py +++ b/setup.py @@ -32,7 +32,7 @@ "Topic :: Documentation", "Topic :: Text Processing", ], - install_requires=["mkdocs-material>=7.1.5"], + install_requires=["mkdocs-material>=7.2.6"], packages=find_packages(), entry_points={"mkdocs.plugins": ["print-site = mkdocs_print_site_plugin.plugin:PrintSitePlugin"]}, ) From c8fad648baeea87996a8ccb15509124bc72e67bb Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Mon, 13 Sep 2021 20:15:20 +0200 Subject: [PATCH 14/25] Fix bug where clicking on an anchor link would jump to a place where the header was hidden under the navbar (in mkdocs-material) Note new situation is still buggy, causing a newline after enumeration somehow --- .../css/print-site-material.css | 5 ---- mkdocs_print_site_plugin/css/print-site.css | 28 ++++--------------- .../projects/basic/mkdocs_with_enum.yml | 6 ++++ 3 files changed, 12 insertions(+), 27 deletions(-) create mode 100644 tests/fixtures/projects/basic/mkdocs_with_enum.yml diff --git a/mkdocs_print_site_plugin/css/print-site-material.css b/mkdocs_print_site_plugin/css/print-site-material.css index 4e812a1..159fbcf 100644 --- a/mkdocs_print_site_plugin/css/print-site-material.css +++ b/mkdocs_print_site_plugin/css/print-site-material.css @@ -3,11 +3,6 @@ https://github.com/squidfunk/mkdocs-material */ /* Table of Contents styling */ -.print-page-toc-title { - padding-bottom: 0em; - margin-bottom: 0; -} - #print-site-page ul.toc-section-line-border { border-left: 5px solid var(--md-default-fg-color--lightest); } diff --git a/mkdocs_print_site_plugin/css/print-site.css b/mkdocs_print_site_plugin/css/print-site.css index c34c5ce..1770ff8 100644 --- a/mkdocs_print_site_plugin/css/print-site.css +++ b/mkdocs_print_site_plugin/css/print-site.css @@ -23,16 +23,6 @@ print-site: - print-site-enumerate_headings: true */ -/* Ensure that when adding enumeration to headings, this happens inline */ -.print-site-enumerate-headings h1:before, -.print-site-enumerate-headings h2:before, -.print-site-enumerate-headings h3:before, -.print-site-enumerate-headings h4:before, -.print-site-enumerate-headings h5:before, -.print-site-enumerate-headings h6:before { - display: inline !important; -} - /* Reset all enumeration at start of page */ body {counter-reset: chapter sec-top toc-chapter toc-sec-chapter figurecounter;} @@ -75,7 +65,7 @@ that are part of an original included page */ } .print-site-enumerate-headings .print-page h6:before { counter-increment: last; - content: counter(chapter) "." counter(section) "." counter(sub-section) "." counter(composite) "." counter(detail) "." counter(last) !important; + content: counter(chapter) "." counter(section) "." counter(sub-section) "." counter(composite) "." counter(detail) "." counter(last) " " !important; } /* Enumerate headings of SECTIONS, @@ -107,7 +97,7 @@ that are part of an original included page */ } .print-site-enumerate-headings h6.nav-section-title:before { counter-increment: sec-last; - content: counter(sec-top, upper-roman) "." counter(sec-section, upper-roman) "." counter(sec-sub-section, upper-roman) "." counter(sec-composite, upper-roman) "." counter(sec-detail, upper-roman) "." counter(sec-last, upper-roman) !important; + content: counter(sec-top, upper-roman) "." counter(sec-section, upper-roman) "." counter(sec-sub-section, upper-roman) "." counter(sec-composite, upper-roman) "." counter(sec-detail, upper-roman) "." counter(sec-last, upper-roman) " " !important; } @@ -139,7 +129,7 @@ that are part of an original included page */ } .print-site-enumerate-headings .print-site-toc-level-6 > li a:before { counter-increment: toc-last; - content: counter(toc-chapter) "." counter(toc-section) "." counter(toc-sub-section) "." counter(toc-composite) "." counter(toc-detail) "." counter(toc-last); + content: counter(toc-chapter) "." counter(toc-section) "." counter(toc-sub-section) "." counter(toc-composite) "." counter(toc-detail) "." counter(toc-last) " "; } /* Enumerate SECTIONS in table of contents also */ @@ -170,7 +160,7 @@ that are part of an original included page */ } .print-site-enumerate-headings li.toc-nav-section-title-level-6:before { counter-increment: toc-sec-last; - content: counter(toc-sec-chapter, upper-roman) "." counter(toc-sec-section, upper-roman) "." counter(toc-sec-sub-section, upper-roman) "." counter(toc-sec-composite, upper-roman) "." counter(toc-sec-detail, upper-roman) "." counter(toc-last, upper-roman); + content: counter(toc-sec-chapter, upper-roman) "." counter(toc-sec-section, upper-roman) "." counter(toc-sec-sub-section, upper-roman) "." counter(toc-sec-composite, upper-roman) "." counter(toc-sec-detail, upper-roman) "." counter(toc-last, upper-roman) " "; } #print-page-toc li a.headerlink:before { @@ -205,14 +195,8 @@ div.print-site-add-full-url section.print-page a[href^="http"]::after{ @keyframes highlight { from { color: orange; } to { color: none; } -} -/* Make sure to offset for the header when using anchor links */ -/* #print-site-page .headerlink::before { - content: ''; - display: block; - height: 180px; - margin-top: -180px; -} */ +} + /* Print site table of contents styling diff --git a/tests/fixtures/projects/basic/mkdocs_with_enum.yml b/tests/fixtures/projects/basic/mkdocs_with_enum.yml new file mode 100644 index 0000000..4f9c289 --- /dev/null +++ b/tests/fixtures/projects/basic/mkdocs_with_enum.yml @@ -0,0 +1,6 @@ +site_name: Test + +plugins: + - print-site: + enumerate_headings: true + \ No newline at end of file From 9f204b89765bdb1f396ffdace26430874243c2bd Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Tue, 14 Sep 2021 10:30:19 +0200 Subject: [PATCH 15/25] New defaults: enumerate_headings and enumerate_figures set to true --- docs/options.md | 4 ++-- mkdocs_print_site_plugin/plugin.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/options.md b/docs/options.md index 6b9bbe0..8ba58c1 100644 --- a/docs/options.md +++ b/docs/options.md @@ -44,12 +44,12 @@ plugins: For example "[google.com](https://www.google.com)" will be replaced by "[google.com](https://www.google.com) (https://www.google.com)" `enumerate_headings` -: Default `false`. This will add numbering (enumeration) to all headings 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). +: Default `true`. This will add numbering (enumeration) to all headings 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). Example "1.2 A chapter subsection". `enumerate_figures` -: Default `false`. 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). +: 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). `add_cover_page` : Default `false`. When enabled, a cover page is added to the print page, displaying the `site_title` and other information from the `mkdocs.yml` file. See also [Customizing the cover page](customization/cover_page.md) diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index d9105aa..ca5df60 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -29,8 +29,8 @@ class PrintSitePlugin(BasePlugin): ("toc_title", config_options.Type(str, default="Table of Contents")), ("toc_depth", config_options.Type(int, default=3)), ("add_full_urls", config_options.Type(bool, default=False)), - ("enumerate_headings", config_options.Type(bool, default=False)), - ("enumerate_figures", config_options.Type(bool, default=False)), + ("enumerate_headings", config_options.Type(bool, default=True)), + ("enumerate_figures", config_options.Type(bool, default=True)), ("add_cover_page", config_options.Type(bool, default=False)), ("cover_page_template", config_options.Type(str, default="")), ("add_print_site_banner", config_options.Type(bool, default=False)), From 071ee7e2d5809ac225a014685ee5906e9e6f1757 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Tue, 14 Sep 2021 15:57:11 +0200 Subject: [PATCH 16/25] Fix bug in tab content not displaying on print page, closes #53 --- mkdocs_print_site_plugin/urls.py | 40 +++++++++++--------------------- 1 file changed, 13 insertions(+), 27 deletions(-) diff --git a/mkdocs_print_site_plugin/urls.py b/mkdocs_print_site_plugin/urls.py index c077696..29f8b81 100644 --- a/mkdocs_print_site_plugin/urls.py +++ b/mkdocs_print_site_plugin/urls.py @@ -167,36 +167,22 @@ def fix_tabbed_content(page_html, page_key): - we should change id, and

+ ${title} / +
`; + + footerHtml = ` `; + + + (async() => { + const browser = await puppeteer.launch({ + headless: true, + executablePath: process.env.CHROME_BIN || null, + args: ['--no-sandbox', '--headless', '--disable-gpu', '--disable-dev-shm-usage'] + }); + + const page = await browser.newPage(); + await page.goto(url, { waitUntil: 'networkidle2' }); + await page.pdf({ + path: pdfPath, // path to save pdf file + format: 'A4', // page format + displayHeaderFooter: true, // display header and footer (in this example, required!) + printBackground: true, // print background + landscape: false, // use horizontal page layout + headerTemplate: headerHtml, // indicate html template for header + footerTemplate: footerHtml, + scale: 1, //Scale amount must be between 0.1 and 2 + margin: { // increase margins (in this example, required!) + top: 80, + bottom: 80, + left: 30, + right: 30 + } + }); + + await browser.close(); + })(); + ``` \ No newline at end of file diff --git a/docs/customization/pdf_button.md b/docs/how-to/pdf_button.md similarity index 100% rename from docs/customization/pdf_button.md rename to docs/how-to/pdf_button.md diff --git a/docs/customization/print_button.md b/docs/how-to/print_button.md similarity index 100% rename from docs/customization/print_button.md rename to docs/how-to/print_button.md diff --git a/docs/index.md b/docs/index.md index 4decddc..9c35dda 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,3 +29,9 @@ plugins: > :warning: Make sure to put `print-site` to the **bottom** of the plugin list. This is because other plugins might alter your site (like the navigation), and you want these changes included in the print page. > If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set. + +## Usage + +- Navigate to `/print_page/` or `print_page.html` +- Export to standalone HTML (see [export to HTML](how-to/export-HTML.html)) +- Export to PDF using your browser using *File > Print > Save as PDF* (see [export to PDF](how-to/export-PDF.html)) diff --git a/docs/options.md b/docs/options.md index 8ba58c1..e9c0d3f 100644 --- a/docs/options.md +++ b/docs/options.md @@ -52,19 +52,19 @@ plugins: : 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). `add_cover_page` -: Default `false`. When enabled, a cover page is added to the print page, displaying the `site_title` and other information from the `mkdocs.yml` file. See also [Customizing the cover page](customization/cover_page.md) +: Default `false`. When enabled, a cover page is added to the print page, displaying the `site_title` and other information from the `mkdocs.yml` file. See also [Customizing the cover page](how-to/cover_page.md) `cover_page_template` -: Default `""`. The path to a custom cover page template to use. See [Customizing the Cover Page](customization/cover_page.md) for more info. +: Default `""`. The path to a custom cover page template to use. See [Customizing the Cover Page](how-to/cover_page.md) for more info. `add_print_site_banner` : Default `false`. When enabled, a banner is added to the top of the HTML print page, explaining to users the current page contains all site pages. `print_site_banner_template` -: Default `""`. The path to a custom print site banner template to use. See [Customizing the print site banner](customization/banner.md) for more info. +: Default `""`. The path to a custom print site banner template to use. See [Customizing the print site banner](how-to/banner.md) for more info. `path_to_pdf` -: Default is empty. Option to make it easier to add a link to the PDF version of the site on each page. See [Adding a PDF button](customization/pdf_button.md) for more info. +: Default is empty. Option to make it easier to add a link to the PDF version of the site on each page. See [Adding a PDF button](how-to/pdf_button.md) for more info. `enabled` : Default is `true`. Enables you to deactivate this plugin. A possible use case is local development where you might want faster build times. It's recommended to use this option with an environment variable together with a default fallback (introduced in `mkdocs` v1.2.1, see [docs](https://www.mkdocs.org/user-guide/configuration/#environment-variables)). Example: @@ -84,4 +84,4 @@ plugins: ``` `exclude` -: Default is empty. Allows to specify a list of page source paths that should not be included in the print page. See [Do Not Print](customization/do_not_print.md#ignoring-an-entire-page) for more info. \ No newline at end of file +: Default is empty. Allows to specify a list of page source paths that should not be included in the print page. See [Do Not Print](how-to/do_not_print.md#ignoring-an-entire-page) for more info. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index a48e91b..104903d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,17 +24,23 @@ plugins: nav: - Home: index.md - Options: options.md - - Customization: - - customization/print_button.md - - customization/pdf_button.md - - customization/cover_page.md - - customization/do_not_print.md + - How to guides: + - Export to PDF: how-to/export-PDF.md + - Export to HTML: how-to/export-HTML.md + - Add a print button: how-to/print_button.md + - Add a PDF button: how-to/pdf_button.md + - Add a cover page: how-to/cover_page.md + - Add a banner: how-to/banner.md + - Exclude content: how-to/do_not_print.md - Demo Content: demo_content.md - Contributing: contributing.md theme: name: material custom_dir: docs/overrides + icon: + admonition: + example: fontawesome/solid/flask palette: - media: "(prefers-color-scheme: light)" scheme: default diff --git a/setup.py b/setup.py index d1cf4c3..c47164f 100644 --- a/setup.py +++ b/setup.py @@ -10,7 +10,7 @@ setup( name="mkdocs-print-site-plugin", version="1.3.0", - description="MkDocs plugin that adds a page with all site pages, enabling printing to PDF for users.", + description="MkDocs plugin that combines all pages into one, allowing for easy export to PDF and standalone HTML.", long_description=long_description, long_description_content_type="text/markdown", keywords="mkdocs plugin print pdf", diff --git a/standalone.html b/standalone.html new file mode 100644 index 0000000..f169da1 --- /dev/null +++ b/standalone.html @@ -0,0 +1,1227 @@ + + + + + + + + + + +Print Site - Documentation mkdocs-print-site-plugin + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
+
+
+
+
+ +
+
+
+
+
+
+ +
+
+
+
+
+
+
+
+

Documentation mkdocs-print-site-plugin

+
+ + + + + + + + + + + + + + + + + +
DescriptionMkDocs Plugin allowing your site visitors to *File > Print > Save as PDF* the entire site.
Author(s)Tim Vink
Repositoryhttps://github.com/timvink/mkdocs-print-site-plugin/
CopyrightCopyright © 2020 Maintained by Tim Vink.
+
+
+
+ +
+
+

Actions Status +PyPI - Python Version +PyPI +PyPI - Downloads +codecov +GitHub contributors +PyPI - License

+

mkdocs-print-site-plugin↵

+

MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to File > Print > Save as PDF the entire site.

+

Installation↵

+

Install the plugin using pip3:

+
pip3 install mkdocs-print-site-plugin
+
+

Next, add the following lines to your mkdocs.yml:

+
plugins:
+  - search
+  - print-site
+
+
+

⚠ Make sure to put print-site to the bottom of the plugin list. This is because other plugins might alter your site (like the navigation), and you want these changes included in the print page.

+

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

+
+

Usage↵

+
    +
  • Navigate to /print_page/ or print_page.html
    • +
  • Export to standalone HTML
    • +
  • Export to PDF using your browser using File > Print > Save as PDF
    • +

Options↵

+

You can customize mkdocs-print-site-plugin in your mkdocs.yml with the following settings:

+
plugins:
+  - print-site:
+      add_to_navigation: false
+      print_page_title: 'Print Site'
+      add_print_site_banner: false
+      # Table of contents
+      add_table_of_contents: true
+      toc_title: 'Table of Contents'
+      toc_depth: 6
+      # Content-related
+      add_full_urls: false
+      enumerate_headings: true
+      enumerate_figures: true
+      add_cover_page: true
+      cover_page_template: ""
+      path_to_pdf: ""
+      enabled: true
+      exclude:
+
+
+
add_to_navigation
+
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).
+
print_page_title
+
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.
+
add_table_of_contents
+
Default is true. Adds a table of contents section at the beginning of the print page (in print version, not HTML version).
+
toc_title
+
Default is 'Table of Contents'. When add_table_of_contents is set to true this setting controls the name of the table of contents. This setting is ignored when add_table_of_contents is set to false.
+
toc_depth
+
Default is 3. When add_table_of_contents is set to true this setting controls the depth of the table of contents. This setting is ignored when add_table_of_contents is set to false.
+
add_full_urls
+
+

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.

+

For example "google.com" will be replaced by "google.com (https://www.google.com)"

+
+
enumerate_headings
+
+

Default true. This will add numbering (enumeration) to all headings 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.

+

Example "1.2 A chapter subsection".

+
+
enumerate_figures
+
Default true. This will add numbering to all figure captions (for example "Figure 1: "). Works especially well with mkdocs-img2fig-plugin.
+
add_cover_page
+
Default false. When enabled, a cover page is added to the print page, displaying the site_title and other information from the mkdocs.yml file. See also Customizing the cover page
+
cover_page_template
+
Default "". The path to a custom cover page template to use. See Customizing the Cover Page for more info.
+
add_print_site_banner
+
Default false. When enabled, a banner is added to the top of the HTML print page, explaining to users the current page contains all site pages.
+
print_site_banner_template
+
Default "". The path to a custom print site banner template to use. See Customizing the print site banner for more info.
+
path_to_pdf
+
Default is empty. Option to make it easier to add a link to the PDF version of the site on each page. See Adding a PDF button for more info.
+
enabled
+
+

Default is true. Enables you to deactivate this plugin. A possible use case is local development where you might want faster build times. It's recommended to use this option with an environment variable together with a default fallback (introduced in mkdocs v1.2.1, see docs). Example:

+
# mkdocs.yml
+plugins:
+    - print-site:
+        enabled: !ENV [ENABLED_PRINT_SITE, True]
+
+

Which enables you do disable the plugin locally using:

+
export ENABLED_PRINT_SITE=false
+mkdocs serve
+
+
+
exclude
+
Default is empty. Allows to specify a list of page source paths that should not be included in the print page. See Do Not Print for more info.
+

How to guides

Export to PDF↵

+

After enabling the print-site plugin in your mkdocs.yml, exporting to PDF is as simple as browsing to /print_page or /print_page.html (url depends on your mkdocs setting use_directory_urls). From your browser you can use File > Print > Save as PDF.

+

Automating exports↵

+

If you want to automatically create PDFs of your mkdocs website, you can automate the process using a headless chrome plugin.

+
npm i --save puppeteer
+
+

node

+
// Requires: npm i --save puppeteer
+
+const puppeteer = require('puppeteer');
+var args = process.argv.slice(2);
+var url = args[0];
+var pdfPath = args[1];
+var title = args[2];
+
+console.log('Saving', url, 'to', pdfPath);
+
+// date –  formatted print date
+// title – document title
+// url  – document location
+// pageNumber – current page number
+// totalPages – total pages in the document
+headerHtml = `
+<div style="font-size: 10px; padding-right: 1em; text-align: right; width: 100%;">
+    <span>${title}</span>  <span class="pageNumber"></span> / <span class="totalPages"></span>
+</div>`;
+
+footerHtml = ` `;
+
+
+(async() => {
+    const browser = await puppeteer.launch({
+        headless: true,
+        executablePath: process.env.CHROME_BIN || null,
+        args: ['--no-sandbox', '--headless', '--disable-gpu', '--disable-dev-shm-usage']
+    });
+
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: 'networkidle2' });
+    await page.pdf({
+        path: pdfPath, // path to save pdf file
+        format: 'A4', // page format
+        displayHeaderFooter: true, // display header and footer (in this example, required!)
+        printBackground: true, // print background
+        landscape: false, // use horizontal page layout
+        headerTemplate: headerHtml, // indicate html template for header
+        footerTemplate: footerHtml,
+        scale: 1, //Scale amount must be between 0.1 and 2
+        margin: { // increase margins (in this example, required!)
+            top: 80,
+            bottom: 80,
+            left: 30,
+            right: 30
+        }
+    });
+
+    await browser.close();
+})();
+

Adding a print button↵

+

You might want to customize your site to include a 'print' button on every page (like the one in the right corner of this page 👆)

+

MkDocs supports theme extension, an easy way to override parts of a theme. +You can use page.url_to_print_page to get the link to the site print page.

+

Adding a print button to mkdocs-material theme↵

+

In mkdocs-material theme (see customization), you can create a file for overrides and point to it your mkdocs.yml. You might also want to disable adding the print page to the navigation when you already have a button with the link.

+

Example:

+
+
theme:
+name: material
+custom_dir: docs/overrides
+
+plugin:
+    - print-site:
+        - add_to_navigation: false
+
+
+
+
{% extends "base.html" %}
+
+{% block content %}
+
+{% if page.url_to_print_page %}
+    <a href="{{ page.url_to_print_page }}" title="Print Site" class="md-content__button md-icon">
+        {% include ".icons/material/printer.svg" %}
+    </a>
+{% endif %}
+
+{{ super() }}
+{% endblock content %}
+
+
+
+

Adding a print button to mkdocs theme↵

+

You can also customize the base mkdocs theme, by creating a file for overrides and pointing to it your mkdocs.yml. You might also want to disable adding the print page to the navigation when you already have a button with the link.

+

Example:

+
+
theme:
+    name: mkdocs
+    custom_dir: docs/overrides
+
+plugin:
+    - print-site:
+        - add_to_navigation: false
+
+
+
+
{% extends "base.html" %}
+
+{% block repo %}
+    {% if page.url_to_print_page %}
+        <li class="nav-item">
+            <a href="{{ page.url_to_print_page }}" title="Print Site" class="nav-link">
+                <i class="fa fa-print"></i> Print
+            </a>
+        </li>
+    {% endif %}
+
+{{ super() }}
+{% endblock repo %}
+
+
+

Adding a PDF button↵

+

You might want to make downloading a PDF even easier for your users. You could include a 'PDF' button on every page (like the one in the right corner of this page 👆)

+

MkDocs supports theme extension, an easy way to override parts of a theme. +You can use page.url_to_pdf to get the link to site PDF from a page.

+
+

Info

+

While it might be easier for your users, using this option means you need to manually create the PDF everytime you make a change to your website.

+

If you use this option and you are using version control like git, you might want to also gitignore the PDF file.

+
+

Adding a PDF button to mkdocs-material theme↵

+

In mkdocs-material theme (see customization), you can create a file for overrides and point to it your mkdocs.yml. You might also want to disable adding the print page to the navigation when you already have a button with the link.

+

Example:

+
+
theme:
+name: material
+custom_dir: docs/overrides
+
+plugin:
+    - print-site:
+        - path_to_pdf: "assets/the_name_of_your_file.pdf"
+        - add_to_navigation: false
+
+
+
+
{% extends "base.html" %}
+
+{% block content %}
+
+{% if page.url_to_pdf %}
+    <a href="{{ page.url_to_pdf }}" title="Site PDF" class="md-content__button md-icon">
+        {% include ".icons/material/pdf-box.svg" %}
+    </a>
+{% endif %}
+
+{{ super() }}
+{% endblock content %}
+
+
+
+

Adding a print button to mkdocs theme↵

+

You can also customize the base mkdocs theme, by creating a file for overrides and pointing to it your mkdocs.yml. You might also want to disable adding the print page to the navigation when you already have a button with the link.

+

Example:

+
+
theme:
+    name: mkdocs
+    custom_dir: docs/overrides
+
+plugin:
+    - print-site:
+        - path_to_pdf: "assets/the_name_of_your_file.pdf"
+        - add_to_navigation: false
+
+
+
+
{% extends "base.html" %}
+
+{% block repo %}
+    {% if page.url_to_pdf %}
+        <li class="nav-item">
+            <a href="{{ page.url_to_pdf }}" title="Site PDF" class="nav-link">
+                <i class="fas fa-file-pdf"></i> PDF
+            </a>
+        </li>
+    {% endif %}
+
+{{ super() }}
+{% endblock repo %}
+
+
+

Customize the cover page↵

+

When the add_cover_page option is set to true, mkdocs-print-site-plugin will generate a cover page when printing. This cover page is quite basic, and you might want to customize it.

+

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 where you can combine HTML and jinja2 variables such as the information specified in mkdocs.yml (see mkdocs project information).

+

Example:

+
+
plugins:
+    - print-site:
+        add_cover_page: true
+        cover_page_template: "docs/assets/templates/custom_cover_page.tpl"
+
+
+
+
{% if config.site_name %}
+    <h1>{{ config.site_name }}</h1>
+{% endif %}
+<h2>This is my custom print cover page</h2>
+
+
+
+

As an example, have a look at the default cover_page.tpl.

+

Adding images↵

+

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.

+

Example:

+
+
{% if config.site_name %}
+    <h1>{{ config.site_name }}</h1>
+{% endif %}
+<img src="/assets/img/example.png" />
+
+
+
+

For a full example have a look at this custom cover page with an image.

+

Adding extra content↵

+

You might want to add some content to your cover page that's not yet specified in your mkdocs.yml file. Of course you could just hard-code it in your custom template file, but you could also make use of MkDocs's extra context feature, allowing you to use {{ config.extra.<your variable> }}

+

Example:

+
+
plugins:
+    - print-site:
+        add_cover_page: true
+        cover_page_template: "docs/assets/templates/custom_cover_page.tpl"
+
+extra:
+    abstract: This is a report about a topic
+
+
+
+
{% if config.site_name %}
+    <h1>{{ config.site_name }}</h1>
+{% endif %}
+<p>{{ config.extra.abstract }}</p>
+
+
+
+

Change the styling↵

+

You'll likely also want to change the styling to your liking. You can add your own CSS file using the extra_css option from MkDocs. mkdocs-print-site-plugin wraps the cover page in a <section> with id print-site-cover-page. You should use this in your CSS to ensure not affecting other pages.

+

Example:

+
+
plugins:
+    - print-site:
+        add_cover_page: true
+
+extra_css:
+    - docs/assets/css/my_cover_page.css
+
+
+
+
#print-site-cover-page h1 {
+    color: blue;
+}
+
+
+

Customize the print site banner↵

+

When the add_print_site_banner option is set to true, mkdocs-print-site-plugin will add a banner to the top of the print page. 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 where you can combine HTML and special jinja2 variables, such as the information specified in mkdocs.yml (see mkdocs project information).

+

Example:

+
+
plugins:
+    - print-site:
+        add_print_site_banner: true
+        print_site_banner_template: "docs/assets/templates/custom_banner.tpl"
+
+
+
+

+
+
+
+

As an example, have a look at the default print_site_banner.tpl.

Do not print↵

+

You might want to exclude certain parts of you website from the print site page. This can be useful when you don't want to include large images, tables, certain admonitions or appendixes to your site PDF.

+

Ignoring certain elements in a page↵

+

mkdocs-print-site-plugin offers the CSS class .print-site-plugin-ignore, that will ignore certain elements.

+

The Attribute Lists extension, which is part of the standard Markdown library, allows to add HTML attributes and CSS classes to Markdown elements, and can be enabled via mkdocs.yml.

+

To apply the .print-site-plugin-ignore class to an element, you can add {: .print-site-plugin-ignore } to many markdown elements, as explained in the attr_list docs. attr_list does not support all markdown elements (see limitations), but remember Markdown is a subset of HTML and anything which cannot be expressed in Markdown can always be expressed with raw HTML directly.

+

Example:

+
+
plugins:
+    - print-site
+
+markdown_extensions:
+    - attr_list
+
+
+
+
# Example page
+
+This paragraph is not part of the print site page.
+{: .print-site-plugin-ignore }
+
+![ignored image](some/path/image.png){: .print-site-plugin-ignore }
+
+You can also use HTML to hide things from printing:
+<span class="print-site-plugin-ignore">hello</span>
+
+
+
+

As another example, this paragraph will not be printed. Go have a look at the print site page and you'll find it missing.

+

Ignoring admonitions↵

+

Adding a class to admonitions is not supported by attr_list. You can use the .print-site-plugin-ignore class directly on admonitions however:

+
!!! info print-site-plugin-ignore
+
+    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.
+
+

Which renders as:

+
+

Info

+

As an example, this admonition will not be printed. Go have a look at the print site page and you'll find it missing.

+
+

Ignoring an entire page↵

+

In the plugin configuration in mkdocs.yml you can specify a list of page source paths (one per line) that should not be included in the print page (excluded from processing by this plugin). This can be useful for example to exlude large appendixes that you only want to display on the web version. The source path of a page is relative to your docs/ folder. You can also use globs instead of full source paths. To exclude docs/subfolder/page.md specify in your mkdocs.yml a line under exclude: with - subfolder/page.md. Some examples:

+
# mkdocs.yml
+plugins:
+  - print-site:
+      exclude:
+        - index.md
+        - subfolder/page.md
+        - another_page.md
+        - folder/*
+

Ended: How to guides

Demo Content↵

+

This content is here to demonstrate what it looks like while printing.

+

👉 Go ahead and visit the print page and check it out!

+

Links to other pages↵

+

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:

+ +

Links to other sections↵

+

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:

+ +

Magic links↵

+

Magic links and emails: turned to links as recognized

+ + + + + + + + + + + + + + + + + + + + + +
OutputCode
http://www.google.comhttp://www.google.com
johndoe@gmail.comjohndoe@gmail.com
www.google.comwww.google.com
+

Markdown extensions↵

+

MkDocs has support for many markdown extensions (see mkdocs-material reference). Below is a quick showcase so you can see how they print.

+
+

Phasellus posuere in sem ut cursus

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod +nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor +massa, nec semper lorem quam in massa.

+
+
+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod +nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor +massa, nec semper lorem quam in massa.

+
+
+

Note

+

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod +nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor +massa, nec semper lorem quam in massa.

+
def bubble_sort(items):
+    for i in range(len(items)):
+        for j in range(len(items) - 1 - i):
+            if items[j] > items[j + 1]:
+                items[j], items[j + 1] = items[j + 1], items[j]
+
+

Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in +sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. +Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.

+
+
Note

This is a collapsible block, that is collapsed by default.

+
+

Example of a button

+

Primary button

+

With icon

+
import tensorflow as tf
+
+
1
+2
+3
+4
+5
def bubble_sort(items):
+    for i in range(len(items)):
+        for j in range(len(items) - 1 - i):
+            if items[j] > items[j + 1]:
+                items[j], items[j + 1] = items[j + 1], items[j]
+
+
+
def bubble_sort(items):
+    for i in range(len(items)):
+        for j in range(len(items) - 1 - i):
+            if items[j] > items[j + 1]:
+                items[j], items[j + 1] = items[j + 1], items[j]
+
+

The range() function is used to generate a sequence of numbers.

+

Ctrl+Alt+Del

+
+
#include <stdio.h>
+
+int main(void) {
+  printf("Hello world!\n");
+  return 0;
+}
+
+
+
+
#include <iostream>
+
+int main(void) {
+  std::cout << "Hello world!" << std::endl;
+  return 0;
+}
+
+
+
+

Another tabbed content

+
+
    +
  • Sed sagittis eleifend rutrum
    • +
  • Donec vitae suscipit est
    • +
  • Nulla tempor lobortis orci
    • +
+
+
+
    +
  1. Sed sagittis eleifend rutrum
    2. +
  2. Donec vitae suscipit est
    3. +
  3. Nulla tempor lobortis orci
    4. +
+
+
+

Embedding content:

+
+

Example

+
+

Example:

+
* Sed sagittis eleifend rutrum
+* Donec vitae suscipit est
+* Nulla tempor lobortis orci
+
+

Result:

+
    +
  • Sed sagittis eleifend rutrum
    • +
  • Donec vitae suscipit est
    • +
  • Nulla tempor lobortis orci
    • +
+
+
+

Example:

+
1. Sed sagittis eleifend rutrum
+2. Donec vitae suscipit est
+3. Nulla tempor lobortis orci
+
+

Result:

+
    +
  1. Sed sagittis eleifend rutrum
    2. +
  2. Donec vitae suscipit est
    3. +
  3. Nulla tempor lobortis orci
    4. +
+
+
+
+ + + + + + + + + + + + + + + + + + + + + +
MethodDescription
GET Fetch resource
PUT Update resource
DELETE Delete resource
+

Footnotes in a text: Lorem ipsum1 dolor sit amet, consectetur adipiscing elit.2

+
    +
  • – .icons/material/account-circle.svg
    • +
  • – .icons/fontawesome/regular/laugh-wink.svg
    • +
  • :octicons-octoface-16: – .icons/octicons/octoface-16.svg
    • +
  • – Medium
    • +
  • – Twitter
    • +
  • – Facebook
    • +
+

😄

+

Images↵

+

mkdocs-print-site-plugin supports enumerating figure captions (which can be added easily using the img2fig plugin):

+
+ +
Image caption
+
+
+ +
Another image caption
+
+

+

+

+

+

Lists↵

+
    +
  1. +

    Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis + sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis + nulla. Vivamus a pharetra leo.

    +
      +
    1. +

      Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet + quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a + ultricies libero efficitur sed.

      +
      2. +
    2. +

      Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet + rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.

      +
        +
      1. Mauris dictum mi lacus
        2. +
      2. Ut sit amet placerat ante
        3. +
      3. Suspendisse ac eros arcu
        4. +
      +
      3. +
    +
    2. +
+
+
Lorem ipsum dolor sit amet
+
Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus +tellus non sem sollicitudin, quis rutrum leo facilisis.
+
Cras arcu libero
+
+

Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin +ut eros sed sapien ullamcorper consequat. Nunc ligula ante.

+

Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis. +Nam vulputate tincidunt fringilla. +Nullam dignissim ultrices urna non auctor.

+
+
+
    +
  • Lorem ipsum dolor sit amet, consectetur adipiscing elit
    • +
  • Vestibulum convallis sit amet nisi a tincidunt
      +
    • In hac habitasse platea dictumst
      • +
    • In scelerisque nibh non dolor mollis congue sed et metus
      • +
    • Praesent sed risus massa
      • +
    +
    • +
  • Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
    • +
+
\[ +\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} +\]
+

The homomorphism \(f\) is injective if and only if its kernel is only the +singleton set \(e_G\), because otherwise \(\exists a,b\in G\) with \(a\neq b\) such +that \(f(a)=f(b)\)00.

+

Dummy section↵

+

This section has an incoming anchor link, at the top of this page

+

Some lorem ipsum↵

+

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.

+

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.

+

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.

+

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.

+

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.

+
+
+
    +
  1. +

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. ↩

    +
    2. +
  2. +

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod +nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor +massa, nec semper lorem quam in massa. ↩

    +
    3. +
+

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:

+
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 for static code checking:

+
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:

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

+

Code Style↵

+

Make sure your code roughly follows PEP-8 and keeps things consistent with the rest of the code. I recommended using black to automatically format your code.

+

We use google-style docstrings.

+

Documentation↵

+

Is in docs/. To deploy the docs, run:

+
mkdocs gh-deploy
+
+
+
+
+
+ +
+
+
+
+ + + + + + + + \ No newline at end of file From 90e3ac104de45852b08c5fa03a26a2c52b6f9cb4 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Wed, 15 Sep 2021 13:30:20 +0200 Subject: [PATCH 19/25] Improve and extend documentation --- docs/how-to/banner.md | 42 +++++++++++++++++-- docs/how-to/cover_page.md | 16 +++---- docs/how-to/do_not_print.md | 20 +++++---- docs/how-to/export-HTML.md | 2 +- docs/how-to/export-PDF.md | 2 +- docs/how-to/pdf_button.md | 19 ++++----- docs/how-to/print_button.md | 21 +++++----- docs/index.md | 4 +- .../templates/print_site_banner.tpl | 4 +- 9 files changed, 84 insertions(+), 46 deletions(-) diff --git a/docs/how-to/banner.md b/docs/how-to/banner.md index 1e28059..a602764 100644 --- a/docs/how-to/banner.md +++ b/docs/how-to/banner.md @@ -1,8 +1,8 @@ # Customize the print site banner -When the `add_print_site_banner` option is set to true, `mkdocs-print-site-plugin` will add a banner to the top of the print page. You might want to customize this banner, for example by translating it to your language. +When a user visits the print page, it might not be immediately obvious how to use it. You can set the `add_print_site_banner` option to `true` to add a banner to the top of the HTML print page that will be hidden when printing. -You 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 special jinja2 variables, such as the information specified in `mkdocs.yml` (see [mkdocs project information](https://www.mkdocs.org/user-guide/configuration/#project-information)). +You might want to customize this banner, for example by translating it to your language. You can do that by specifying the path to a custom banner template in the `mkdocs.yml` file. This file should be a standard [jinja2 template](https://jinja.palletsprojects.com/en/2.11.x/templates/) where you can combine HTML and jinja2 variables. The information specified in `mkdocs.yml` will already by available as jinja2 variables (see [mkdocs project information](https://www.mkdocs.org/user-guide/configuration/#project-information)). _Example_: @@ -18,7 +18,43 @@ _Example_: === "docs/assets/templates/custom_banner.tpl" ```jinja - +

+ This box will disappear when printing + mkdocs-print-site-plugin +

+

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

+

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

``` As an example, have a look at the default [print_site_banner.tpl](https://github.com/timvink/mkdocs-print-site-plugin/tree/master/mkdocs_print_site_plugin/templates/print_site_banner.tpl). + +## Adding configurable content + +You might want to add some content to your cover page that's not yet specified in your `mkdocs.yml` file. +Of course you could just hard-code it in your custom template file, but you could also make use of MkDocs's [extra context](https://www.mkdocs.org/user-guide/custom-themes/#extra-context) feature, allowing you to use custom variables from your config file with `{{ config.extra. }}`. + +_Example_: + +=== "mkdocs.yml" + + ```yaml + plugins: + - print-site: + add_print_site_banner: true + print_site_banner_template: "docs/assets/templates/custom_banner.tpl" + + extra: + banner_message: "Save this page using File > Print > Save as PDF" + ``` + +=== "docs/assets/templates/custom_banner.tpl" + + ```jinja +

+ This box will disappear when printing + mkdocs-print-site-plugin +

+

{{ config.extra.banner_message }}

+ ``` + + diff --git a/docs/how-to/cover_page.md b/docs/how-to/cover_page.md index 95fed7f..f41d3b4 100644 --- a/docs/how-to/cover_page.md +++ b/docs/how-to/cover_page.md @@ -1,8 +1,8 @@ # Customize the cover page -When the `add_cover_page` option is set to true, `mkdocs-print-site-plugin` will generate a cover page when printing. This cover page is quite basic, and you might want to customize it. +By default the `add_cover_page` option is set to `true`, which will add a cover page to the print page. You might want to customize it more to your liking. -You can do that by specifying the path to a custom cover page template in the `mkdocs.yml` file. This file should be a standard [jinja2 template](https://jinja.palletsprojects.com/en/2.11.x/templates/) where you can combine HTML and jinja2 variables such as the information specified in `mkdocs.yml` (see [mkdocs project information](https://www.mkdocs.org/user-guide/configuration/#project-information)). +You can do that by specifying the path to a custom cover page template in the `mkdocs.yml` file. This file should be a standard [jinja2 template](https://jinja.palletsprojects.com/en/2.11.x/templates/) where you can combine HTML and jinja2 variables. The information specified in `mkdocs.yml` will already by available as jinja2 variables (see [mkdocs project information](https://www.mkdocs.org/user-guide/configuration/#project-information)). _Example_: @@ -24,7 +24,7 @@ _Example_:

This is my custom print cover page

``` -As an example, have a look at the default [cover_page.tpl](https://github.com/timvink/mkdocs-print-site-plugin/tree/master/mkdocs_print_site_plugin/templates/cover_page.tpl). +To get you started have a look at the default [cover_page.tpl](https://github.com/timvink/mkdocs-print-site-plugin/tree/master/mkdocs_print_site_plugin/templates/cover_page.tpl). ## Adding images @@ -41,11 +41,11 @@ _Example_: ``` -For a full example have a look at this [custom cover page with an image](https://github.com/timvink/mkdocs-print-site-plugin/blob/master/tests/fixtures/projects/with_markdown_ext/other_cover_page.tpl). +For a full working example have a look at this [custom cover page with an image](https://github.com/timvink/mkdocs-print-site-plugin/blob/master/tests/fixtures/projects/with_markdown_ext/other_cover_page.tpl). -## Adding extra content +## Adding configurable content -You might want to add some content to your cover page that's not yet specified in your `mkdocs.yml` file. Of course you could just hard-code it in your custom template file, but you could also make use of MkDocs's [extra context](https://www.mkdocs.org/user-guide/custom-themes/#extra-context) feature, allowing you to use `{{ config.extra. }}` +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. }}`. _Example_: @@ -72,7 +72,7 @@ _Example_: ## Change the styling -You'll likely also want to change the styling to your liking. You can add your own CSS file using the [extra_css](https://www.mkdocs.org/user-guide/configuration/#extra_css) option from MkDocs. `mkdocs-print-site-plugin` wraps the cover page in a `
` with id `print-site-cover-page`. You should use this in your CSS to ensure not affecting other pages. +You'll likely also want to change the styling of the cover page to your liking. You can add your own CSS file using the [extra_css](https://www.mkdocs.org/user-guide/configuration/#extra_css) option from MkDocs. `mkdocs-print-site-plugin` wraps the cover page in a `
`. You should use this in your CSS to ensure not affecting other pages. _Example_: @@ -93,4 +93,4 @@ _Example_: #print-site-cover-page h1 { color: blue; } - ``` \ No newline at end of file + ``` diff --git a/docs/how-to/do_not_print.md b/docs/how-to/do_not_print.md index 743492b..c16dcfd 100644 --- a/docs/how-to/do_not_print.md +++ b/docs/how-to/do_not_print.md @@ -1,14 +1,14 @@ -# Do not print +# Exclude content from print -You might want to exclude certain parts of you website from the print site page. This can be useful when you don't want to include large images, tables, certain [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) or appendixes to your site PDF. +You might want to exclude certain parts of you website from the print site page. This can be useful when you don't want to include certain page, large images, tables, certain [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) or appendixes to your site exports. -## Ignoring certain elements in a page +## Ignoring elements in a page `mkdocs-print-site-plugin` offers the CSS class `.print-site-plugin-ignore`, that will ignore certain elements. -The [Attribute Lists](https://python-markdown.github.io/extensions/attr_list/) extension, which is part of the standard Markdown library, allows to add HTML attributes and CSS classes to Markdown elements, and can be enabled via `mkdocs.yml`. +The [Attribute Lists](https://python-markdown.github.io/extensions/attr_list/) extension, which is part of the standard Markdown library, allows to add HTML attributes and CSS classes to Markdown elements, and needs to be enabled in your `mkdocs.yml`. -To apply the `.print-site-plugin-ignore` class to an element, you can add `{: .print-site-plugin-ignore }` to many markdown elements, as explained in the [attr_list docs](https://python-markdown.github.io/extensions/attr_list/). `attr_list` does not support all markdown elements (see [limitations](https://python-markdown.github.io/extensions/attr_list/#limitations)), but remember Markdown is a subset of HTML and anything which cannot be expressed in Markdown can always be expressed with raw HTML directly. +To apply the `.print-site-plugin-ignore` class to an element you can use `{: .print-site-plugin-ignore }` on many different markdown elements, as explained in the [attr_list docs](https://python-markdown.github.io/extensions/attr_list/). `attr_list` does not support all markdown elements (see [limitations](https://python-markdown.github.io/extensions/attr_list/#limitations)), but remember Markdown is a subset of HTML and anything which cannot be expressed in Markdown can always be expressed with raw HTML directly. _Example_: @@ -27,7 +27,7 @@ _Example_: ```md # Example page - This paragraph is not part of the print site page. + This paragraph will not be part of the print site page. {: .print-site-plugin-ignore } ![ignored image](some/path/image.png){: .print-site-plugin-ignore } @@ -41,7 +41,9 @@ As another example, this paragraph will not be printed. Go have a look at the [p ## Ignoring admonitions -Adding a class to [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) is not supported by `attr_list`. You can use the `.print-site-plugin-ignore` class directly on admonitions however: +Adding a class to [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions) is not supported by `attr_list`. You can use the `.print-site-plugin-ignore` class directly on admonitions however. + +_Example_: ```markdown !!! info print-site-plugin-ignore @@ -58,7 +60,9 @@ Which renders as: ## Ignoring an entire page -In the plugin configuration in `mkdocs.yml` you can specify a list of page source paths (one per line) that should not be included in the print page (excluded from processing by this plugin). This can be useful for example to exlude large appendixes that you only want to display on the web version. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude`: with `- subfolder/page.md`. Some examples: +In the plugin configuration in `mkdocs.yml` you can specify a list of page source paths (one per line) that should not be included in the print page (excluded from processing by this plugin). This can be useful for example to exlude large appendixes that you only want to display on the web version. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude`: with `- subfolder/page.md`. + +_Example_: ```yml # mkdocs.yml diff --git a/docs/how-to/export-HTML.md b/docs/how-to/export-HTML.md index dac7bb6..76799c6 100644 --- a/docs/how-to/export-HTML.md +++ b/docs/how-to/export-HTML.md @@ -1,6 +1,6 @@ # Export to HTML -After enabling the `print-site` plugin in your `mkdocs.yml`, you will have your entire site combined into a single page. That allows you to create a standalone HTML page: a single self-contained file that has all images and script embedded. This means you could send a site as an email attachment, a use case common within companies where deploying static sites might be more involved. +After enabling the `print-site` plugin in your `mkdocs.yml`, you will have your entire site combined into a single page. That allows you to create a standalone HTML page: a single self-contained file that has all images, styling and scripts embedded. This means you could send a site as an email attachment, a use case common within companies where deploying static sites might be more involved. In order to create a self-contained, standalone HTML file from the print page, we will need to embed images, CSS and javascript using [data URLs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs). We can do this quite easily using the [htmlark](https://github.com/BitLooter/htmlark) python package: diff --git a/docs/how-to/export-PDF.md b/docs/how-to/export-PDF.md index 50033af..2c4ff4a 100644 --- a/docs/how-to/export-PDF.md +++ b/docs/how-to/export-PDF.md @@ -15,7 +15,7 @@ We can use [nodejs](https://nodejs.org/en/) together with the [puppeteer](https: - In a separate terminal window, you can now run the PDF export with `url` (to your print page), `pdfPath` (name of output file) and `title` arguments: ```shell -node exportpdf.js http://localhost:8000/print_page.html out.pdf 'your website name' +node exportpdf.js http://localhost:8000/print_page.html out.pdf 'title' ``` ??? example "export_to_pdf.js" diff --git a/docs/how-to/pdf_button.md b/docs/how-to/pdf_button.md index c7f05fe..30a209b 100644 --- a/docs/how-to/pdf_button.md +++ b/docs/how-to/pdf_button.md @@ -1,18 +1,19 @@ # Adding a PDF button -You might want to make downloading a PDF even easier for your users. You could include a 'PDF' button on every page (like the one in the right corner of this page 👆) +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 👆). -MkDocs supports [theme extension](https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir), an easy way to override parts of a theme. -You can use `page.url_to_pdf` to get the link to site PDF from a page. +MkDocs supports [theme extension](https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir), an easy way to override parts of a theme. That will allow you to add a button to the top of every page. + +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: !!! info - While it might be easier for your users, using this option means you need to manually create the PDF everytime you make a change to your website. + 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. 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. ## Adding a PDF button to mkdocs-material theme -In `mkdocs-material` theme (see [customization](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks)), you can create a file for overrides and point to it your `mkdocs.yml`. You might also want to disable adding the print page to the navigation when you already have a button with the link. +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)). _Example_: @@ -23,10 +24,9 @@ _Example_: name: material custom_dir: docs/overrides - plugin: + plugins: - print-site: - path_to_pdf: "assets/the_name_of_your_file.pdf" - - add_to_navigation: false ``` === "docs/overrides/main.html" @@ -49,7 +49,7 @@ _Example_: ## Adding a print button to mkdocs theme -You can also [customize](https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme) the base mkdocs theme, by creating a file for overrides and pointing to it your `mkdocs.yml`. You might also want to disable adding the print page to the navigation when you already have a button with the link. +You can also [customize](https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme) the base mkdocs theme, by overriding `main.html`. _Example_: @@ -60,10 +60,9 @@ _Example_: name: mkdocs custom_dir: docs/overrides - plugin: + plugins: - print-site: - path_to_pdf: "assets/the_name_of_your_file.pdf" - - add_to_navigation: false ``` === "docs/overrides/main.html" diff --git a/docs/how-to/print_button.md b/docs/how-to/print_button.md index e2b9ec3..0fd48f5 100644 --- a/docs/how-to/print_button.md +++ b/docs/how-to/print_button.md @@ -1,13 +1,14 @@ # Adding a print button -You might want to customize your site to include a 'print' button on every page (like the one in the right corner of this page 👆) +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 👆. -MkDocs supports [theme extension](https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir), an easy way to override parts of a theme. -You can use `page.url_to_print_page` to get the link to the site print page. +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. + +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: ## Adding a print button to mkdocs-material theme -In `mkdocs-material` theme (see [customization](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks)), you can create a file for overrides and point to it your `mkdocs.yml`. You might also want to disable adding the print page to the navigation when you already have a button with the link. +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)). _Example_: @@ -18,9 +19,8 @@ _Example_: name: material custom_dir: docs/overrides - plugin: - - print-site: - - add_to_navigation: false + plugins: + - print-site ``` === "docs/overrides/main.html" @@ -43,7 +43,7 @@ _Example_: ## Adding a print button to mkdocs theme -You can also [customize](https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme) the base mkdocs theme, by creating a file for overrides and pointing to it your `mkdocs.yml`. You might also want to disable adding the print page to the navigation when you already have a button with the link. +You can also [customize](https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme) the base mkdocs theme, by overriding `main.html`. _Example_: @@ -54,9 +54,8 @@ _Example_: name: mkdocs custom_dir: docs/overrides - plugin: - - print-site: - - add_to_navigation: false + plugins: + - print-site ``` === "docs/overrides/main.html" diff --git a/docs/index.md b/docs/index.md index 9c35dda..f8265ea 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,5 +33,5 @@ plugins: ## Usage - Navigate to `/print_page/` or `print_page.html` -- Export to standalone HTML (see [export to HTML](how-to/export-HTML.html)) -- Export to PDF using your browser using *File > Print > Save as PDF* (see [export to PDF](how-to/export-PDF.html)) +- Export to standalone HTML (see [export to HTML](how-to/export-HTML.md)) +- Export to PDF using your browser using *File > Print > Save as PDF* (see [export to PDF](how-to/export-PDF.md)) diff --git a/mkdocs_print_site_plugin/templates/print_site_banner.tpl b/mkdocs_print_site_plugin/templates/print_site_banner.tpl index 04ad492..e4749cc 100644 --- a/mkdocs_print_site_plugin/templates/print_site_banner.tpl +++ b/mkdocs_print_site_plugin/templates/print_site_banner.tpl @@ -2,5 +2,5 @@ This box will disappear when printing mkdocs-print-site-plugin

-

This page combines all site pages and applies print and PDF friendly styling. Print or export to PDF using File > Print > Save as PDF.

-

For creating PDFs, make sure to use the browser's print and save-as-pdf function instead of the system dialog.

+

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

+

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

From c0a86c691c115060bd7d4744b1ffa85d3cc0b2ec Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Wed, 15 Sep 2021 14:13:15 +0200 Subject: [PATCH 20/25] Fix the HTML sidebar ToC to only show page heading level 1 and section headings --- docs/options.md | 8 +-- mkdocs_print_site_plugin/renderer.py | 74 ++++++++++------------------ mkdocs_print_site_plugin/urls.py | 11 +++++ 3 files changed, 42 insertions(+), 51 deletions(-) diff --git a/docs/options.md b/docs/options.md index e9c0d3f..0ae7448 100644 --- a/docs/options.md +++ b/docs/options.md @@ -30,13 +30,13 @@ plugins: : 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`. `add_table_of_contents` -: Default is `true`. Adds a table of contents section at the beginning of the print page (in print version, not HTML version). +: 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). `toc_title` -: Default is `'Table of Contents'`. When `add_table_of_contents` is set to `true` this setting controls the name of the table of contents. This setting is ignored when `add_table_of_contents` is set to `false`. +: 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`. `toc_depth` -: Default is `3`. When `add_table_of_contents` is set to `true` this setting controls the depth of the table of contents. This setting is ignored when `add_table_of_contents` is set to `false`. +: 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`. `add_full_urls` : 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. @@ -58,7 +58,7 @@ plugins: : Default `""`. The path to a custom cover page template to use. See [Customizing the Cover Page](how-to/cover_page.md) for more info. `add_print_site_banner` -: Default `false`. When enabled, a banner is added to the top of the HTML print page, explaining to users the current page contains all site pages. +: 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. `print_site_banner_template` : 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. diff --git a/mkdocs_print_site_plugin/renderer.py b/mkdocs_print_site_plugin/renderer.py index 1ca3442..dc1552b 100644 --- a/mkdocs_print_site_plugin/renderer.py +++ b/mkdocs_print_site_plugin/renderer.py @@ -3,7 +3,7 @@ from mkdocs.structure.toc import AnchorLink, TableOfContents -from mkdocs_print_site_plugin.urls import fix_internal_links, get_page_key +from mkdocs_print_site_plugin.urls import fix_internal_links, get_page_key, to_snake_case from mkdocs_print_site_plugin.exclude import exclude logger = logging.getLogger("mkdocs.plugins") @@ -33,6 +33,9 @@ def __init__( self.items = [] + def _get_items(self): + return [i for i in self.items if not i == self.print_page] + def write_combined(self): """ Generates the HTML of the page that combines all page into one. @@ -86,9 +89,9 @@ def get_html_from_items(items: list, dir_urls: bool, excluded_pages: list, secti item_html += fix_internal_links(item.html, item.url, directory_urls=dir_urls) if item.is_section: - item_html += "%s" % ( - min(6, section_depth + 1), - item.title, + item_html += ( + "%s ↵" # noqa + % (min(6, section_depth + 1), to_snake_case(item.title), item.title, to_snake_case(item.title)) ) item_html += get_html_from_items(item.children, dir_urls, excluded_pages, section_depth + 1) # We also need to indicate the end of section page @@ -98,7 +101,7 @@ def get_html_from_items(items: list, dir_urls: bool, excluded_pages: list, secti return item_html html += get_html_from_items( - self.items, + self._get_items(), dir_urls=self.mkdocs_config.get("use_directory_urls"), excluded_pages=self.plugin_config.get("exclude", []), ) @@ -165,55 +168,32 @@ def get_toc_sidebar(self) -> TableOfContents: Generate a MkDocs a navigation sidebar. We want to generate one for the print page also, so we can export HTML. - Here we go over each page with a toc. Then we fix the anchor links. - See also https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/toc.py + We'll generate a ToC with an entry for each page (the h1). A section will be level 1, + and we indent with the pages inside. + + Reference: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/toc.py """ toc = [] - for item in self.items: - if hasattr(item, "toc"): + for item in self._get_items(): + if item.is_page: + # Take the first item of the page's ToC + # Which will be the heading 1 + p = item.toc.items[0] page_key = get_page_key(item.url) - item_toc = item.toc - if hasattr(item_toc, "items"): - for toc_link in item.toc.items: - toc_link = update_toc_item(page_key, toc_link) - toc += [toc_link] - - # Make sure the sidebar ToC also respects - # the plugin's toc_depth parameter - toc = clear_children_up_to(self.plugin_config.get("toc_depth"), toc) - - return TableOfContents(toc) - - -def clear_children_up_to(depth, items): - """ - Filters items in sidebar table of contents to a given depth. - """ - for toc_item in items: - # note the -1 is there because of the hack on levels in update_toc_item() - if toc_item.level == depth - 1: - toc_item.children = [] - else: - toc_item.children = clear_children_up_to(depth, toc_item.children) - return items + toc.append(AnchorLink(title=p.title, id=f"{page_key}-{p.id}", level=0)) + if item.is_section: -def update_toc_item(page_key: str, toc_link: AnchorLink) -> AnchorLink: - """ - Updates a AnchorItem to work on the print page. - """ - # update the link to point to the anchor in print page instead of actual page - toc_link.id = f"{page_key}-{toc_link.id}" + section_link = AnchorLink(title=item.title, id=f"section-{to_snake_case(item.title)}", level=0) - # MkDocs-material parses the TOC and does not display level 1 - # This is a small hack that will set all levels off by 1 - # Will work just fine in base mkdocs theme also - toc_link.level = toc_link.level - 1 + subpages = [p for p in item.children if p.is_page] + for page in subpages: + page_key = get_page_key(page.url) + p = page.toc.items[0] + section_link.children.append(AnchorLink(title=p.title, id=f"{page_key}-{p.id}", level=1)) - if len(toc_link.children) > 0: - for link in toc_link.children: - update_toc_item(page_key, link) + toc.append(section_link) - return toc_link + return TableOfContents(toc) diff --git a/mkdocs_print_site_plugin/urls.py b/mkdocs_print_site_plugin/urls.py index 29f8b81..eb105c6 100644 --- a/mkdocs_print_site_plugin/urls.py +++ b/mkdocs_print_site_plugin/urls.py @@ -262,3 +262,14 @@ def fix_internal_links(page_html, page_url, directory_urls): page_html = ('
' % page_key) + page_html + "
" return page_html + + +def to_snake_case(text): + """ + Convert string to snake_case. + + Example: + + 'Hi there!' -> 'hi_there_' + """ + return re.sub("\W+", "-", text).lower() From 9b83cc71a1328e9f2862371fe1e6bccb931ae096 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Wed, 15 Sep 2021 14:31:07 +0200 Subject: [PATCH 21/25] Fix Toc animation and homepage navigation --- mkdocs_print_site_plugin/css/print-site.css | 3 +++ mkdocs_print_site_plugin/renderer.py | 12 +++++------- mkdocs_print_site_plugin/templates/cover_page.tpl | 2 +- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/mkdocs_print_site_plugin/css/print-site.css b/mkdocs_print_site_plugin/css/print-site.css index 1770ff8..a4f749b 100644 --- a/mkdocs_print_site_plugin/css/print-site.css +++ b/mkdocs_print_site_plugin/css/print-site.css @@ -192,6 +192,9 @@ div.print-site-add-full-url section.print-page a[href^="http"]::after{ #print-site-page h6:target { animation: highlight 1.5s ease; } +#print-site-page .print-page:target h1 { + animation: highlight 1.5s ease; +} @keyframes highlight { from { color: orange; } to { color: none; } diff --git a/mkdocs_print_site_plugin/renderer.py b/mkdocs_print_site_plugin/renderer.py index dc1552b..74376b8 100644 --- a/mkdocs_print_site_plugin/renderer.py +++ b/mkdocs_print_site_plugin/renderer.py @@ -178,12 +178,11 @@ def get_toc_sidebar(self) -> TableOfContents: for item in self._get_items(): if item.is_page: - # Take the first item of the page's ToC - # Which will be the heading 1 - p = item.toc.items[0] page_key = get_page_key(item.url) - - toc.append(AnchorLink(title=p.title, id=f"{page_key}-{p.id}", level=0)) + # navigate to top of page if page is homepage + if page_key == "index": + page_key = "" + toc.append(AnchorLink(title=item.title, id=f"{page_key}", level=0)) if item.is_section: section_link = AnchorLink(title=item.title, id=f"section-{to_snake_case(item.title)}", level=0) @@ -191,8 +190,7 @@ def get_toc_sidebar(self) -> TableOfContents: subpages = [p for p in item.children if p.is_page] for page in subpages: page_key = get_page_key(page.url) - p = page.toc.items[0] - section_link.children.append(AnchorLink(title=p.title, id=f"{page_key}-{p.id}", level=1)) + section_link.children.append(AnchorLink(title=page.title, id=f"{page_key}", level=1)) toc.append(section_link) diff --git a/mkdocs_print_site_plugin/templates/cover_page.tpl b/mkdocs_print_site_plugin/templates/cover_page.tpl index 64f7bd8..af282cb 100644 --- a/mkdocs_print_site_plugin/templates/cover_page.tpl +++ b/mkdocs_print_site_plugin/templates/cover_page.tpl @@ -37,7 +37,7 @@ {{ config.copyright }} {% endif %} - + From 25bc443bd2f16781b6d1e4189c57b1d6fc5f5488 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Wed, 15 Sep 2021 14:47:35 +0200 Subject: [PATCH 22/25] Fix validation of heading 1 in a page, now only validate pages that are actually in the navigation --- mkdocs_print_site_plugin/plugin.py | 16 +++++++++------- mkdocs_print_site_plugin/utils.py | 14 ++++++++++++++ 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/mkdocs_print_site_plugin/plugin.py b/mkdocs_print_site_plugin/plugin.py index ca5df60..51dcf45 100644 --- a/mkdocs_print_site_plugin/plugin.py +++ b/mkdocs_print_site_plugin/plugin.py @@ -9,7 +9,7 @@ from mkdocs.utils import write_file, copy_file, get_relative_url, warning_filter from mkdocs_print_site_plugin.renderer import Renderer -from mkdocs_print_site_plugin.utils import get_theme_name +from mkdocs_print_site_plugin.utils import flatten_nav, get_theme_name logger = logging.getLogger("mkdocs.plugins") logger.addFilter(warning_filter) @@ -147,6 +147,7 @@ def on_nav(self, nav, config, files, **kwargs): # Save the (order of) pages and sections in the navigation before adding the print page self.renderer.items = nav.items + self.all_pages_in_nav = flatten_nav(nav.items) # Optionally add the print page to the site navigation if self.config.get("add_to_navigation"): @@ -172,12 +173,13 @@ def on_page_content(self, html, page, config, files, **kwargs): # We need to validate that the first heading on each page is a h1 # This is required for the print page table of contents and enumeration logic if self.config.get("add_table_of_contents") or self.config.get("enumerate_headings"): - match = re.search(r"\ str: return "mkdocs" else: return name + + +def flatten_nav(items): + """ + Create a flat list of pages from a nested navigation. + """ + pages = [] + + for item in items: + if item.is_page: + pages.append(item) + if item.is_section: + pages.append(flatten_nav(item.children)) + return pages From 8f05cf46d9978d40a8ee85e11e5f8daea7da56f3 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Wed, 15 Sep 2021 15:16:21 +0200 Subject: [PATCH 23/25] Fix bug with pages that have names starting with a number --- mkdocs_print_site_plugin/urls.py | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/mkdocs_print_site_plugin/urls.py b/mkdocs_print_site_plugin/urls.py index eb105c6..3411fce 100644 --- a/mkdocs_print_site_plugin/urls.py +++ b/mkdocs_print_site_plugin/urls.py @@ -175,14 +175,14 @@ def fix_tabbed_content(page_html, page_key): """ - regex = re.compile(r"()", flags=re.I) - page_html = re.sub(regex, fr"\1{page_key}-\2\3", page_html) + regex = re.compile(r"(\)", re.I) + page_html = re.sub(regex, fr"\g<1>{page_key}-\g<2>\g<3>", page_html) - regex = re.compile(r"()", flags=re.I) - page_html = re.sub(regex, fr"\1{page_key}-\2\3", page_html) + regex = re.compile(r"(\)", re.I) + page_html = re.sub(regex, fr"\g<1>{page_key}-\g<2>\g<3>", page_html) - regex = re.compile(r"()", flags=re.I) - page_html = re.sub(regex, fr"\1{page_key}-\2\3", page_html) + regex = re.compile(r"(\)", re.I) + page_html = re.sub(regex, fr"\g<1>{page_key}-\g<2>\g<3>", page_html) return page_html @@ -253,10 +253,14 @@ def fix_internal_links(page_html, page_url, directory_urls): """ page_key = get_page_key(page_url) - page_html = fix_href_links(page_html, page_key, page_url, directory_urls) - page_html = update_anchor_ids(page_html, page_key) - page_html = fix_tabbed_content(page_html, page_key) - page_html = fix_image_src(page_html, page_url, directory_urls) + try: + page_html = fix_href_links(page_html, page_key, page_url, directory_urls) + page_html = update_anchor_ids(page_html, page_key) + page_html = fix_tabbed_content(page_html, page_key) + page_html = fix_image_src(page_html, page_url, directory_urls) + except: + print(f"Could not fix page '{page_url}', please report an issue on github") + raise # Finally, wrap the entire page in a section with an anchor ID page_html = ('
' % page_key) + page_html + "
" From bcce1f2eee1118602b8aa26274712ff1831fbd06 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Wed, 15 Sep 2021 15:22:57 +0200 Subject: [PATCH 24/25] Fix closing header level for section headings --- mkdocs_print_site_plugin/renderer.py | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/mkdocs_print_site_plugin/renderer.py b/mkdocs_print_site_plugin/renderer.py index 74376b8..1e8cb5c 100644 --- a/mkdocs_print_site_plugin/renderer.py +++ b/mkdocs_print_site_plugin/renderer.py @@ -89,9 +89,16 @@ def get_html_from_items(items: list, dir_urls: bool, excluded_pages: list, secti item_html += fix_internal_links(item.html, item.url, directory_urls=dir_urls) if item.is_section: - item_html += ( - "%s ↵" # noqa - % (min(6, section_depth + 1), to_snake_case(item.title), item.title, to_snake_case(item.title)) + item_html += """ + + %s ↵ + + """ % ( + min(6, section_depth + 1), + to_snake_case(item.title), + item.title, + to_snake_case(item.title), + min(6, section_depth + 1), ) item_html += get_html_from_items(item.children, dir_urls, excluded_pages, section_depth + 1) # We also need to indicate the end of section page From 3322c9b209f3895f4e3e6b97a973d87c74000ab3 Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Wed, 15 Sep 2021 15:23:27 +0200 Subject: [PATCH 25/25] Bump to v2.0.0 --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index c47164f..5cc138d 100644 --- a/setup.py +++ b/setup.py @@ -9,7 +9,7 @@ setup( name="mkdocs-print-site-plugin", - version="1.3.0", + version="2.0.0", description="MkDocs plugin that combines all pages into one, allowing for easy export to PDF and standalone HTML.", long_description=long_description, long_description_content_type="text/markdown",