Fix Markdown headers (#696)

Author: adiroiban

docs/configuration.rst

@@ -82,7 +82,7 @@ Top level keys
     When using reStructuredText, formatted titles are underlined using the ``underlines`` configuration.
     For titles, the first value from ``underlines`` is used to create the underline (which is inserted on the line following the title).
     If the template has an ``.md`` suffix, we assume we are looking at markdown format and the title is applied as, i.e. full control over the title format is given to the user.
-    This choice is made because setting the correct markdown header level automatically is non-trivial (mainly because you don't know what context the generated CHANGELOG entries are being written into).
+    The top header level is inferred from this, e.g. ``title_format = "(v{version})=\n### {version}"`` will render the title at level 3, categories at level 4, and so on.
 
 ``issue_format``
     A format string for rendering the issue/ticket number in newsfiles.

src/towncrier/_builder.py

@@ -362,6 +362,7 @@ def render_fragments(
     top_underline: str = "=",
     all_bullets: bool = False,
     render_title: bool = True,
+    md_header_level: int = 1,
 ) -> str:
     """
     Render the fragments into a news file.
@@ -435,6 +436,7 @@ def get_indent(text: str) -> str:
         top_underline=top_underline,
         get_indent=get_indent,  # simplify indentation in the jinja template.
         issues_by_category=issues_by_category,
+        header_prefix="#" * md_header_level,
     )
 
     for line in res.split("\n"):

src/towncrier/build.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import os
+import re
 import sys
 
 from datetime import date
@@ -213,6 +214,16 @@ def __main(
     # in the template.
     render_title = config.title_format == ""
 
+    # Add format-specific context to the template
+    md_header_level = 1
+    if is_markdown:
+        if config.title_format:
+            m = re.search(r"^#+(?=\s)", config.title_format, re.MULTILINE)
+            lvl = len(m[0]) if m else 0
+        else:  # TODO: derive from template or make configurable?
+            lvl = 1 if render_title else 0
+        md_header_level = lvl
+
     rendered = render_fragments(
         # The 0th underline is used for the top line
         template,
@@ -225,6 +236,7 @@ def __main(
         top_underline=config.underlines[0],
         all_bullets=config.all_bullets,
         render_title=render_title,
+        md_header_level=md_header_level,
     )
 
     if config.title_format:

src/towncrier/newsfragments/695.bugfix.rst

@@ -0,0 +1 @@
+Markdown header level is correctly inferred from ``title_format``.

src/towncrier/templates/default.md

@@ -1,19 +1,19 @@
 {% if render_title %}
 {% if versiondata.name %}
-# {{ versiondata.name }} {{ versiondata.version }} ({{ versiondata.date }})
+{{header_prefix}} {{ versiondata.name }} {{ versiondata.version }} ({{ versiondata.date }})
 {% else %}
-# {{ versiondata.version }} ({{ versiondata.date }})
+{{header_prefix}} {{ versiondata.version }} ({{ versiondata.date }})
 {% endif %}
 {% endif %}
 {% for section, _ in sections.items() %}
 {% if section %}
 
-## {{section}}
+{{header_prefix}}# {{section}}
 {% endif %}
 
 {% if sections[section] %}
 {% for category, val in definitions.items() if category in sections[section] %}
-##{% if section %}#{% endif %} {{ definitions[category]['name'] }}
+{{header_prefix}}#{% if section %}#{% endif %} {{ definitions[category]['name'] }}
 
 {% for text, values in sections[section][category].items() %}
 - {{ text }}

src/towncrier/test/test_build.py

@@ -16,7 +16,7 @@
 
 from .._shell import cli
 from ..build import _main
-from .helpers import read, read_pkg_resource, with_git_project, with_project, write
+from .helpers import read, with_git_project, with_project, write
 
 
 class TestCli(TestCase):
@@ -1086,7 +1086,7 @@ def test_title_format_custom_markdown(self, runner):
 
             [20-01-2001] CUSTOM RELEASE for FooBarBaz version 7.8.9
 
-            ## Features
+            # Features
 
             - Adds levitation (#123)
 
@@ -1104,7 +1104,6 @@ def test_title_format_custom_markdown(self, runner):
         package = "foo"
         filename = "NEWS.md"
         title_format = "### [{project_date}] CUSTOM RELEASE for {name} version {version}"
-        template = "custom_template.md"
         """
     )
     def test_markdown_injected_after_header(self, runner):
@@ -1136,13 +1135,6 @@ def test_markdown_injected_after_header(self, runner):
             dedent=True,
         )
 
-        default_template = read_pkg_resource("templates/default.md")
-        assert "##{%" in default_template
-        write(
-            "custom_template.md",
-            contents=default_template.replace("##{%", "####{%"),
-        )
-
         result = runner.invoke(_main, ["--date", "01-01-2001"], catch_exceptions=False)
 
         with open("foo/newsfragments/123.feature", "w") as f: