Merge pull request #104 from timvink/support_missing_h1

Support pages with missing h1 tags

Author: timvink

mkdocs_print_site_plugin/plugin.py

@@ -216,19 +216,6 @@ def on_page_content(self, html, page, config, files, **kwargs):
         if page != self.print_page:
             page.html = html
 
-        # 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"
-        ):
-            if page in self.all_pages_in_nav:
-                match = re.search(r"\<h[0-6]", html)
-                if match:
-                    if not match.group() == "<h1":
-                        msg = f"The page {page.title} ({page.file.src_path}) does not start with a level 1 heading."
-                        msg += "This is required for print page Table of Contents and/or enumeration of headings."
-                        raise AssertionError(msg)
-
         # Link to the PDF version of the entire site on a page.
         if self.config.get("path_to_pdf") != "":
             pdf_url = self.config.get("path_to_pdf")

mkdocs_print_site_plugin/renderer.py

@@ -76,7 +76,7 @@ def get_html_from_items(
             """
             Get all the HTML from the pages.
             """
-            item_html = ""
+            items_html = ""
 
             for item in items:
                 if item.is_page:
@@ -94,13 +94,31 @@ def get_html_from_items(
                                 % item.file.src_path
                             )
                             continue
+
+                        item_html = item.html
+                        
+                        # Add missing h1 tag if it doesn't exist
+                        if not item_html.startswith("<h1"):
+                            item_html = f"<h1 id=\"{to_snake_case(item.title)}\">{item.title}</h1>{item_html}"
+                            logger.warning(f"[mkdocs-print-site] '{item.file.src_path}' file is missing a leading h1 tag. Added to the print-page with title '{item.title}'")
+                        
+                        # Support mkdocs-material tags
+                        # See https://squidfunk.github.io/mkdocs-material/plugins/tags
+                        if "tags" in item.meta:
+                            tags = item.meta["tags"]
+                            tags_html = "<nav class='md-tags'>"
+                            for tag in tags:
+                                tags_html += f"<span class='md-tag'>{tag}</span>"
+                            tags_html += "</nav>"
+                            item_html = tags_html + item_html
+                        
                         # Update internal anchor links, image urls, etc
-                        item_html += fix_internal_links(
-                            item.html, item.url, directory_urls=dir_urls
+                        items_html += fix_internal_links(
+                            item_html, item.url, directory_urls=dir_urls
                         )
 
                 if item.is_section:
-                    item_html += """
+                    items_html += """
                         <h%s class='nav-section-title' id='section-%s'>
                             %s <a class='headerlink' href='#section-%s' title='Permanent link'>↵</a>
                         </h%s>
@@ -111,16 +129,16 @@ def get_html_from_items(
                         to_snake_case(item.title),
                         min(6, section_depth + 1),
                     )
-                    item_html += get_html_from_items(
+                    items_html += get_html_from_items(
                         item.children, dir_urls, excluded_pages, section_depth + 1
                     )
                     # We also need to indicate the end of section page
                     # We do that using a h1 with a specific class
                     # In CSS we display:none, in JS we can use it for formatting the table of contents.
-                    item_html += (
+                    items_html += (
                         "<h1 class='nav-section-title-end'>Ended: %s</h1>" % item.title
                     )
-            return item_html
+            return items_html
 
         html += get_html_from_items(
             self._get_items(),

setup.py

@@ -9,7 +9,7 @@
 
 setup(
     name="mkdocs-print-site-plugin",
-    version="2.4.1",
+    version="2.5.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",

tests/fixtures/projects/mkdocs_material_tags/docs/index.md

@@ -0,0 +1,10 @@
+---
+tags:
+  - HTML5
+  - JavaScript
+  - CSS
+---
+
+# Hello there
+
+Testing [tags](https://squidfunk.github.io/mkdocs-material/plugins/tags/?h=tags#usage) plugin.

tests/fixtures/projects/mkdocs_material_tags/mkdocs.yml

@@ -0,0 +1,12 @@
+site_name: Test
+
+theme:
+  name: material
+
+plugins:
+    - tags
+    - print-site:
+        add_to_navigation: true
+  
+markdown_extensions:
+    - attr_list

tests/test_building.py

@@ -269,10 +269,17 @@ def test_basic_build6(tmp_path):
 
 def test_basic_build7(tmp_path):
     """
-    Test error when page does not start with h1 heading.
+    Test when page does not start with h1 heading.
+
+    As of v2.5.0, this is allowed (the plugin will add a heading to the print page)
     """
-    check_build(tmp_path, "bad_headings/mkdocs.yml", exit_code=1)
+    check_build(tmp_path, "bad_headings/mkdocs.yml", exit_code=0)
 
+def test_build_with_material_tags(tmp_path):
+    """
+    Test support with tags.
+    """
+    check_build(tmp_path, "mkdocs_material_tags/mkdocs.yml", exit_code=0)
 
 def test_basic_disable_plugin(tmp_path):
     """