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 · 25 comments

Comments

Projects
@d0ugal
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 the Enhancement label Jun 7, 2015

@d0ugal d0ugal added this to the 1.0.0 milestone Jun 7, 2015

@waylan

This comment has been minimized.

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

This comment has been minimized.

Member

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

This comment has been minimized.

Member

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

This comment has been minimized.

Member

waylan commented Jun 7, 2015

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

@SEJeff

This comment has been minimized.

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

This comment has been minimized.

Member

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

This comment has been minimized.

Member

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

This comment has been minimized.

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

Allow README.md to be used as the index page
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

This comment has been minimized.

Member

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 referenced this issue Jul 10, 2015

Closed

Internal refactoring. #689

1 of 15 tasks complete
@fedotxxl

This comment has been minimized.

fedotxxl commented Aug 14, 2015

+1 for index_page: README.md

@BrianHicks

This comment has been minimized.

BrianHicks commented Dec 7, 2015

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

@waylan

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

llonchj commented May 13, 2016

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

@GPMueller

This comment has been minimized.

GPMueller commented Jul 14, 2017

@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

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

ppKrauss commented Sep 10, 2017

@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

This comment has been minimized.

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

This comment has been minimized.

ppKrauss commented Sep 10, 2017

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

@valzi

This comment has been minimized.

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

This comment has been minimized.

ppKrauss commented Jan 20, 2018

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.

@waylan waylan added this to To do in Pages Refactor Feb 5, 2018

@shacker

This comment has been minimized.

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 moved this from To do to In progress in Pages Refactor Jun 3, 2018

@waylan waylan moved this from In progress to To do in Pages Refactor Jun 3, 2018

@waylan waylan moved this from To do to In progress in Pages Refactor Jun 7, 2018

@waylan waylan referenced this issue Jun 8, 2018

Merged

Pages Refactor #1504

@waylan waylan closed this in 34ef3ca Jun 28, 2018

Pages Refactor automation moved this from In progress to Done Jun 28, 2018

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