How to activate auto header generation in jupyter-book?

Question

In my jupyter-book, I want to reference a section header in the same document using the syntax below:

I want to refer to [section](intro.md#how-to-learn-python]

where intro.md is your current markdown file, and how-to-learn-python is a section inside this document.

I read that MyST-Parser has Auto-generated header anchors which allow me to do so using the above method. But after I placed my configuration into _config.yml:

parse:
  myst_heading_anchors: 3

It still did not work. Currently, the jupyter-book tutorial requires me to create a tag manually for each section header, which consumes a lot of time.

Other references:

• Adding a cross-reference to a subheading or anchor in another page
• https://daobook.github.io/MyST-Parser/sphinx/use.html#automatically-create-targets-for-section-headers
• https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-header-anchors

Answer 1

I had the same issue and found the reason to be that the jupyter-book config module , which generates the Sphinx configuration, does not include myst_heading_anchors.

So far, I've only managed to enable the feature by manually adding the entry to get_default_sphinx_config in jupyter-book's config.py. This is obviously not a clean or permanent solution, but at least a first step towards a solution. A better solution would be to somehow communicate the directive via the _config.yml config file.

You can add the configuration directive to the generated config by adding

sphinx:
  config:
    myst_heading_anchors: 3

to your _config.yml.