Using superscript in toctree doesn't render correctly

[chester-leung]

Describe the bug When I try to render a superscript as part of a toctree, either using the HTML <sup> tag or the reStructuredText :sup:, the built sphinx documentation doesn't produce a superscript but instead copies the exact characters into the built documentation. For example, I have the following:

.. toctree::
     :maxdepth: 2

What is MC<sup>2</sup> <self>
documentation
GitHub <https://github.com/mc2-project/mc2>

Sphinx builds

when I'm expecting

To Reproduce Steps to reproduce the behavior:

<Paste your command-line here which cause the problem>

$ git clone https://github.com/mc2-project/mc2-project.github.io.git
$ cd mc2-project.github.io
$ sudo apt-get install -y enchant
$ pip3 install furo sphinx sphinx-argparse sphinx-copybutton sphinxcontrib-spelling
$ make html
$ open _build/html/index.html
See left navigation bar

Expected behavior The table of contents should include my links with the superscript rendered correctly, as shown above. (I made it render correctly by manually going into the resulting HTML and changing the relevant line, which originally appeared as href="#">What is MC&lt;sup&gt;2&lt;/sup&gt;</a></li>)

Your project https://mc2-project.github.io/

Screenshots See above

Environment info

• OS: Ubuntu 18.04
• Python version: 3.6.9
• Sphinx version: 3.0.3
• Sphinx extensions: "sphinx.ext.autodoc", "sphinx.ext.autosectionlabel", "sphinxarg.ext", "sphinx_copybutton", "sphinxcontrib.spelling"

Additional context It looks the problem may stem from the files _static/underscore-1.3.1.js, which contains the line

return (''+string).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')

or _static/underscore.js, which contains the line ...b.escape=function(a){return(""+a).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;")...

I'm also unsure if this issue stems from sphinx itself or the theme I'm using, Furo, so apologies if I posted this in the wrong place.

[astrojuanlu]

I confirm this issue. It's not specific to superscripts (any HTML markup will be copied verbatim) and it's not specific to Furo (I also tried with Alabaster)

I think this is a limitation in reStructuredText, since nested inline markup is not possible:

https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible

The workaround for your specific case would be to use the corresponding Unicode character:

https://www.fileformat.info/info/unicode/char/b2/index.htm

For generic HTML and reST roles, I don't think this can be fixed.

[chester-leung]

@astrojuanlu thanks for your help. It seems that reST also replaces the & from the unicode character - the rendered HTML looks like MC². Any suggestions on how to fix this? Thank you.

[astrojuanlu]

@chester-leung I can't reproduce it, & looks fine to me:

$ cat index.rst
...
.. toctree::

   U & E <usage>
$ cat source/usage.rst 
U & e
=====
...

[chester-leung]

@astrojuanlu I meant that when sphinx builds the rst, it replaces the & character with ² in the resulting HTML. Is this not the case for you?

[astrojuanlu]

Yes, it looks fine to me on the HTML 🤔

[tk0miya]

At present, toctree directive does not support markups for titles. It would be nice if we support it. But we need to rewrite whole of ToC data structure. Contributions are welcome :-)

[ahorn42]

@tk0miya could you point out, which components might need some rework for this as a starting point? I am potentially interested in using replacements in a toctree title.

[picnixz]

~~(tk0miya is no more active, so I'll answer instead)~~

@ahorn42

If you want to help, I think having a look at the TocTree directive in sphinx/directives/other.py would be good. Then, you need to see where and how the nodes being generated are used. I suggest using an IDE with a good support for 'following symbols/implementation'.