backstage / backstage/mkdocs-monorepo-plugin
Feature Request: Generate sites based on nav hierarchy instead of site_name
- Dominant language
- Python
- Stars
- 400
- Forks
- 80
- PR merge metrics
- No merged PRs in 30d
Description
**Current Behavior:**
Currently the mkdocs-monorepo-plugin generates the page based on `site_name` for each subrepos. This means that there is a strong coupling between the `site_name` and the url of the built docs.
**Problems Related:**
In case of the documentation owner wants to move a subrepo's documentation into another path, one should consult the subrepo owner to update the `site_name`, which reduces development efficiency.
Furthermore, due to the coupling between `site_name` and the generated path, one should set a url path as the `site_name` of the subrepo to retain the web semantic of the documentations. Thus, there's aesthetic concern when the subrepo's mkdocs built separately for internal purpose as the title now becomes a url path instead of a meaningful name.
**Desired Behavior:**
By default the generated documentations respect the hierarchy during the build, and making the coupling between the `site_name` and path as optional, e.g. specifying in the `extra` map inside the subrepo's `mkdocs.yml`
Contributor guide
Research direction
The issue names no files, tests, or entry points. Start by locating where subrepository site_name values become generated paths, then clarify the nav-hierarchy default and the extra-map option. Done means generated documentation follows the hierarchy by default while retaining an explicit way to couple paths to site_name.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100