readthedocs.org: README.md not found

Hi and thanks for the readthedocs.org project,

I’m using readthedocs.org and mkdocs for the following project:

https://github.com/Orange-OpenSource/fiware-cepheus/

All docs are in ‘doc’ and only have README.md files (as github displays them by default), and using the following mkdocs.yml with explicit pages:

site_name: Fiware-Cepheus
repo_url: https://github.com/Orange-OpenSource/fiware-cepheus
site_description: FIWARE Cepheus Documentation
docs_dir: 'doc'
markdown_extensions: [toc,fenced_code]
theme: readthedocs
pages:
- 'Home': 'README.md'
- 'Cepheus-CEP':
  - 'Overview': 'cep/README.md'
  - 'Configuration': 'cep/configuration.md'
  - 'NGSI mapping': 'cep/mapping.md'
- 'Cepheus-Broker': 'broker/README.md'

mkdocs is working fine localy (mkdocs 0.14.0, pip pip 7.1.2, python 2.7) to generate the doc but fails during build on readthedocs.org:

ERROR   -  file not found: /home/docs/checkouts/readthedocs.org/user_builds/fiware-cepheus/checkouts/latest/doc/README.md 
ERROR   -  Error building page README.md

I expected not to be forced to use index.md if all pages are explicitly listed in the mkdocs.yml.

Am I wrong ?

About this issue

Original URL
State: closed
Created 9 years ago
Comments: 17 (8 by maintainers)

Most upvoted comments

I see this is still an open issue, and I believe I have seen several issues in regards to the README.md and index.md relationship. Can someone comment on where it stands?

Specifically, I am very much interested to know if there is a way to configure ReadTheDocs to simply use README.md as the index file - as is the practice on GitHub itself and GitHub Pages. this will make it fully compatible across three platforms.

DannyBen on May 20, 2018

Well, as it seems this issue is one comment away from being closed, I leave you with food for thought:

There is only something to gain, and probably nothing to lose, by having a logic that shows index.md if found, and falls back to showing README.md if not. No dirty tricks needed, no copying of anything. Just a fallback.

DannyBen on Sep 4, 2018

I see. I wish it was different - I really like cross-platform compatibility, and was hoping I can use the same repo for both GitHub pages and RTD.

DannyBen on May 21, 2018

Workaround: I moved the contents all of README.md files to index.md and it now works correctly.

yalp on Sep 1, 2015