backstage / backstage/mkdocs-monorepo-plugin

Feature Request: Generate sites based on nav hierarchy instead of site_name

Open
#142 0 comments 2 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.