Repository: mkdocs/mkdocs

Issue:
README.md -> index.md should be optional
This is a really useful feature, but it should be optional.

I have a `README.md` file in my repository exclusively to render it on GitHub, indicating that the documentation uses format not compatible with GitHub, and that it should be viewed on the generated site.

See: https://github.com/Galarzaa90/NabBot/tree/master/docs

Now, I also have an `index.md` file in the `docs` folder, and that is the actual homepage of my site, and now it is getting overriden by `README.md` and there's no way to see the homepage anymore.

See:
- https://galarzaa90.github.io/NabBot/ - Generated Site
- https://github.com/Galarzaa90/NabBot/blob/master/docs/index.md  - My index.md file

And this is my `pages`/`nav` section:
```yml
nav:
    - Home: index.md
    - Changelog: changelog.md
    - Install Guide: install.md
    - Permissions: permissions.md
    - FAQ: faq.md
    - Features:
      - Overview: features/index.md
      - Autoroles: features/autoroles.md
      - Groups: features/groups.md
    - Commands:
      - Overview: commands/index.md
      - Admin commands: commands/admin.md
      - General commands: commands/general.md
      - Info commands: commands/info.md
      - Loot commands: commands/loot.md
      - Mod commands: commands/mod.md
      - Owner commands: commands/owner.md
      - Roles commands: commands/roles.md
      - Settings commands: commands/settings.md
      - Tibia commands: commands/tibia.md
      - TibiaWiki commands: commands/tibiawiki.md
      - Tracking commands: commands/tracking.md
    - Hosting:
      - Configuration: hosting/config.md
      - Messages: hosting/messages.md
      - Cogs: hosting/cogs.md
```

Full file: https://github.com/Galarzaa90/NabBot/blob/master/mkdocs.yml


Discussion:
How would you propose we determine which file to use? Only fall back to `README.md` if `index.md` is not present? Of did you have something else in mind?

And as a reminder, in version 1.0 the `nav` section of the config has no effect on which pages are included in the build. It only defines the global navigation menu. Therefore, it would have no effect on whether MkDocs should use `README.md` or `index.md` as the index file for a directory.
I think that could be the safest option. If `index.md` is present, then do not use `README.md`.
I'm not entirely sure how to implement this. Internally we build up a files collection which holds the data for each page. That collection would contain an object for each of the README and the index file. For example, using pseudo code, a collection might look like this:

```
[
    Page(src_path='index.md, dest_path='index.html', url='index.html'),
    Page(src_path='README.md', dest_path='index.html', url='index.html'),
    Page(src_path='about.md', dest_path='about.html', url='about.html')
]
```

The problem is that two different source pages both point to the same destination. And as we step through that collection, writing each file to the destination, the second file overwrites the first. Perhaps we should not include the README at all if there is an index? It would seem unlikely that the user would want the README to be included even if it was "hidden."
        

And how is this collection ordered? If somehow, `README.md` always had precedence in the collection, even if it generated `index.html`, it would then be overwritten by the content of `index.md`.

I'm assuming this collection is just ordered from crawling the files in the `docs` directory, so hardcoding a different order for `README.md` is probably not a viable option.

And yes, this would mean not including `README.md` at all if there's also an `index.md` file. But who knows if someone actually wants both `README.md` and `index.md`.

We use our own [sort function][1] (within a directory) which sorts index files to the top so that an index file always comes first. All other files are sorted alphanumerically. The sort function does nothing special for readme files. So, currently the index file will always come before the readme file. Perhaps the simple fix would be to simply update the sort function to sort readme files before index files.

The other solution would be to [exclude][2] the readme if an index file is present.

[1]: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/files.py#L240
[2]: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/structure/files.py#L232
Thinking about this more, it occurs to me that we promise that index files are sorted to the top. However, that is not true when the source of an index file is README.md. Therefore, sorting the README might actually fix two bugs.
Then I think sorting would be a good solution for this :)

Resolving patch:
diff --git a/mkdocs/structure/files.py b/mkdocs/structure/files.py
--- a/mkdocs/structure/files.py
+++ b/mkdocs/structure/files.py
@@ -232,20 +232,23 @@ def get_files(config):
             # Skip any excluded files
             if _filter_paths(basename=filename, path=path, is_dir=False, exclude=exclude):
                 continue
+            # Skip README.md is an index file also exists in dir
+            if filename.lower() == 'readme.md' and 'index.md' in filenames:
+                continue
             files.append(File(path, config['docs_dir'], config['site_dir'], config['use_directory_urls']))
 
     return Files(files)
 
 
 def _sort_files(filenames):
-    """ Always sort `index` as first filename in list. """
+    """ Always sort `index` or `README` as first filename in list. """
 
     def compare(x, y):
         if x == y:
             return 0
-        if os.path.splitext(y)[0] == 'index':
+        if os.path.splitext(y)[0] in ['index', 'README']:
             return 1
-        if os.path.splitext(x)[0] == 'index' or x < y:
+        if os.path.splitext(x)[0] in ['index', 'README'] or x < y:
             return -1
         return 1
 


Test patch:
diff --git a/mkdocs/tests/structure/file_tests.py b/mkdocs/tests/structure/file_tests.py
--- a/mkdocs/tests/structure/file_tests.py
+++ b/mkdocs/tests/structure/file_tests.py
@@ -48,6 +48,11 @@ def test_sort_files(self):
             ['a.md', 'a.md', 'b.md']
         )
 
+        self.assertEqual(
+            _sort_files(['A.md', 'B.md', 'README.md']),
+            ['README.md', 'A.md', 'B.md']
+        )
+
     def test_md_file(self):
         f = File('foo.md', '/path/to/docs', '/path/to/site', use_directory_urls=False)
         self.assertPathsEqual(f.src_path, 'foo.md')
@@ -533,6 +538,31 @@ def test_get_files(self, tdir):
         self.assertEqual(len(files), len(expected))
         self.assertEqual([f.src_path for f in files], expected)
 
+    @tempdir(files=[
+        'README.md',
+        'foo.md'
+    ])
+    def test_get_files_include_readme_without_index(self, tdir):
+        config = load_config(docs_dir=tdir)
+        files = get_files(config)
+        expected = ['README.md', 'foo.md']
+        self.assertIsInstance(files, Files)
+        self.assertEqual(len(files), len(expected))
+        self.assertEqual([f.src_path for f in files], expected)
+
+    @tempdir(files=[
+        'index.md',
+        'README.md',
+        'foo.md'
+    ])
+    def test_get_files_exclude_readme_with_index(self, tdir):
+        config = load_config(docs_dir=tdir)
+        files = get_files(config)
+        expected = ['index.md', 'foo.md']
+        self.assertIsInstance(files, Files)
+        self.assertEqual(len(files), len(expected))
+        self.assertEqual([f.src_path for f in files], expected)
+
     @tempdir()
     @tempdir(files={'test.txt': 'source content'})
     def test_copy_file(self, src_dir, dest_dir):