Include documents from relative paths on the built site

[julioz]

Hi, thanks for the great tool, we are very happy with it at SoundCloud.

One of our codebases is a multi-module project, each owned by different teams and with different sub-structures. One android app is built from the combination of all sources, and in a similar fashion, we provide an internal documentation website using mkdocs for the entire development team.

One of the limitations we see so far, though, is including markdown files that aren't under the docs directory under our root. Some teams prefer to have README files or other pieces of documentation side-by-side with the code under each module, take a look at the example directory structure (starting from the root dir):

- mkdocs.yml
- docs/
  - onboarding/
    - file1.md
    - file2.md
  - releasing/
  - testing/
- libs/
  - networking/
    - README.md
    - docs/
      - apiclient.md
      - caching.md
  - analytics/
- ...

So far, all of the files under the docs directory in the root are included in the built website, but we would also like to have another section for the documents under each module. In the example above, we would like a "networking" section with the md files under its docs directory (namely apiclient.md and caching.md).

We explored using the nav configuration setting but since it only considers paths under docs_dir, we cannot express a navigation like:

nav:
    - 'Networking': '../libs/networking/README.md'

I see a printed log line with

WARNING -  A relative path to '../libs/networking/README.md' is included in the 'nav' configuration, which is not found in the documentation files

We could have separate built websites, and link between them, but ideally we would rather have a single deployment with all aggregated documentation.

Is this possible? Or maybe I am doing something wrong?

[martinbira]

Perhaps this could be of use: https://labs.spotify.com/2019/10/01/solving-documentation-for-monoliths-and-monorepos/

[waylan]

@julioz this is something that can be addressed by a plugin. I don't recall but there may be an existing third party plugin which already offers such a feature. Regardless, this is not a feature we will be adding to mkdocs directly.

[julioz]

@martinbira @waylan Thank you both. I wasn't aware, but maybe monorepo can help with what we want to achieve, I'll give it a try and report back to them in case I find need for extension.