Improve documentation about custom roles

[dbitouze]

Context

reStructuredText lets us easily define Custom Interpreted Text Roles, say .. role:: custom, which can be used automatically in every document thanks to rst_prolog (to be inserted in the conf.py file):

rst_prolog = """
.. role:: custom
"""

Then if a .rst file contains :custom:`foo`, the corresponding html built file contains:

<span class="custom">foo</span>

It is not clear from the MyST documentation if such a feature is provided by MyST and, if so, how to proceed.

Proposal

Could you clarify the MyST documentation from this point of view?

Related discussion: https://github.com/executablebooks/MyST-Parser/discussions/634.

Tasks and updates

No response

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[dbitouze]

Let me be more explicit.

Consider two minimalist, almost identical, Sphinx-doc sites, a reStructuredText one and a Markdown one, resp. in folders test-rst and test-md, with the following:

• structures:

  ./test-rst
  ├── build
  ├── make.bat
  ├── Makefile
  └── source
      ├── conf.py
      └── test.rst
  

  and:

  ./test-md
  ├── build
  ├── make.bat
  ├── Makefile
  └── source
      ├── conf.py
      └── test.md
  

• identical conf.py configuration file:

  project = 'Test'
  copyright = 'Test'
  
  # -- General configuration ---------------------------------------------------
  
  # The suffix(es) of source filenames.
  # You can specify multiple suffix as a list of string:
  #
  source_suffix = ['.rst', '.md']
  
  # The master toctree document.
  master_doc = 'test'
  
  rst_prolog = """
  .. role:: custom
  """
  
  # Add any Sphinx extension module names here, as strings. They can be
  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  # ones.
  extensions = [
      'myst_parser',
  ]
  

• sources files:

  • test.rst:

    .. toctree::
    
    :custom:`foo`
    

  • test.md:

    ```{toctree}
    ```
    
    {custom}`foo`
    

When these sites are built with make html, the compilation of the:

• reStructuredText one works without any error,
• Markdown one results in the error:

  .../test-md/source/test.md:4: ERROR: Unknown interpreted text role "custom".

and, looking at the differences between the .html generated files with diff test-rst/build/html/test.html test-md/build/html/test.html:

38c38
< <p><span class="custom">foo</span></p>
---
> <p><a href="#id1"><span class="problematic" id="id2">foo</span></a></p>
95c95
<       <a href="_sources/test.rst.txt"
---
>       <a href="_sources/test.md.txt"

we see that the role custom is, in the case:

• reStructuredText: recognized,
• Markdown: not recognized.

Hence my concern: does MyST support custom roles?

[jessicah]

It does, it just doesn't seem to support the rst_prolog key, which would be helpful.

I added the following to the top of one of my markdown files:

```{role} nc
```

Then later in my document, I could "{nc}`use my custom role`" without issues.

I even combined with rst-class to add block level HTML classes.

```{rst-class} highlight no-background
- Some text, with my {nc}`highlighted span` in it
```

That generated HTML like below:

<ul class="highlight no-background simple">
<li>
<p>Some text, with my <span class="nc">highlighted span</span> in it</p>
</li>
</ul>

[dbitouze]

@jessicah Many thanks for your insights!

Your workaround indeed does the trick :smile:. But the point is, my documentation (in fact a ((La)TeX) FAQ) contains 1240 source files...

Hence, as you said, it would be helpful for MyST to support the rst_prolog key, or even an equivalent which would be proper to MyST.

[chrisjsewell]

I believe the more "Markdown centric" way to do this is in #654

There you can now add any number of classes to both verbatim text and (nested) spans:

`verbatim`{.class1 .class2} [*span*]{.class3 .class4}

[dbitouze]

I believe the more "Markdown centric" way to do this is in #654

There you can now add any number of classes to both verbatim text and (nested) spans:

`verbatim`{.class1 .class2} [*span*]{.class3 .class4}

@chrisjsewell Is this "Markdown centric" way documented in https://myst-parser--717.org.readthedocs.build/en/717/?

(BTW, thanks for working so hard on a new release!)

[chrisjsewell]

is this "Markdown centric" way documented in

• https://myst-parser--717.org.readthedocs.build/en/717/syntax/typography.html#inline-text-formatting
• https://myst-parser--717.org.readthedocs.build/en/717/syntax/code_and_apis.html#inline-syntax-highlighting

Feedback welcome though

(BTW, thanks for working so hard on a new release!)

Thanks!

[dbitouze]

Feedback welcome though

Looks clear! But needs to be tested in order to be sure: can't wait for the release to be published! :wink: