Merge pull request #513 from davep/post-header-order

Retain relative header structure in archive pages

Author: davep

ChangeLog.md

@@ -11,6 +11,11 @@
 - Changed the links and socials headings in the sidebar to `div`s from
   `h2`s, leaving headings only used in the main page or article.
   ([#512](https://github.com/davep/blogmore/pull/512))
+- Changed the heading level of post content in list views (index, archives,
+  tags, categories) to be relative to the post title. For example, if a post
+  uses `h2` headings, they will be rendered as `h3` in list views where the
+  post title itself is an `h2`, maintaining a correct heading hierarchy.
+  ([#513](https://github.com/davep/blogmore/pull/513))
 
 **Released: WiP**
 

src/blogmore/renderer.py

@@ -1,6 +1,7 @@
 """Template rendering using Jinja2."""
 
 import datetime as dt
+import re
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlparse
@@ -66,6 +67,7 @@ def __init__(
         self.env.filters["format_date"] = self._format_date
         self.env.filters["format_date_plain"] = self._format_date_plain
         self.env.filters["is_external_link"] = self._is_external_link
+        self.env.filters["shift_headings"] = self._shift_headings
 
         # Provide default values for pagination context variables so that
         # templates rendering without a full generator context (e.g. tests)
@@ -189,6 +191,31 @@ def _is_external_link(self, href: str) -> bool:
         # All other links with schemes are external
         return True
 
+    @staticmethod
+    def _shift_headings(html: str, shift: int = 1) -> str:
+        """Shift HTML heading levels (h1-h6) by a given amount.
+
+        Args:
+            html: The HTML content to modify.
+            shift: The number of levels to shift headings by. Positive values
+                make headings smaller (e.g. h1 -> h2), negative values make
+                them larger. Results are clamped to the h1-h6 range.
+
+        Returns:
+            The HTML with heading levels shifted.
+        """
+        if shift == 0:
+            return html
+
+        def shift_tag(match: re.Match[str]) -> str:
+            prefix, level_str = match.groups()
+            level = int(level_str)
+            new_level = max(1, min(6, level + shift))
+            return f"<{prefix}{new_level}"
+
+        # Matches <h1, <h2, ..., </h1, </h2, ...
+        return re.sub(r"<(/?h)([1-6])", shift_tag, html)
+
     def render_post(self, post: Post, **context: Any) -> str:
         """Render a single blog post.
 

src/blogmore/templates/_post_summary.html

@@ -33,7 +33,7 @@ <h2><a href="{{ post.url }}">{{ post.title }}{% if post.draft %} 🚧{% endif %}
     </div>
     {% endif %}
     <div class="post-content">
-        {{ post.html_content|safe }}
+        {{ post.html_content|shift_headings(1)|safe }}
     </div>
     {% if post.tags %}
     <div class="tags">

tests/test_renderer.py

@@ -1132,6 +1132,69 @@ def test_post_summary_omits_reading_time_by_default(
 
         assert "reading-time" not in html
 
+    def test_shift_headings_filter(self) -> None:
+        """Test the shift_headings filter directly."""
+        html = "<h1>Title</h1><h2>Subtitle</h2><p>Text</p><h3>Small</h3>"
+
+        # Shift by 1
+        shifted = TemplateRenderer._shift_headings(html, 1)
+        assert "<h2>Title</h2>" in shifted
+        assert "<h3>Subtitle</h3>" in shifted
+        assert "<h4>Small</h4>" in shifted
+        assert "<p>Text</p>" in shifted
+
+        # Shift by 2
+        shifted = TemplateRenderer._shift_headings(html, 2)
+        assert "<h3>Title</h3>" in shifted
+        assert "<h4>Subtitle</h4>" in shifted
+        assert "<h5>Small</h5>" in shifted
+
+        # Clamping to h6
+        html_h6 = "<h6>Already small</h6>"
+        shifted = TemplateRenderer._shift_headings(html_h6, 1)
+        assert "<h6>Already small</h6>" in shifted
+
+        # Shift by 0
+        assert TemplateRenderer._shift_headings(html, 0) == html
+
+        # Negative shift (shift up)
+        html_h2 = "<h2>Title</h2>"
+        shifted = TemplateRenderer._shift_headings(html_h2, -1)
+        assert "<h1>Title</h1>" in shifted
+
+        # Clamping to h1
+        shifted = TemplateRenderer._shift_headings(html_h2, -2)
+        assert "<h1>Title</h1>" in shifted
+
+    def test_shift_headings_closing_tags(self) -> None:
+        """Test that closing heading tags are also shifted."""
+        html = "<h2>Title</h2>"
+        shifted = TemplateRenderer._shift_headings(html, 1)
+        assert "<h3>Title</h3>" in shifted
+
+    def test_shift_headings_in_summary(self) -> None:
+        """Test that headings are shifted when rendering a post summary."""
+        renderer = TemplateRenderer()
+        post = Post(
+            path=Path("test.md"),
+            title="Post Title",
+            content="## Subheading",
+            html_content="<h2>Subheading</h2>",
+            date=dt.datetime(2024, 1, 15, 12, 0, 0, tzinfo=dt.UTC),
+        )
+
+        html = renderer.render_index(
+            posts=[post],
+            page=1,
+            total_pages=1,
+            site_title="Test Blog",
+        )
+
+        # Post title in index is h2
+        assert "<h2>" in html
+        # Subheading in content should be shifted to h3
+        assert "<h3>Subheading</h3>" in html
+
     def test_listing_meta_tags_on_tag_page(self, sample_post: Post) -> None:
         """Test that tag pages include standard listing meta tags."""
         renderer = TemplateRenderer()