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.

[fedotxxl]

+1 for index_page: README.md

[BrianHicks]

Is this in a released version? I'd really like to use it as well.

[waylan]

This issue is still open as it hasn't been added at all. I'm sure a pull request implementing it would be welcome.

[machow]

+1, I've run into the same problem. Do you think the implementation should start from the refactoring branch or master?

[waylan]

My understanding is that the refactoring branch is both incomplete and out-of-date. I'd work from master.

[styfle]

I think this feature makes sense since we have all come to recognize readme.md as the starting point when sifting through markdown files.

May I make a suggestion that will get the same behavior as readthedocs? Use an array.

IIS on windows does something similar for default files and lets the user chose the order such as [default.asp,default.aspx,index.htm,index.html]

So the config value could have the following default value and still be configurable:

index_page: [index.md, readme.md]

[llonchj]

+1 for index_page: Home.md
Will be helpful with GitLab wikis

[GPMueller]

@waylan

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?

How about relative to docs_dir? It might also be nice to be able to actually specify the top-level Readme of a repo as index_page.

[ppKrauss]

Hi @GPMueller, @llonchj , @fedotxxl, @waylan ... Perhaps the easiest way is to express the external files (any that is not into /docs) at mkdocs.yml, and the mkdocs-software validating relative paths, example:

pages:
    - Home: ../README.md
    - Topic1: topic1.md
    - Topic2: ../repoTopic/README.md

[waylan]

@ppKrauss this issue is about converting README.md => index.html without changing location. Basically, when no index.md is found within a dir within the docs_dir, but README.md is found, then README.md is used and treated as if it was index.md. Using a file from a different location is an entirely different issue which should be addressed via symbolic links.

[ppKrauss]

@waylan I have no good experience with symbolic links when working with git clone... This is the main cenario, all the contents in a git repo. See eg. this readme, this other and this other one, all in folder or subfolder structures of a repo.... Not make sense, for me, an "working overhead" for user, making and controling symbolic links.

I not understand the problem with relative paths with ../
perhaps an option in mkdocs or config, to enable/disable "external files from doc_dir" (default as disable no problem).

[waylan]

@ppKrauss as I stated previously, that is a different issue than is being discussed here. Please keep the discussion here to the relevant issue of using a README file as an index file.

[ppKrauss]

Hi @waylan , please reopen #1279 to discuss this global solution.

[valzi]

Has this been implemented yet? I hate having to keep my file named index.md. I regularly export it to PDF and have to rename the pdf file every time.

[ppKrauss]

PS: this issue is "about converting README.md => index.html without changing location"... But I think that not make sense when I say - Home: ../README.md at mkdocs.yml (!).
There are a precedence order, and is natural to suppose mkdocs.yml on the top:

1. Use as global index.html what mkdocs.yml say to use as Home.
2. Use as global index.html the root's README.md.
3. Use as global index.html the root's index.md.

[shacker]

@d0ugal (2015):

For reference, ReadTheDocs look for an index.md file and then try README.md if it can't be found.

That is not what I experienced today. When I built the project from github with only a README.md, then followed the link provided by RTD, I got a 404. I then renamed the doc to index.md and rebuilt, and it worked (but of course that leaves my github repo without a displayed readme).

[ve3]

I see that this issue is closed but still cannot found how to change index page to something that is not index.md, readme.md.

[waylan]

@ve3 We closed this when we added support for readme.md. We have no intention of supporting any other file names as index pages.

[ve3]

I see @d0ugal mentioned about home.md too this file is created and use in GitHub Wiki page.
It would be good if mkdocs support it. :)

[alcorwalter]

I don't understand this choice as Mkdocs is structure/file based.
My documentations deserve better structure readability. If you have to maintain many collaborative documentations, it's impossible to guess the content of files named "index.md" or "readme.md". I would find it really useful to have a contextual/user-defined name for the first/default page.