The current pages configuration looks like this:
This has a number of flaws:
This change adds a new format which makes the above configuration
(Note I added some tiles on purpose and skipped some to show usage).
With this structure, we can more easily see the documentation
This change restructures the pages configuration, but doesn't yet
The text was updated successfully, but these errors were encountered:
The current pages configuration looks like this: pages: - ['index.md', 'Home'] - ['writing-your-docs.md', 'User Guide', 'Writing your docs'] - ['styling-your-docs.md', 'User Guide', 'Styling your docs'] - ['configuration.md', 'User Guide', 'Configuration'] - ['about/license.md', 'About', 'License'] - ['about/release-notes.md', 'About', 'Release Notes'] - ['about/contributing.md', 'About', 'Contributing'] This has a number of flaws: - It isn't clear how to add second levels of navigation for newcomers. This is often queried and not easy to document. - We are representing a tree structure as a set of flat items that need to be merged. This creates some interesting edge cases, for example: - ['writing-your-docs.md', 'User Guide'] - ['styling-your-docs.md', 'User Guide', 'Styling your docs'] Is the first entry a page with the title User Guide? or a page in the User Guide category with an automatic title. - We are currently limited to two levels deep in the navigation. Changing this with the current structure isn't trivial. This change adds a new format which makes the above configuration look like this: pages: - Home: index.md - User Guide: - user-guide/writing-your-docs.md - user-guide/styling-your-docs.md - user-guide/configuration.md - About: - License: about/license.md - about/release-notes.md - Contributing: about/contributing.md With this structure, we can more easily see the documentation tree and it is far more obvious what the navigation will look like. It also removes the ambiguous edge cases and opens up the possibility of adding further levels to the navigation more easily. This change restructures the pages configuration, but doesn't yet allow users to add further levels in the navigation. Fixes mkdocs#6
Further refactor the site navigation builder to allow for further nesting of the pages.