Skip to content
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

Refactor the pages configuration #482

Merged
merged 4 commits into from May 5, 2015
Merged

Refactor the pages configuration #482

merged 4 commits into from May 5, 2015

Conversation

@d0ugal
Copy link
Member

@d0ugal d0ugal commented Apr 27, 2015

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

(Note I added some tiles on purpose and skipped some to show usage).

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.

See #6

@d0ugal d0ugal added this to the 0.13.0 milestone Apr 27, 2015
@ci5er
Copy link

@ci5er ci5er commented Apr 27, 2015

I never personally had a problem with the old way, but this is pretty dang sweet. Thank you.

@waylan
Copy link
Member

@waylan waylan commented Apr 28, 2015

Wow, that is a great improvement. At a glance, the page structure is immediately obvious from the config. I like it.

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented May 1, 2015

This is now supported in the MkDocs theme.

MkDocs theme

@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented May 1, 2015

RTD

d0ugal added 4 commits May 5, 2015
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.
@d0ugal
Copy link
Member Author

@d0ugal d0ugal commented May 5, 2015

Rebased to fix a conflict. This is working really well, I'm going to land it if the build is okay. For now just the mkdocs and ReadTheDocs themes will support >2 levels of nav.

d0ugal added a commit that referenced this issue May 5, 2015
Refactor the pages configuration
@d0ugal d0ugal merged commit 7849e71 into mkdocs:master May 5, 2015
3 checks passed
@d0ugal d0ugal deleted the nav-refactor branch May 5, 2015
@tobegit3hub
Copy link

@tobegit3hub tobegit3hub commented May 6, 2015

Looking forward to this feature 😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants