New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Allow non-index.md files to be used as the homepage #608
Comments
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? |
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. |
This is the example I seen today while replying to an post on the mailing list. https://github.com/apache/aurora/tree/master/docs |
Ah, got it. I hadn't considered that. Thanks. |
Instead of hardcoding either 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. |
@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,
Nice! Looks like that is shaping up well. |
For reference, ReadTheDocs look for an |
If that's what you'd prefer, it totally works for me. |
If index.md exists, it will be preferenced over README.md, to match the featureset of [readthedocs](https://github.com/rtfd/readthedocs.org/blob/347104f25c82bba0c42029a2226cbbb71a0bf627/readthedocs/doc_builder/base.py#L89-L103) as the index page. Fixes mkdocs#608
Thinking about this a bit more, there are really two cases we need to cover.
|
+1 for |
Is this in a released version? I'd really like to use it as well. |
This issue is still open as it hasn't been added at all. I'm sure a pull request implementing it would be welcome. |
+1, I've run into the same problem. Do you think the implementation should start from the refactoring branch or master? |
My understanding is that the refactoring branch is both incomplete and out-of-date. I'd work from master. |
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 So the config value could have the following default value and still be configurable: index_page: [index.md, readme.md] |
+1 for index_page: Home.md |
How about relative to |
Hi @GPMueller, @llonchj , @fedotxxl, @waylan ... Perhaps the easiest way is to express the external files (any that is not into pages:
- Home: ../README.md
- Topic1: topic1.md
- Topic2: ../repoTopic/README.md |
@ppKrauss this issue is about converting |
@waylan I have no good experience with symbolic links when working with I not understand the problem with relative paths with |
@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. |
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. |
PS: this issue is "about converting
|
@d0ugal (2015):
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). |
I see that this issue is closed but still cannot found how to change index page to something that is not |
@ve3 We closed this when we added support for |
I see @d0ugal mentioned about home.md too this file is created and use in GitHub Wiki page. |
I don't understand this choice as Mkdocs is structure/file based. |
ReadTheDocs allows README.md files, GitHub also renders those as the root. We should support that and/or a way for users to pick.
The text was updated successfully, but these errors were encountered: