Workaround Limitations

[digitaldonkey]

Documentation says "sitename must adhere follow the regular expression: ^[a-zA-Z0-9-/]+$"

My problem with that is that if you also want to single-build the repos you end up with a ugly site_name in the frontend. I wonder if you can introduce a new property like submodule_alias to work around that issue.

You may also autogenerate the machine name (lowercase, replace spaces and strip out special chars) and allow override via custom property. It would improve the "works out of the box" experience and you don't squat site_name prop.

https://github.com/spotify/mkdocs-monorepo-plugin/blob/a252e28a7129010e5e1db05efa08bade3ebb722c/mkdocs_monorepo_plugin/parser.py#L150

https://spotify.github.io/mkdocs-monorepo-plugin/limitations/

[bih]

@digitaldonkey This is something we discussed with the idea that it would change later. The reason why we decided that it should adhere to a specific ruleset is to remove the "magic" and add more predictability.

Another point is explaining to other engineers that your site_name does not exactly correlate with the URL would be confusing and difficult, especially because a "normal" site name could easily make a valid (albeit ugly) URL. An example would be: https://localhost/V1%20Documentation/changelog/ where V1 Documentation would be the site_name.

But maybe there's a middle ground where it isn't too magical and doesn't introduce an easily avoidable limitation. Thoughts?

[dellagustin-sap]

@bih I liked the idea of having introducing a new property like submodule_alias. Could yo comment on that?

[GAS85]

I use my own script to update site_name before to generate documentation. It will search for all !include in root mkdocs.yaml and update them to URL friendly format.