In myst.yml toc element, is title field allowed for file entries?

[emiliom]

I'm new to JB2, but have used JB1 extensively.

I'm trying to mirror the JB1 capability to add a title field to any file entry in the toc (url entries still handle a title field as expected). But the title entry is ignored, and the title is always drawn from the document title in the referenced file. The only exception I could find is when the file entry has children; I couldn't find documentation for that behavior, but I found one live example in the JB2 website: the myst.yml toc entry is here, and the website result is here

I can't find anything in the JB2 or mystmd documentation that explicitly says that file entries w/o children will ignore a title field. The closest I can see is in the mystmd TOC page "Document title" section, which describes where the document title in the toc is drawn from; it doesn't say that it's possible to override the title found on the document using a title field.

I also found a JB2 website featured on the JB2 Gallery that uses lots of toc title fields, all of which seem to be ignored. For an example, see the Foreground section: the entry that appears on the rendered site's TOC as "Navigating The Turing Way" is actually coded as

- file: foreword/navigate.md
  title: Navigating the Handbook

I'm using jupyter-book 2.1.0 installed from PyPI via uv.

Thanks!

[emiliom]

Adding links to relevant issues:

• Support overriding the file title in the Table of content #1324
• Feature Request: Customize titles for files in myst.yml #2470

[FreekPols]

In the frontmatter of the specific page you can add a short_title. This short_title replaces the title in the toc.

---
title: Gallery
short_title: Title for toc
--- 

# Gallery

It is briefly (and bit cryptic) described here: https://mystmd.org/guide/frontmatter#titles

[choldgraf]

We have a PR to fix this here

• Allow TOC to set short_title #2636

Just needs to be merged!

[emiliom]

@choldgraf that's wonderful, thank you!!

@FreekPols thanks for chiming in. Yeah, I'm aware of the short_title entry in the page frontmatter. I actually started using it in the absence of the ability to set the TOC file title in the TOC itself. But having that ability in the TOC provides more flexibility and convenience. @choldgraf's PR addresses that need directly.

[emiliom]

I'm marking this as "answered", since @choldgraf 's PR has been merged. Thanks again!