backstage / backstage/mkdocs-monorepo-plugin

Better support with `macros` plugin to override `extras`

Open
#130 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Python
Stars
400
Forks
80
PR merge metrics
No merged PRs in 30d

Description

I'm not sure if I should ask this here, or at the `macros` repository.

Consider the following setup:
```yaml
# /mkdocs.yml
site_name: Cats API

nav:
- Intro: 'index.md'
- Authentication: 'authentication.md'
- API:
- v1: '!include ./v1/mkdocs.yml'
- v2: '!include ./v2/mkdocs.yml'

plugins:
- monorepo

extras:
version: v2 # default
```

```yaml
# /src/v1/mkdocs.yml
site_name: versions/v1

nav:
- Reference: "reference.md"
- Changelog: "changelog.md"

extras:
version: v1
```

```yaml
# /src/v2/mkdocs.yml
site_name: versions/v2

nav:
- Migrating to v2: "migrating.md"
- Reference: "reference.md"
- Changelog: "changelog.md"
```

I would love to have the version variable be overridden by the v1 in the earlier version, but it looks like the included extras are not evaluated.

Contributor guide

Open the contributing guide

Research direction

Start with the root mkdocs.yml and the included src/v1/mkdocs.yml and src/v2/mkdocs.yml to understand how the monorepo plugin processes included configuration and extras. Verify the desired behavior by checking that v1 resolves version as v1 while the root and v2 retain the default v2 value.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.