backstage / mkdocs-monorepo-plugin

✚ Build multiple documentation folders in a single Mkdocs. Designed for large codebases.
https://backstage.github.io/mkdocs-monorepo-plugin/
Apache License 2.0
314 stars 75 forks source link

Suggestion: Allow any config file name #36

Closed wilhelmer closed 3 years ago

wilhelmer commented 3 years ago

Currently, monorepo only supports including MkDocs config files that are named exactly mkdocs.yml.

However, it can be useful to have multiple config files, especially when working with projects that are built both individually and as part of a multirepo. In this case, the default "standalone" config file would ideally be named mkdocs.yml, and the monorepo version would have a different name, e.g., mkdocs-monorepo.yml.

So I suggest to get rid of this limitation and support any *.yml file. I think this could be achieved quite easily:

  1. Adapt the regex that matches the config file name: https://github.com/backstage/mkdocs-monorepo-plugin/blob/bbe9ddab8192fa5e49c0cc82901ef850a045bf79/mkdocs_monorepo_plugin/parser.py#L59

    rootDir, re.sub(r'(.*)\/.*\.yml$', r'\1', path, re.IGNORECASE)))
  2. Adapt read(): https://github.com/backstage/mkdocs-monorepo-plugin/blob/bbe9ddab8192fa5e49c0cc82901ef850a045bf79/mkdocs_monorepo_plugin/parser.py#L124

if not self.absNavPath.endswith(".yml"):

Any thoughts? Should I submit a PR for this?

OrkoHunter commented 3 years ago

Thanks for reporting! Is it possible to tell the plugin in anyway that the config file is called something else than mkdocs.yml?

Regex way sounds good, although I think we should ensure match with something like this - *mkdocs*.yml so that non-mkdocs yaml files are not matched. I am not too familiar with how this plugin is implemented, but I'm happy to accept any PR if it's helpful.

wilhelmer commented 3 years ago

Thanks for reporting! Is it possible to tell the plugin in anyway that the config file is called something else than mkdocs.yml?

Currently, you can (and must) define where the mkdocs.yml is located, but not how it is called.

- Subproject: '!include ./my_sub_dir/mkdocs.yml'

my_sub_dir can be anything, but mkdocs.yml must be exactly that or the build process will fail.

Regex way sounds good, although I think we should ensure match with something like this - *mkdocs*.yml so that non-mkdocs yaml files are not matched. I am not too familiar with how this plugin is implemented, but I'm happy to accept any PR if it's helpful.

I don't think this is necessary since you'll still provide the full file path and name as outlined above. So files can't be mixed up.

I'll provide a PR.