mkdocs / mkdocs

Project documentation with Markdown.
https://www.mkdocs.org
BSD 2-Clause "Simplified" License
18.49k stars 2.36k forks source link

Organizing chapters on toolbar using mkdocs #3689

Closed leweex95 closed 1 month ago

leweex95 commented 1 month ago

I am using mkdocs (1.6.0) with mkdocs-material (9.5.19).

My documentation that I am building with mkdocs and hosting on Github Pages looks approximately like this:

repo/
├── docs/
│   ├── index.md
│   ├── assets/
│   ├── chapter1/
│   │       ├── assets/
│   │       ├── chapter1_doc1.md
│   │       ├── chapter1_doc2.md
│   │       └── index.md
│   ├── chapter2/
│   │       ├── assets/
│   │       ├── chapter2_doc1.md
│   │       ├── chapter2_doc2.md
│   │       └── index.md

I understand that the uppermost index.md will be the opening page of the hosted site. That file has a title "Introduction" which, upon rendering on Github Pages, will create an "Introduction" chapter on the top toolbar with only one page, the identically named Introduction page being in it.

I would like to specify more introduction-related pages instead of having to condense everything into this global index.md. I tried adding getting-started.md and contact-us.md files on the top level (just within the docs folder, i.e., on the same level as the main index.md) but that created two additional chapters on the toolbar: Getting Started and Contact Us. That is not what I had in mind; I would like to use the aforementioned "Introduction" chapter and add more pages to it.

I'm aware I can just reorganize my folder structure like this:

repo/
├── docs/
│   ├── assets/
│   ├── Introduction/
│   │       ├── assets/
│   │       ├── index.md
│   │       ├── getting-started.md
│   │       └── contact-us.md
│   ├── chapter1/
│   │       ├── assets/
│   │       ├── chapter1_doc1.md
│   │       ├── chapter1_doc2.md
│   │       └── index.md
│   ├── chapter2/
│   │       ├── assets/
│   │       ├── chapter2_doc1.md
│   │       ├── chapter2_doc2.md
│   │       └── index.md

However, in this case my original index.md is no longer on the top level and hence the site will not have an opening page as earlier. Can I point the opening page to be the docs/Introduction/index.md? If so, how?