Same file index.md and README.md

[agile ginkgo]

Hey team,

I'm running into an issue with our Backstage tech docs setup. Here's the situation:

Our documentation is stored in the docs folder.
This docs folder contains an index.md file.
All documentation files are within this docs folder.
However, our GitLab README.md is at the root of the project.
The problem is that this setup duplicates content between the README.md for GitLab and the index.md for TechDocs. I'm looking for a way to consolidate this into a single file that can serve both purposes.

TechDocs in Backstage uses MkDocs, so I'm wondering if there's a way to configure MkDocs or Backstage to use the README.md from the root directory as the index.md for the docs folder.

Does anyone have experience with this or any suggestions on how to resolve this duplication issue?

Thanks!

[dusty latch]

👋

If you're building your docs with the techdocs-cli, you can use --legacyCopyReadmeMdToIndexMd.

If not, we use the include-markdown Mkdocs plugin, which is a little bit more powerful.

[agile ginkgo]

hello, yes include can be a good solution but after with this plugin we can have problem with relative links between README.md at root and the index.md in the docs folder

[dusty latch]

I'm surprised, as the plugin defaults to rewrite-relative-urls

[wispy meadow]

We use a symlink in the docs/index.md e.g.

{% include "../README.md" %}

and the mkdocs-include plugin

overlooked @dusty latch's comment, sorry for duplicate

[agile ginkgo]

oooooh this is interesting thx