Repository: mondeja/mkdocs-include-markdown-plugin (python)

Issue:
Feature Request: Add option to offset headings
I would like to ability to offset the headings inside a markdown file I import. I have a Markdown file that can both standalone and be imported into another file.  

This could be an option available for every import.

{%
    include-markdown "docs/test.md"
    heading-offset=1
%}

Pull request:
Add support to Offset Markdown headings.
Fixes #45

This PR adds a new option for include-markdown to have headings depth from included files to have 1-5 number of levels.  0 is the default offset.

heading-offset=1

Would look like the following:

File to import:
'''# Test Header

Example Test
'''

Rendered:
'''## Test Header

Example Test
'''




Patch:
diff --git a/README.md b/README.md
index 8233cb3..8ee3c14 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,8 @@ content to include.
  include is wrapped by `<!-- BEGIN INCLUDE -->` and `<!-- END INCLUDE -->`
  comments which help to identify that the content has been included. Possible
  values are `true` and `false`.
+- **heading-offset** (0): Increases the Markdown heading depth by this number.
+ Only supports number sign (#) heading syntax. Max offset of 5.
 
 > Note that the **start** and **end** strings may contain usual (Python-style)
 escape sequences like `\n`, which is handy if you need to match on a multi-line
@@ -76,6 +78,13 @@ start or end trigger.
 %}
 ```
 
+```jinja
+{%
+   include-markdown "docs/includes/header.md"
+   heading-offset=1
+%}
+```
+
 #### **`include`**
 
 Includes the content of a file.
diff --git a/mkdocs_include_markdown_plugin/event.py b/mkdocs_include_markdown_plugin/event.py
index 61f7fe6..82d192c 100644
--- a/mkdocs_include_markdown_plugin/event.py
+++ b/mkdocs_include_markdown_plugin/event.py
@@ -51,6 +51,7 @@ ARGUMENT_REGEXES = {
     'comments': re.compile(r'comments=(\w*)'),
     'preserve_includer_indent': re.compile(r'preserve_includer_indent=(\w*)'),
     'dedent': re.compile(r'dedent=(\w*)'),
+    'heading-offset': re.compile(r'heading-offset=([0-5])'),
 }
 
 
@@ -221,6 +222,21 @@ def get_file_content(markdown, abs_src_path):
         if new_text_to_include != text_to_include:
             text_to_include = new_text_to_include
 
+        # heading offset
+        offset_match = re.search(
+            ARGUMENT_REGEXES['heading-offset'],
+            arguments_string,
+        )
+        if offset_match:
+            offset = int(offset_match.group(1))
+            lines = []
+            for line in text_to_include.splitlines(keepends=True):
+                if line.startswith('#'):
+                    lines.append('#' * offset + line)
+                else:
+                    lines.append(line)
+            text_to_include = ''.join(lines)
+
         if not bool_options['comments']['value']:
             return text_to_include
 


Test patch:
diff --git a/tests/test_include_markdown.py b/tests/test_include_markdown.py
index f5d9eca..d188bbb 100644
--- a/tests/test_include_markdown.py
+++ b/tests/test_include_markdown.py
@@ -242,6 +242,111 @@ This must be included.
     - Foo
     - Bar
         - Baz
+''',
+        ),
+
+        # Markdown heading offset 1
+        (
+            '''# Header
+
+{%
+  include-markdown "{filepath}"
+  heading-offset=1
+%}
+''',
+            '''# This should be a second level heading.
+
+Example data''',
+            '''# Header
+
+<!-- BEGIN INCLUDE {filepath}   -->
+## This should be a second level heading.
+
+Example data
+<!-- END INCLUDE -->
+''',
+        ),
+        # Markdown heading offset 2
+        (
+            '''# Header
+
+{%
+  include-markdown "{filepath}"
+  heading-offset=2
+%}
+''',
+            '''# This should be a third level heading.
+
+Example data''',
+            '''# Header
+
+<!-- BEGIN INCLUDE {filepath}   -->
+### This should be a third level heading.
+
+Example data
+<!-- END INCLUDE -->
+''',
+        ),
+        # Markdown heading no offset
+        (
+            '''# Header
+
+{%
+  include-markdown "{filepath}"
+%}
+''',
+            '''# This should be a first level heading.
+
+Example data''',
+            '''# Header
+
+<!-- BEGIN INCLUDE {filepath}   -->
+# This should be a first level heading.
+
+Example data
+<!-- END INCLUDE -->
+''',
+        ),
+        # Markdown heading zero offset
+        (
+            '''# Header
+
+{%
+  include-markdown "{filepath}"
+  heading-offset=0
+%}
+''',
+            '''# This should be a first level heading.
+
+Example data''',
+            '''# Header
+
+<!-- BEGIN INCLUDE {filepath}   -->
+# This should be a first level heading.
+
+Example data
+<!-- END INCLUDE -->
+''',
+        ),
+        # Markdown heading offset string
+        (
+            '''# Header
+
+{%
+  include-markdown "{filepath}"
+  heading-offset=true
+%}
+''',
+            '''# This should be a first level heading.
+
+Example data''',
+            '''# Header
+
+<!-- BEGIN INCLUDE {filepath}   -->
+# This should be a first level heading.
+
+Example data
+<!-- END INCLUDE -->
 ''',
         ),
     ),