Allow non-index.md files to be used as the homepage

[d0ugal]

ReadTheDocs allows README.md files, GitHub also renders those as the root. We should support that and/or a way for users to pick.

[waylan]

While I understand the desire not to duplicate information, I'm having trouble understanding how this would work. In my projects the README.md file is in the same dir as mkdocs.yml. However, the homepage would be at docs/index.md. Right now anyone using non-windows systems could potentially use a symbolic link for one of them, but that is not cross-platform and may not always work with version control systems, so it's not really a tenable solution. Would there be some setting which points to the README which effectively says "use this file instead of docs/index.md"? But what would the path be relative to?

[d0ugal]

Quite often people name the root document docs/README.md - one advantage is that GitHub renders that and can make the documentation browsable, assuming you link well enough from that page. I'm not sure if there are any other advantages.

[d0ugal]

This is the example I seen today while replying to an post on the mailing list. https://github.com/apache/aurora/tree/master/docs

[waylan]

Ah, got it. I hadn't considered that. Thanks.

[SEJeff]

Instead of hardcoding either index.md or README.md, why not simply keep the existing code and add a config option like index_page or something:

This seems totally reasonable to me and could be added to the existing documentation prominently:

index_page: README.md

Surely this can't be that hard to do? I might be willing to take a stab at it as I'd really like to move the Aurora docs over towards using mkdocs if possible. To get buy-in on that from the core team / committers would require this feature.

Oh and for reference, check this mkdocs theme out which perfectly replicates the upstream documentation site rendered using the ruby tool middleman.

[d0ugal]

@SEJeff You are right, it really wouldn't be that hard technically to implement. However, I am on a constant mission to keep the number of configuration options as low as possible. I think that is a reasonable addition however, I just want to carefully consider it.

One alternative would be to automatically try a few names in order, for example, index.md then README.md then home.md.

Oh and for reference, check this mkdocs theme out which perfectly replicates the upstream documentation site rendered using the ruby tool middleman.

Nice! Looks like that is shaping up well.

[d0ugal]

For reference, ReadTheDocs look for an index.md file and then try README.md if it can't be found. https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/base.py#L89-L103

[SEJeff]

If that's what you'd prefer, it totally works for me.

[d0ugal]

Thinking about this a bit more, there are really two cases we need to cover.

• If the user doesn't manually provide a pages config, we should make the index.md the index if it exists, if it doesn't try README.md and if neither are found display an error.
• If the user does define the full pages structure, we should take the first one and make that the homepage regardless of what the files are called.