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

Proposal to page sorting #137

Open
mrtve opened this issue Oct 29, 2024 · 0 comments
Open

Proposal to page sorting #137

mrtve opened this issue Oct 29, 2024 · 0 comments

Comments

@mrtve
Copy link

mrtve commented Oct 29, 2024

The one thing that I think this plugin is lacking is the ability to customize page ordering.
When using the following syntax to include nested mkdocs.yml files it doesn't seem to be sorted in any meaningful manner:

nav:
  - Intro: 'index.md'
  - Components: '*include ./components/*/mkdocs.yml'

I'm not fully certain if the capabilities to sort all folders can be achieved in combination with other plugins e.g.
https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin. This is a mockup of what I think could be a useful way to customize page layouts in monorepo setups, feel free to post suggestions or corrections!

I think it could be a great addition if the monorepo plugin had support for the following configurations:

monorepo:
  sorting-method: alphabetical | natural | none
  folder-order: first | last | mixed (do not treat folders and file separately)
  page-order:
    - introduction.md
    - ...
    - summary.md
    - changelog.md

The above configuration would be the 'default' folder layout for any mkdocs.yml file unless explicitly defined by the included mkdocs.yml. Notably, it follows a similar syntax to the mkdocs-awesome-pages-plugin.

sorting-method: Determines the order of sections/files

folder-order: Determines the order of folders. If placed first or last the folders are also sorted with the sorting-method, but they will be placed together.

page-order: Determines the order of pages within a folder. The elements mentioned here determine the page order, with ... including anything that doesn't match the other filenames. I guess that it will also include folders here in case any are present.

The 'page-order' concept is inspired by the mkdocs-awesome-pages-plugin, but in this case its applied recursively throughout the entire repo, unless an included mkdocs.yml file specifies its own nav layout. In many cases i want the 'introduction.md' (or similarly named) page to be the 'landing' page of a section. At the same time i also like the idea of structuring each section as a report that may need to follow a deterministic layout which can't be achieved with any sorting method.

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

No branches or pull requests

1 participant