Skip to content
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

Closed
d0ugal opened this issue Jun 7, 2015 · 29 comments
Closed

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

d0ugal opened this issue Jun 7, 2015 · 29 comments
Milestone

Comments

@d0ugal
Copy link
Member

d0ugal commented Jun 7, 2015

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

@d0ugal d0ugal added this to the 1.0.0 milestone Jun 7, 2015
@waylan
Copy link
Member

waylan commented Jun 7, 2015

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
Copy link
Member Author

d0ugal commented Jun 7, 2015

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
Copy link
Member Author

d0ugal commented Jun 7, 2015

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
Copy link
Member

waylan commented Jun 7, 2015

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

@SEJeff
Copy link

SEJeff commented Jun 8, 2015

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
Copy link
Member Author

d0ugal commented Jun 8, 2015

@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
Copy link
Member Author

d0ugal commented Jun 8, 2015

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
Copy link

SEJeff commented Jun 8, 2015

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

SEJeff added a commit to SEJeff/mkdocs that referenced this issue Jun 9, 2015
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
@d0ugal
Copy link
Member Author

d0ugal commented Jun 10, 2015

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.

@tomchristie tomchristie mentioned this issue Jul 10, 2015
15 tasks
@fedotxxl
Copy link

+1 for index_page: README.md

@BrianHicks
Copy link

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

@waylan
Copy link
Member

waylan commented Dec 7, 2015

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
Copy link

machow commented Jan 12, 2016

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

@waylan
Copy link
Member

waylan commented Jan 12, 2016

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

@styfle
Copy link
Contributor

styfle commented Mar 1, 2016

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
Copy link

llonchj commented May 13, 2016

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

@GPMueller
Copy link

@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
Copy link

ppKrauss commented Sep 9, 2017

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
Copy link
Member

waylan commented Sep 10, 2017

@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
Copy link

@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
Copy link
Member

waylan commented Sep 10, 2017

@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
Copy link

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

@valzi
Copy link

valzi commented Jan 20, 2018

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
Copy link

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
Copy link

shacker commented Apr 7, 2018

@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).

@waylan waylan mentioned this issue Jun 8, 2018
@waylan waylan closed this as completed in 34ef3ca Jun 28, 2018
@ve3
Copy link

ve3 commented Dec 7, 2019

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
Copy link
Member

waylan commented Dec 7, 2019

@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
Copy link

ve3 commented Dec 8, 2019

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
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests