Doc optimations

sphinx/conf.py

@@ -17,7 +17,7 @@ author = 'Kevin Veen-Birkenbach'
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-templates_path = ['_templates']
+templates_path = ['templates']
 exclude_patterns = ['docs', 'venv', 'venv/**']
 
 
@@ -26,7 +26,7 @@ exclude_patterns = ['docs', 'venv', 'venv/**']
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinxawesome_theme'
-html_static_path = ['_static']
+html_static_path = ['static']
 
 html_sidebars = {
     '**': [

sphinx/extensions/markdown_include.py

@@ -8,24 +8,24 @@ logger = logging.getLogger(__name__)
 from myst_parser.parsers.sphinx_ import MystParser
 
 class MarkdownIncludeDirective(Directive):
-    required_arguments = 1  # Pfad zur Markdown-Datei
+    required_arguments = 1  # Path to the Markdown file
     optional_arguments = 0
     final_argument_whitespace = True
     has_content = False
 
     def run(self):
-        logger.info("markdown-include-Direktive wird ausgeführt")
+        logger.info("Executing markdown-include directive")
         env = self.state.document.settings.env
-        # Ermittle den absoluten Pfad der Datei.
+        # Determine the absolute path of the file.
         rel_filename, filename = env.relfn2path(self.arguments[0])
-        logger.info("Markdown-Datei: %s", filename)
+        logger.info("Markdown file: %s", filename)
         if not os.path.exists(filename):
             error = self.state_machine.reporter.error(
                 f'File not found: {filename}',
                 nodes.literal_block(self.block_text, self.block_text),
                 line=self.lineno)
             return [error]
-        
+
         try:
             with open(filename, 'r', encoding='utf-8') as f:
                 markdown_content = f.read()
@@ -36,16 +36,43 @@ class MarkdownIncludeDirective(Directive):
                 line=self.lineno)
             return [error]
 
-        # Parse den Markdown-Content mit MystParser.
+        # Parse the Markdown content with MystParser.
         parser = MystParser()
         from docutils.frontend import OptionParser
         from docutils.utils import new_document
         settings = OptionParser(components=(MystParser,)).get_default_values()
-        # Hänge die Sphinx-Umgebung an die Einstellungen an, damit myst_parser funktioniert.
+        # Attach the Sphinx environment to the settings so that myst_parser works.
         settings.env = self.state.document.settings.env
         doc = new_document(filename, settings=settings)
         parser.parse(markdown_content, doc)
-        logger.info("Markdown-Parsing erfolgreich abgeschlossen")
+        logger.info("Markdown parsing completed successfully")
+
+        # Remove the first header (title) if it exists.
+        if doc.children:
+            first_section = doc.children[0]
+            if isinstance(first_section, nodes.section) and first_section.children:
+                first_child = first_section.children[0]
+                if isinstance(first_child, nodes.title):
+                    # If there are additional children, remove the title node.
+                    if len(first_section.children) > 1:
+                        first_section.pop(0)
+                        logger.info("Removed first header from Markdown content")
+                    else:
+                        # If it's the only child, clear its content instead.
+                        first_child.clear()
+                        logger.info("Cleared text of first header from Markdown content")
+            
+            # Unwrap the first section if it no longer has a title.
+            if isinstance(first_section, nodes.section):
+                has_title = any(isinstance(child, nodes.title) and child.astext().strip() 
+                                for child in first_section.children)
+                if not has_title:
+                    # Remove the section wrapper so that its content does not create a TOC entry.
+                    unwrapped = list(first_section.children)
+                    # Replace the first section with its children.
+                    doc.children = unwrapped + doc.children[1:]
+                    logger.info("Unwrapped first section to avoid a TOC entry")
+
         return doc.children
 
 def setup(app):

sphinx/templates/structure.html

@@ -34,11 +34,11 @@
 {% if local_md_headings or local_subfolders %}
 <div class="local-md-headings">
   <h3 class="toctree-l1">Index</h3>
-  {% if local_subfolders %}
-    {{ render_headings(local_subfolders) }}
-  {% endif %}
   {% if local_md_headings %}
     {{ render_headings(local_md_headings) }}
   {% endif %}
+  {% if local_subfolders %}
+    {{ render_headings(local_subfolders) }}
+  {% endif %}
 </div>
 {% endif %}