mkdocs
mkdocs copied to clipboard
Is there a way to support reference link for soft link files
My project already have some documents and README.md files and I would like to reuse them directly. My current folder structure is like below.
├── docs
│ ├── best-practice
│ ├── components
│ │ ├── apiserver.md -> ../../apiserver/README.md
│ │ ├── cli.md -> ../../cli/README.md
│ │ └── operator.md -> ../../ray-operator/README.md
├── ray-operator
│ ├── README.md
│ ├── config
│ │ ├── example.md
As you see, docs/components/operator.md
-> ray-operator/README.md
. However, there's reference used in the ray-operator/README.md
like ./config/example.md
. When I build the mkdoc site, I see warnings like
WARNING - Documentation file 'components/operator.md' contains a link to 'components/config/example.yaml' which is not found in the documentation files.
My question is how to resolve this issue? Is there a way to auto link those files when build the site? The reason I design this way is to make both Github README and Mkdoc work at the same time. I don't want to replicate the files which may leads to inconsistency issue.
You can do that by using the snippets extensions.
Here's an example of a site using just that to re-use the README.md
.
https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/blob/master/docs/index.md
More documentation:
https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files
You can do that by using the snippets extensions.
Thanks @timvink.