Fix negative heading-offsets (#271)

Author: mondeja

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkdocs-include-markdown-plugin"
-version = "7.1.6"
+version = "7.1.7"
 description = "Mkdocs Markdown includer plugin."
 readme = "README.md"
 license = "Apache-2.0"

src/mkdocs_include_markdown_plugin/directive.py

@@ -208,7 +208,7 @@ def parse_filename_argument(
 
 def parse_string_argument(match: re.Match[str] | None) -> str | None:
     """Return the string argument matched by ``match``."""
-    if match is None:
+    if match is None:  # pragma: no cover
         return None
     value = match[1]
     if value is None:

src/mkdocs_include_markdown_plugin/event.py

@@ -436,27 +436,30 @@ def found_include_markdown_tag(  # noqa: PLR0912, PLR0915
             offset_match = ARGUMENT_REGEXES['heading-offset']().search(
                 arguments_string,
             )
-            if offset_match:
-                offset_raw_value = offset_match[1]
-                if offset_raw_value == '':
-                    location = process.file_lineno_message(
-                        page_src_path, docs_dir, directive_lineno(),
-                    )
-                    raise PluginError(
-                        "Invalid empty 'heading-offset' argument in"
-                        f" 'include-markdown' directive at {location}",
-                    )
-                try:
-                    offset = int(offset_raw_value)
-                except ValueError:
-                    location = process.file_lineno_message(
-                        page_src_path, docs_dir, directive_lineno(),
-                    )
-                    raise PluginError(
-                        f"Invalid 'heading-offset' argument"
-                        f" '{offset_raw_value}' in 'include-markdown'"
-                        f" directive at {location}",
-                    ) from None
+            try:
+                # Here None[1] would raise a TypeError
+                offset_raw_value = offset_match[1]  # type: ignore
+            except (IndexError, TypeError):  # pragma: no cover
+                offset_raw_value = ''
+            if offset_raw_value == '':
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno(),
+                )
+                raise PluginError(
+                    "Invalid empty 'heading-offset' argument in"
+                    f" 'include-markdown' directive at {location}",
+                )
+            try:
+                offset = int(offset_raw_value)
+            except ValueError:
+                location = process.file_lineno_message(
+                    page_src_path, docs_dir, directive_lineno(),
+                )
+                raise PluginError(
+                    f"Invalid 'heading-offset' argument"
+                    f" '{offset_raw_value}' in 'include-markdown'"
+                    f" directive at {location}",
+                ) from None
 
         bool_options, invalid_bool_args = parse_bool_options(
             [

src/mkdocs_include_markdown_plugin/process.py

@@ -33,7 +33,7 @@
 # previous to Python3.11. Also, these nested brackets can be recursive in the
 # Perl implementation but this doesn't seem possible in Python, the current
 # implementation only reaches two levels.
-MARKDOWN_LINK_REGEX = re.compile(  # noqa: DUO138
+MARKDOWN_LINK_REGEX = re.compile(
     r'''
         (                 # wrap whole match in $1
           (?<!!)          # don't match images - negative lookbehind
@@ -427,17 +427,19 @@ def filter_inclusions(  # noqa: PLR0912
 def _transform_negative_offset_func_factory(
         offset: int,
 ) -> Callable[[str], str]:
-    heading_prefix = '#' * abs(offset)
+    abs_offset = abs(offset)
 
     def transform(line: str) -> str:
         try:
             if line[0] != '#':
                 return line
         except IndexError:  # pragma: no cover
+            # Note for pragma: all lines include a newline
+            # so this exception is never raised in tests.
             return line
-        if line.startswith(heading_prefix):
-            return heading_prefix + line.lstrip('#')
-        return '#' + line.lstrip('#')
+        stripped_line = line.lstrip('#')
+        new_n_headings = max(len(line) - len(stripped_line) - abs_offset, 1)
+        return '#' * new_n_headings + stripped_line
 
     return transform
 
@@ -449,11 +451,11 @@ def _transform_positive_offset_func_factory(
 
     def transform(line: str) -> str:
         try:
-            prefix = line[0]
+            if line[0] != '#':
+                return line
         except IndexError:  # pragma: no cover
             return line
-        else:
-            return heading_prefix + line if prefix == '#' else line
+        return heading_prefix + line
 
     return transform
 

tests/test_unit/test_include_markdown.py

@@ -488,6 +488,26 @@
             [],
             id='heading-offset=-2',
         ),
+        pytest.param(
+            '''# Header
+
+{%
+  include-markdown "{filepath}"
+  heading-offset=-1
+%}
+''',
+            '''#### This should be a third level heading.
+
+Example data''',
+            '''# Header
+
+### This should be a third level heading.
+
+Example data
+''',
+            [],
+            id='heading-offset=-1',
+        ),
 
         # Markdown heading positive offset beyond rational limits
         pytest.param(