backstage / backstage/mkdocs-monorepo-plugin
Unable to use includes
- Dominant language
- Python
- Stars
- 400
- Forks
- 80
- PR merge metrics
- No merged PRs in 30d
Description
On child projects we use includes for files that need to be at project root, like `README.md` or `CHANGELOG.md` and this is achieved using
```md
{!../CHANGELOG.md!}
```
```yaml
# child mkdocs.yml file
plugins:
- markdown_include.include:
base_path: docs
```
While this works when building docs of each child-site, it does not work with monorepo plugin.
I mention that our initial attempt was to use symlinks from docs/ to parent but that does not work with mkdocs either, being forced to use the include method. Also creating symlinks from root to docs/ folder does not work because github does not display these markdown files correctly.
Related: https://github.com/cmacmackin/markdown-include/issues/41
Contributor guide
Research direction
Reproduce the include example with docs/changelog.md and the child mkdocs.yml configuration, comparing a standalone child-site build with a monorepo build. Start by tracing how the monorepo plugin handles each documentation folder and how markdown-include resolves base_path; done means root-level README.md and CHANGELOG.md render correctly in the monorepo build.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100