Customize left navigation TEXT in sphinx book theme using myST

[lwasser]

Hey y'all. I have a nav bar question

in RST i can customize a toctree setup like so where i can assign a specific name to appear in the toc for each link. It will default to the H1 otherwise.

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   TEXT SHOWN IN NAV BAR HERE <get-started/index>
   TEXT SHOWN IN NAV BAR HERE <manage-assignments/index>

I've tried a few things with myST

```{toctree}
:hidden:
:caption: Documentation

TEXT HERE DOESN"T WORK documentation/intro
documentation/readme-files TEXT HERE DOESN"T WORK
ALSO DOESN"T WORK <documentation/package-documentation-tutorials>

I'm open to submitting a documentation PR update if there is a way to do this? Or am I missing the correct documentation page perhaps?
Many thanks
Leah

ANSWER:

make sure you only have one h1 level element on your markdown page.

# Title here

no more h1 's after. h2, h3 ... etc are all fine. but sphinx book theme expects only one h1 which is best practice for website design anyway. but the behavior surprised me.

[chrisjsewell]

Hey Leah, this works exactly the same with myst as rst. You can see it working here: https://github.com/aiidateam/aiida-website/blob/main/docs/index.md

[lwasser]

@chrisjsewell THANK YOU. Clearly there is user error (leah error happens!!) happening here. I see it working. it works for me sometimes

can you by chance think of anything that could cause the inconsistent error that I could check? Clearly I broke something somewhere but am out of ideas regarding what to test. Thank you so much for any ideas.

PR here
html artifact here Can you see this?

Example:

```{toctree}
:hidden:
:caption: Documentation
I dont work <documentation/index.md>
I dont work <documentation/create-readme-files.md>
I work here <documentation/package-documentation-tutorials.md>
```

```{toctree}
:hidden:
:caption: Package structure
I don't work <package-structure-code/index.md>
I work <package-structure-code/code-structure-style.md>
```

[lwasser]

ok @chrisjsewell i FINALLY FIGURED THIS OUT. it was acting buggy BECAUSE i had additional # h1 tags

in the page. If a user has more than one h1 tag in their markdown file, the book theme IGNORES the title text that you specify

I dont work <documentation/index.md>

I use h1 tags with TODOS while i'm working as they pop out in my vscode outline as things i need to do. I noticed a page that i was done working on started to work in the nav bar so i took another page and commented all of the h1 todo's out. WALA the navigation custom titles worked. Hopefully this will help someone else running into seemingly buggy behavior. i'm not sure why that impacted the side nav titles but it did! it's resolved now.

[chrisjsewell]

Good debugging! I guess maybe open an issue in the book theme, as seems an unexpected behaviour?

[lwasser]

Sure thing.

I'll open an issue! If it's desirable, i'm happy to submit a PR to update the docs on creating custom navigation using :hidden and toctree with custom labels as well. I've been digging into other people's documentation to try to figure this out. I wondered if having a section on that left nav bar setup could be helpful to others?