How to turn on heading numbering ?

[rtesse]

Hello, I am building a project with Sphinx and myst_parser. Looking into the documentation of MyST Markdown, I saw this is possible to have numbering headers:

https://mystmd.org/guide/cross-references

But including this in my file.md and compiling with the classic make html, the headers are not referenced by number.

Do I miss something ?

[72757373656c6c]

I'm not 100% sure, but it sounds like you are using Sphinx+Myst, which is different than mystmd. If that is the case, the documentation is here:

https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html

Look for the toctree option numbered.

numbered: Number all headings in children. If an integer is specified, then this is the depth to number down to

Your index.md might look like:

 # Welcome

 :::{toctree}
 :glob:
 :hidden:
 :maxdepth: 1
 :numbered:

 [a-z]*
 :::

Html output might format like:

1. Hello World
This is a new document.

1.1. Not so fast
This is a level 2 heading.

1.1.1. Slow down
This is a level 3 heading.

1.2. Goodbye world
So long, and thanks for all the fish. – Douglas Adams

In this case, make sure to do a make clean && make html.

[rtesse]

Hello, thank you for your answer. Indeed, I use Sphinx+Myst. After re-reading what I wrote, my question was not so clear, sorry for this. Here is a minimal working example with this index.rst file:

.. toctree::
   :maxdepth: 2
   :caption: Contents: 
   :numbered:

   introduction.md

and the introduction.md file:

(first_chapter)=

# First chapter

# Second chapter

In chapter [](first_chapter)

When I do make html, I have the results below and I was wondering if it is possible to have the sentence In chapter 1. instead of having In chapter First chapter.

Do I need to add something in my conf.py file ?

project = "test"
copyright = "2024, robin"
author = "robin"

extensions = [
   "sphinx.ext.autodoc",
   "myst_parser",
]

myst_enable_extensions = [
   "amsmath",
   "attrs_inline",
   "colon_fence",
   "deflist",
   "dollarmath",
   "fieldlist",
   "html_admonition",
   "html_image",
   "replacements",
   "smartquotes",
   "strikethrough",
   "substitution",
   "tasklist",
]

html_theme = "alabaster"
html_static_path = ["_static"]

[72757373656c6c]

I was wondering if it is possible to have the sentence In chapter 1. instead of having In chapter First chapter

One way to do it is to put the desired link text inside the brackets [link text](link destination).

In [chapter 1](first_chapter)

Reference doc:

• Creating explicit targets

[rtesse]

Ok so it means I have to know all the structure of my documentation before. If I add sections before, do I have to manually change all the cross links ?

[72757373656c6c]

With this option, I'm 99% sure the answer is "yes".

Manual. Yuck. 😉

Maybe...

I see in Mystmd they have number references and substitution, %s or {number}.

The myst-sphinx documentation says,

Sphinx offers numerous roles for referencing specific objects.

These can also be used within MyST documents, although it is recommended to use the Markdown syntax where possible, which is more portable and native to MyST.

In addition to {ref}, I see that sphinx also has a {numref}. There is more doc at readthedocs for the numref role. There is one reference to numref in the MyST documentation.

Question
The question becomes, will the numref role work in Sphinx+MyST for section/heading numbering?

Additional Link

• Sphinx - Add way to reference chapters / sections

Update

I got it to work! 😄

I didn't have to add anything to conf.py.

I created the explicit targets: (target)=.

And to use it: In Chapter {numref}`%s <target>`.

Anyone doing this with Sphinx-MyST? Did I get it right? Any suggestions for OP.

[rtesse]

I can confirm, it works :) . Thanks a lot for the help, I will use this method as it is quite flexible.