How to specify index content/entries in Markdown?

480 Views Asked by At

Based on the Sphinx documentation, to specify various index entries (single entry, for example) in reStructuredText, like this:

.. index::
   single: execution; context

The execution context
---------------------
...

When using Myst to do the same in Markdown (and according to its documentation), this should be its equivalent:

```{index}
   single: execution; context
```

sphinx-build reports an error: Directive 'index': No content permitted.

Since adding content to other Sphinx directives (like toctree) works, my assumption is there is some hard-coded logic in the myst_parser Sphinx extension preventing adding the content for the index directive. Is my assumption correct or is there actually a way to add entries to the index in Markdown?


UPDATE: as per Steve's answer, it is possible to put one of the entries directly in the first line, like this:

```{index} single: execution; context
```

But then the new question is how to add multiple entries into the same index item, which reStructuredText supports (an example from Sphinx docs):

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path
1

There are 1 best solutions below

2
On

Per @mzjn's comment, you probably want the MyST documentation for Directives - a block-level extension point.

reStructuredText

.. directivename:: arguments
   :key1: val1
   :key2: val2

   This is
   directive content

MyST

```{directivename} arguments
---
key1: val1
key2: val2
---
This is
directive content
```

For a directive, the arguments are on the same line as the directive, and options are on subsequent lines in key/value pairs. In your example, the MyST directive index treats your single: execution; context as content, which is not allowed.

Thus try this untested example:

```{index} single: execution; context
```
# The execution context

Update

Untested, but try this:

```{index}
---
single: execution; context
module: __main__
module: sys
triple: module; search; path
---
```
# The execution context

And if that does not work, you could try good old brute force with eval-rst.

```{eval-rst}
.. index::
    single: execution; context
    module: __main__
    module: sys
    triple: module; search; path
```

# The execution context