Allow title of JupyterBook page to be defined in YAML block?

[rowanc1]

I am under the impression at the moment that JupyterBook doesn't support the title being defined as anything other than an H1?

I was looking at a few other projects (quarto, fastpages, rmd, some blogging sites) and a lot of those allow you to specify the page title in the YAML block at the top. I wonder if JupyterBook could also do that?

i.e. allowing:

---
title: My title
...
---

Content without a header

vs currently requiring:

# My Title

Content with a header first, and I think mostly ignoring the YAML block?

[choldgraf]

It might be possible but is probably clunky. We do some hacky workarounds in other Sphinx sites to get a similar effect (e.g. see
https://sphinx-book-theme.readthedocs.io/en/latest/)

It seems like there are some common markdown rules that would make this more complex. Specifically:

• It's good for pages to only have a single <h1> tag, denoting the "most important header" of the page
• It's good for pages to not "skip" header levels (e.g. start at <h2> or go from <h1> to <h4>) (one ref here)
• Markdown tends to map # to <h1> and ## to <h2>

So:

• if you allow for people to write a lot of single # headers on a page, you'd need to change the parsing logic to make those map onto h2 as a special case, if a title object were specified
• if you allow for people to just start with ## on the page, you'll trigger errors in Sphinx because it wants the document structure to follow the same "hierarchy" of # then ## then ### and so on

[chrisjsewell]

Wanna move the conversation to executablebooks/MyST-Parser#492 😄

[rowanc1]

This is great. :)

[jgunstone]

would it be possible to extend this to cover of meta data associated to the JupyterBook, like pandoc's yaml_metadata_block ?

https://pandoc.org/MANUAL.html#extension-yaml_metadata_block