Feature Request: multiple root directories

[rplotkin]

awesome-pages is... awesome. But it cannot be successfully used with monorepo and multirepo plugins (and monorepos/multirepos are challenging to manage without those plugins). I decided to bail on the mono/multi-repo plugins and figure out how to make my multiple monorepos (yup, both) work, in the aggregate, with awesome-pages. Turns out that it only took a small shell script to move some files around into the "docs" directory.

And so, with that realization, I can also say that awesome-pages could be altered to work for mono/multi-repos by supporting more path options. The plugin currently only descends into docs_dir, but if .pages could add an option to look in other dirs (and maybe even support deeper paths, e.g. my_dir/nested_dir and not just my_dir), it would work for users handling mono/multi-repos (and, I believe, would also allow people using those other plugins to either ditch them or configure them to allow awesome-pages to work).

[lacyllana-zb]

I'd like to second this feature request, as well as ask @rplotkin if he would be willing to share more on his workaround, because we are running into exactly the same issue. 😄

[taylanisikdemir]

This is also something we need for our monorepo. Bringing all markdowns to "docs" folder is not desirable because

• we want documentation to live closer to code
• we want CODEOWNERs to continue to work

Are there any plans to support including files from any folder in the repo?

[Vaelor]

I have a similar need for my documentation.

We have multiple projects (different git repositories) and we want the documentation to be versioned with the project code. I am using mkdocs with the multirepo plugin and awesome-pages (this is so much better then the regular nav btw thanks a lot!).

Out of the box, these plugins didn't play well together and I dug around a bit. The main issues I encountered was that awesome-pages doesn't look into the directory temp_dir which multirepo uses to checkout other the documentations. This is my first time working with mkdocs, so I am kinda stumbling around and poking here and there and see what happens, so I assume my solution is probably very flawed. But, as a quick workaround I did the following:

diff --git a/mkdocs_awesome_pages_plugin/navigation.py b/mkdocs_awesome_pages_plugin/navigation.py
index deeb354..72d72dd 100644
--- a/mkdocs_awesome_pages_plugin/navigation.py
+++ b/mkdocs_awesome_pages_plugin/navigation.py
@@ -219,6 +219,10 @@ class NavigationMeta:
             if isinstance(item, Page):
                 if Path(self.docs_dir) in Path(item.file.abs_src_path).parents:
                     paths.append(item.file.abs_src_path)
+                elif self.options.additional_dirs:
+                    for d in self.options.additional_dirs:
+                        if Path(self.docs_dir).parent / d in Path(item.file.abs_src_path).parents:
+                            paths.append(item.file.abs_src_path)
             elif isinstance(item, Section):
                 section_dir = self._gather_metadata(item.children)
                 if item in self.explicit_sections:
diff --git a/mkdocs_awesome_pages_plugin/options.py b/mkdocs_awesome_pages_plugin/options.py
index 5b72945..c5592dd 100644
--- a/mkdocs_awesome_pages_plugin/options.py
+++ b/mkdocs_awesome_pages_plugin/options.py
@@ -1,5 +1,6 @@
 class Options:
-    def __init__(self, *, filename: str, collapse_single_pages: bool, strict: bool):
+    def __init__(self, *, filename: str, collapse_single_pages: bool, strict: bool, additional_dirs: list):
         self.filename = filename
         self.collapse_single_pages = collapse_single_pages
         self.strict = strict
+        self.additional_dirs = additional_dirs
diff --git a/mkdocs_awesome_pages_plugin/plugin.py b/mkdocs_awesome_pages_plugin/plugin.py
index d5c932c..c582c83 100644
--- a/mkdocs_awesome_pages_plugin/plugin.py
+++ b/mkdocs_awesome_pages_plugin/plugin.py
@@ -36,6 +36,7 @@ class AwesomePagesPlugin(BasePlugin):
         ("filename", config_options.Type(str, default=DEFAULT_META_FILENAME)),
         ("collapse_single_pages", config_options.Type(bool, default=False)),
         ("strict", config_options.Type(bool, default=True)),
+        ("additional_dirs", config_options.Type(list, default=[])),
     )

     def __init__(self):

This allowed me to add a config option, additional_dirs - and the documentation works! :) Well kind of. There is another issue, but I assume is with multirepos - the root .pages file from the import docs is missing. I fixed this by renaming the .pages files to pages. Just mentioning if anyone stumbles over this thing and happens to have the same problem.

So yeah, not sure if anyone finds this interesting/useful here with the same issue. Not perfect, but works if needed, at least as far as I can tell.