backstage / backstage/mkdocs-monorepo-plugin

Internal Markdown links in included folder not converted to HTML when pointing outside included folder

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

Description

Your tool is awesome, and thanks for open sourcing it! It solves a very common problem.

I'm using:

mkdocs 1.0.4
mkdocs-monorepo-plugin 0.4.3

I have a pretty basic setup:

- a primary docs folder with a primary mkdocs.yml
- a secondary docs folder with a mkdocs.yml that I'm including in the primary mkdocs.yml

In the secondary docs folder, I have a page where I am trying to create a Markdown link to a page in the primary docs folder. I do so with something like:
`[MyLink](MyLink.md)`
I'm assuming it is possible to get back to the root this way (I have also tried `/MyLink.md`).

However, the resulting link is not correctly being converted to HTML when the site is built. It comes out to be:
`MyLink`

With the .md extension, the link is then not found. For included folders, it seems like the build is not aware when internal links are pointing outside of that included folder. The only way to get around this is using an HTML link.

Thanks much!

Contributor guide

Open the contributing guide

Research direction

Start with the primary and secondary mkdocs.yml files and reproduce the link from the included folder using mkdocs 1.0.4 and mkdocs-monorepo-plugin 0.4.3. Trace how the plugin handles Markdown links that leave the included folder; done means the generated link points to the corresponding HTML page without the .md extension.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.