lukasgeiter / mkdocs-awesome-pages-plugin

An MkDocs plugin that simplifies configuring page titles and their order
MIT License
452 stars 35 forks source link

Question: Page ordering in subfolders #68

Closed elapse2039 closed 1 year ago

elapse2039 commented 1 year ago

I've spent some time reading and re-reading the documentation... and experimenting... and would appreciate any guidance on whether the following is possible...

I understand .pages can be added to docs/ or a subfolder/ in a mkdocs project. The one I create at the top level in teh docs/ folder works and can define the order of pages and include subfolders.

I think I can also include .pages in subfolders and I see they get parsed. What I can't figure out is how to include them from the top-level .pages file so that they are used to build the subfolder menu items. When I include the subfolder in the menu, I get the subfolder pages in alphabetical order. It is as if the subfolder .pages file is ignored.

Top level .pages content...

nav:
    - Overview: 'index.md'
    - Blender: 'blender_jobs.md'
    - Topology: 'topology.md'
    - Technical:
        - "Overview": install.md
        - installation
        - services
        - "Resources":
          - Goto Blender: http://blender.org
          - Goto Flamenco: https://flamenco.blender.org/

The subfolder "installation" has a .pages

nav:
  - "Building": requirements.md
  - "Ansible Host": ansible_host.md
  - "Adding a worker node": node_add.md

What I get is the installation subfolder showing up with alphabetical list of pages.

Screen Shot 2023-02-16 at 9 51 51 PM

I have also tried building a top level .pages file and have also failed to hard-code subfolder pages.

nav:
    - Overview: 'index.md'
    - Blender: 'blender_jobs.md'
    - Topology: 'topology.md'
    - Technical:
        - "Overview": install.md
        - installation:
          - Building: installation/requirements.md
        - services
        - "Resources":
          - Goto Blender: http://blender.org
          - Goto Flamenco: https://flamenco.blender.org/

In this last example, the Building page fails to render with a 404 whether I put the installation/ subfolder or not in the .pages navigation entry.

WARNING  -  [21:55:52] "GET /requirements.md HTTP/1.1" code 404
...
WARNING  -  [21:55:05] "GET /installation/requirements.md HTTP/1.1" code 404

I have also tried other flags, like hide: true in installation/ subfolder and it seems to have no effect. What am I missing or misunderstood from the documentation?

If I use "..." then subfolder pages are incorporated and work but they are in alphabetical order.

elapse2039 commented 1 year ago

Arh... I found the issue... in my top level .pages I had created a logical two subfolder layer structure (technical/ installation/) but there is only one subfolder layer (installation).

When I create real two-layer subfolder structure: docs/ technical/ installation/ each with their own .pages they are parsed and used.