markdown links broke from README.md outside of docs folder

[my3sons]

Hello, we have some existing github repos that contain markdown documentation that we want to keep as is and also move to Backstage. To keep things simple, I am using a contrived example here that represents the issue we are facing with links in our markdown. This is the structure of our repos:

.
├── README.md
├── docs
│   ├── how-to
│   │   ├── example1.md
│   │   └── example2.md
│   └── index.md
└── mkdocs.yml

We want our mkdocs site to use the README.md as its root index.html and here is the content of the README.md:

# mkdocs-example

* [docs/how-to](./docs/how-to/)
  * [example1](./docs/how-to/example1.md)
  * [example2](./docs/how-to/example2.md)

and in the ./docs/index.md, we have this:

--8<-- "README.md"

Lastly, here is our mkdocs.yml file:

site_name: Repair Workshop
site_dir: site

nav:
  - Home: index.md

use_directory_urls: true 

markdown_extensions:
  - pymdownx.snippets:
      check_paths: true

When we run mkdocs build everything builds fine and we get the below structure in our site folder.

.
├── 404.html
├── css
│   ├── base.css
│   ├── bootstrap.min.css
│   └── font-awesome.min.css
├── fonts
│   ├── fontawesome-webfont.eot
│   ├── fontawesome-webfont.svg
│   ├── fontawesome-webfont.ttf
│   ├── fontawesome-webfont.woff
│   └── fontawesome-webfont.woff2
├── how-to
│   ├── example1
│   │   └── index.html
│   └── example2
│       └── index.html
├── img
│   ├── favicon.ico
│   └── grid.png
├── index.html
├── js
│   ├── base.js
│   ├── bootstrap.min.js
│   └── jquery-3.6.0.min.js
├── search
│   ├── lunr.js
│   ├── main.js
│   ├── search_index.json
│   └── worker.js
├── sitemap.xml
└── sitemap.xml.gz

The index.html at the root does in fact reference our README.md so we know the pymdown snippet is working. However, because mkdocs flattens the docs folder and just leaves "how-to", all our links in the root index.html are broken because the hyperlink path includes the "docs" folder in it.

I know this is not necessarily a pymdown snippet issue because it is not going to change the links in the README.md, but this overall scenario seems like the classic case for using the pymdown snippet to begin with (when you want mkdocs to use a index.md/README.md outside the docs folder. I tried various configuration options in both mkdocs and pymdown but I could never get it to work end-to-end. I know that I could change the links or copy things around, but then everything will break in github and developers won't be able to walk the documentation there. Is there not a way for me to have my cake and eat it too with this, meaning I can walk the documentation in github and from a mkdocs published site?

[facelessuser]

Snippets is just a dumb content inserter and has no knowledge of your documentation structure, nor does it have the ability to know where in that structure you've inserted that content. Only at the MkDocs level would such knowledge be known.

There are probably two ways you could handle this.

1. In you readme, give direct links to the deployed locations you can find the links in the readme; therefore it would be correct as a GitHub landing page and as a documentation page.

2. Create a simple MkDocs plugin that intercepts the initial index.html page (where the readme is inserted) and programmatically rewrite the links so that as a github landing page, the links make sense, and when inserted into documentation, the links are augmented properly.

[my3sons]

thanks Isaac, will give those suggestions a try!