How to specify index content/entries in Markdown?

Question

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

Note that there is both a *directive* and a *role* called `index` in ReST. `.. index::` is the directive and `:index:` is the role. The referenced MyST documentation is about roles. — mzjn, Feb 10 '23 at 10:46
Yeah, I worded it incorrectly, I meant the directive. Thanks for pointing this out, I will update the question. — Igor Brejc, Feb 10 '23 at 17:33
I get a different error message than the one in the question: "Directive 'index': 1 argument(s) required, 0 supplied" (with Sphinx 5.3.0, docutils 0.17.1, myst-parser 0.18.1). — mzjn, Feb 11 '23 at 10:32
@mzjn yeah, it's complicated. Try adding a main entry in the first line, like `{index} MainEntry` — Igor Brejc, Feb 11 '23 at 11:20

score 1 · Answer 1 · edited Feb 21 '23 at 18:46

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

Thanks! This works for cases when you only need a single entry added to the index, but I still don't know how to add multiple entries (see the updated question) - is there a separator char that can be used in Myst for multiple arguments? — Igor Brejc, Feb 10 '23 at 18:10

How to specify index content/entries in Markdown?

1 Answers1

reStructuredText

MyST

Update