Merge_root option

docs/reference.md

@@ -121,6 +121,23 @@ By default (like in MkDocs), lists need to be indented by 4 spaces. The more mod
 
 You can change the indentation just for the extension, but that will not affect MkDocs' rendering. If you want to change both at once, install [mdx_truly_sane_lists](https://github.com/radude/mdx_truly_sane_lists) and use it through `markdown_extensions`, instead of this option. See example below.
 
+#### `merge_root`
+
+*boolean, default `false`*
+
+If your root documentation level, should be omitted and instead the navigation be hierarchically merged in order of appearance then set this to true. If no SUMMARY is present then the chapters are merged in order of occurence from the globbing function.
+
+This can be useful in combination with monorepo, multirep or similar setups when you want chapters on root-level that several repos / root folders contribute too.
+
+!!! example "SUMMARY.yml"
+    Please note in this example no title is specified as root titles are discard, and instead subfolders merged when option is active.
+
+    ```markdown
+    - Repo_1*/
+    - Repo_2*/
+    - Repo_3*/
+    ```
+
 #### `markdown_extensions`
 
 *list of mappings, [same as MkDocs](https://www.mkdocs.org/user-guide/configuration/#markdown_extensions)*

mkdocs_literate_nav/plugin.py

@@ -14,6 +14,7 @@
 import mkdocs.structure.files
 import mkdocs.structure.nav
 import mkdocs.structure.pages
+import copy
 
 try:
     from mkdocs.plugins import event_priority
@@ -29,6 +30,7 @@
 class _PluginConfig:
     nav_file = mkdocs.config.config_options.Type(str, default="SUMMARY.md")
     implicit_index = mkdocs.config.config_options.Type(bool, default=False)
+    merge_root = mkdocs.config.config_options.Type(bool, default=False)
     markdown_extensions = mkdocs.config.config_options.MarkdownExtensions()
     tab_length = mkdocs.config.config_options.Type(int, default=4)
 
@@ -47,6 +49,7 @@ def on_files(self, files: mkdocs.structure.files.Files, config: mkdocs.config.Co
             files,
             nav_file_name=self.config["nav_file"],
             implicit_index=self.config["implicit_index"],
+            merge_root=self.config["merge_root"],
             markdown_config=dict(
                 extensions=self.config["markdown_extensions"],
                 extension_configs=self.config["mdx_configs"],
@@ -68,11 +71,49 @@ def on_nav(
             )
 
 
+def find_nav_match(key, nav):
+    """Find first match on current navigation hierarchy level.
+    """
+    if key is not None:
+        if isinstance(nav, list):
+            for oitem in nav:
+                if isinstance(oitem, dict):
+                    for okey, ovalue in oitem.items():
+                        if key == okey:
+                            return ovalue
+    return None
+
+
+def merge_nav(in_nav, out_nav):
+    """Merge one navigation into another, the order is important as navigation order depends on it.
+    """
+    if isinstance(in_nav, dict):
+        in_nav = [in_nav]
+
+    for item in in_nav:
+        if isinstance(item, dict):
+            for key, value in item.items():
+                datav = copy.deepcopy(value)
+
+                output_list = find_nav_match(key, out_nav)
+                if output_list is None:
+                    out_nav.append({key: datav})
+                elif isinstance(output_list, list) and isinstance(datav, list):
+                    merge_nav(datav, output_list)
+        else: # index handling
+            if len(out_nav) > 0 and isinstance(out_nav[0], dict):
+                # insert index in front if no index present yet
+                out_nav.insert(0, item)
+            else:
+                out_nav.append(item)
+
+
 def resolve_directories_in_nav(
     nav_data,
     files: mkdocs.structure.files.Files,
     nav_file_name: str,
     implicit_index: bool,
+    merge_root: bool,
     markdown_config: dict | None = None,
 ):
     """Walk through a standard MkDocs nav config and replace `directory/` references.
@@ -106,7 +147,16 @@ def get_nav_for_dir(path: str) -> tuple[str, str] | None:
         result = nav_parser.markdown_to_nav()
     if not result:
         result = nav_parser.resolve_yaml_nav(nav_data)
-    return result or []
+
+    if not merge_root:
+        return result or []
+
+    # merge root hierarchically?
+    merged_result = []
+    for data in result:
+        merge_nav(list(data.values())[0], merged_result)
+
+    return merged_result or []
 
 
 class MkDocsGlobber: