Add use-page config option

The option allows to use a different page for the section page instead
of the first child.

Author: jannschu

README.md

@@ -61,6 +61,21 @@ To make writing this kind of `nav` more natural ([in YAML there's no better opti
     * [Foo](borgs/foo.md)
 ```
 
+### Specifying the page to use for the section
+
+By default the first child is used as the section page, even if there is no
+`index.md`. If you want to change the page to use add the `use-page` config
+option:
+
+```yaml
+plugins:
+  - section-index:
+    use-page: index
+```
+
+The value is the name of the page to use, in this case `index.md`. If a child
+with that name does not exist no section page is generated.
+
 [literate-nav]: https://oprypin.github.io/mkdocs-literate-nav/
 
 ## [Implementation](https://github.com/oprypin/mkdocs-section-index/blob/master/mkdocs_section_index/plugin.py)

mkdocs_section_index/plugin.py

@@ -16,6 +16,10 @@
 
 
 class SectionIndexPlugin(BasePlugin):
+    config_scheme = (
+        ('page', mkdocs.config.config_options.Type(str, default=None)),
+    )
+
     def on_nav(self, nav: Navigation, config, files) -> Navigation:
         todo = collections.deque((nav.items,))
         while todo:
@@ -24,7 +28,16 @@ def on_nav(self, nav: Navigation, config, files) -> Navigation:
                 if not isinstance(section, Section) or not section.children:
                     continue
                 todo.append(section.children)
-                page = section.children[0]
+                name = self.config['use-page']
+                if name is None:
+                    page = section.children[0]
+                else:
+                    for child in section.children:
+                        if child.file.name == name:
+                            page = child
+                            break
+                    else:
+                        continue
                 if not isinstance(page, Page):
                     continue
                 assert not page.children

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "mkdocs-section-index"
-version = "0.3.0"
+version = "0.4.0"
 description = "MkDocs plugin to allow clickable sections that lead to an index page"
 authors = ["Oleh Prypin <[email protected]>"]
 license = "MIT"