Organizing chapters on toolbar using mkdocs & mkdocs-material

[leweex95]

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?

[alexvoss]

One idea might be to use a redirect? As far as I know, this involves creating a file docs/index.md that uses the redirect.html template and specifies the desired location.

---
template: redirect.html
location: Introduction/index.md
---

[leweex95]

Thank you for that.

I tried it but I still get two "Introduction" tabs on the navigation bar. One is coming from the "docs/index.md" while the other is coming from the "docs/Introduction" folder.

I would want to merge these two entirely.

[alexvoss]

You could help us advise you by creating a minimal reproduction. What you are describing now seems to be a different problem (perhaps I am holding the wrong end of the stick), so would be good if we could look at the same thing.

[leweex95]

@alexvoss , sure thing. Sorry for the confusion. I created a minimal reproducible example to demonstrate the issue.

Here is a screenshot to start with; as you see, the "Introduction" tab is duplicated no matter what I do.

Please find the whole trial project in the attached zip.

mkdocs_trial.zip

[alexvoss]

Is this what you are looking for?

[alexvoss]

introduction.zip

If it is, the trick is to define a navigation in the mkdocs.yml. I am not sure the desired effect can be achieved when you let MkDocs generate the navigation for you as it will take docs/index.md even if it contains only the redirect header. It will just be called "Home".

[leweex95]

Thanks a lot @alexvoss , that is exactly what I was after!