From 6bcf951408abf3792aba4905f1c11ff2475e7aa4 Mon Sep 17 00:00:00 2001
From: Saptak Sengupta <saptak013@gmail.com>
Date: Sat, 2 May 2026 19:59:20 +0530
Subject: Update initial header level in BLOG_DOCUTILS_SETTINGS to 2 (#2609)

Sets initial header level for rst to 2 since it always starts with
heading level 1 automatically but keeps markdown baselevel to 1 since
markdown has actual heading level applied.
---
 blog/models.py | 7 +++++--
 blog/tests.py  | 2 +-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/blog/models.py b/blog/models.py
index 06fcee6f..ac7f4d48 100644
--- a/blog/models.py
+++ b/blog/models.py
@@ -17,7 +17,7 @@ from markdown.extensions.toc import TocExtension, slugify as _md_title_slugify
 
 BLOG_DOCUTILS_SETTINGS = {
     "doctitle_xform": False,
-    "initial_header_level": 1,
+    "initial_header_level": 2,
     "id_prefix": "s-",
     "raw_enabled": False,
     "file_insertion_enabled": False,
@@ -61,7 +61,10 @@ class ContentFormat(models.TextChoices):
                 source,
                 output_format="html",
                 extensions=[
-                    # baselevel matches `initial_header_level` from BLOG_DOCUTILS_SETTINGS
+                    # baselevel is 1 unlike `initial_header_level` from
+                    # BLOG_DOCUTILS_SETTINGS because rst always starts from heading
+                    # level 1, but markdown can have specific heading levels so
+                    # starting from 1 makes sense.
                     "tables",
                     TocExtension(baselevel=1, slugify=_md_slugify),
                 ],
diff --git a/blog/tests.py b/blog/tests.py
index 87f3fc14..fb272385 100644
--- a/blog/tests.py
+++ b/blog/tests.py
@@ -129,7 +129,7 @@ class EntryTestCase(DateTimeMixin, TestCase):
             content_format=ContentFormat.REST,
         )
         self.assertHTMLEqual(
-            entry.body_html, '<div class="section" id="s-test"><h1>test</h1></div>'
+            entry.body_html, '<div class="section" id="s-test"><h2>test</h2></div>'
         )
 
     def test_header_base_level_markdown(self):
-- 
cgit v1.3