README vs docs/index.md
I saw that README.md was copied to docs/index.md, so it could appear in the docs. Later, the inevitable happened, and one of the two got edited, the other one not. I would like to delete one of the two, so this could not happen again. It seems not possible though, to make mkdocs use the main README.md of the repo, because when I try this in mkdocs.yml:
docs_dir: .
I get:
ERROR - Config value: 'docs_dir'. Error: The 'docs_dir' should not be the parent directory of the config file. Use a child directory instead so that the 'docs_dir' is a sibling of the config file.
Which is a shame, because that is how static site generators work by default, so mkdocs is not compatible with the default.
The second best idea I have, is to not use mkdocs directly, but use a script that auto-copies README.md to docs/index.md and then runs mkdocs.
The third option is, to use the mkdocs simple plugin, which makes mkdocs use the repo-root as the docs root (which I think is a better idea anyway, as the whole repo is a/the documentation). I tried that, and it works, except that it makes the "git-revision-date-localized-plugin" fail. That one would probably need bug-fixing. It should not be too hard but.. I have enough of this by now. ;-) maybe some other day.
In the long run, I would recommend using an other static site generator then mkdocs.