backstage / backstage/mkdocs-monorepo-plugin

Unable to use includes

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.