Make index.md render like README.md when it's present in a repository
Firstly, this this would help in better maintenance of both /help
and docs.gitlab.com. Now, when the doc site is built,we link to the README.html which feels a little awkward, for example http://docs.gitlab.com/ce/api/README.html.
If we could render index.md
like README.md
then we would have a 2-way profit:
- When visiting https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/api the page would still render the contents of
index.md
- Static generators would create easily
index.html
files from the relevantindex.md
The main point is clean URLs.
The only point we need to pay attention is not to break existing functionality and decide what will be first rendered if both an index.md
and a README.md
are present in a directory.
We no longer allow README.md
s in the docs so that we have clean URLs in the docs site. While this is useful for us, someone that uses the project to quickly visit a document, has to explicitly click on index.md
as it's not automatically rendered by GitLab https://gitlab.com/gitlab-com/gitlab-docs/issues/228#note_111910629.