64

I'm writing some documentation using ReStructuredText (ReST) format for the later web-page generation using Sphinx, and I cannot find a way to write some "bold italic" text.

There are markers for the so-called 'emphasis' (italic) and 'strong emphasis' (bold) text. They are *italic text* and **bold text** respectively. I also read in some documentation on this format that these formatting markers cannot be simply "nested". I.e. the ***text*** (or ** *text* **) does not produce the bold italic text.

Still there probably should be some way to produce a text emphasized both with bold and italic markers, since it is a widespread practice to mark pieces of text that way.

3 Answers 3

45

Although Markdown supports nesting bold and italic, reStructuredText does not (this is one of the rare cases where Markdown is more powerful, as there is no way to represent bold italics in reStructuredText).

Quote from this Gist: https://gist.github.com/1855764

3
  • 22
    one of the rare cases, but an important one!
    – Dacav
    Commented Aug 30, 2013 at 14:26
  • 8
    Nope, this is incorrect ("there is no way to represent bold italics in reStructuredText"). There are actually several different methods (as pointed out by other respondents). I shall agree - though - that it is unfortunate this is not supported "out of the box" by mean of triple * on either side of the string...
    – mac
    Commented Nov 20, 2014 at 17:03
  • Since html(5) supports nesting of strong (bold) and emphasized tags, I do not really understand why reStructuredText does not support it. This is also a disadvantage when I have written an emphasized sentence with some words in monospaced (double backtick) in it. In RST every mixed text snippet with italic must be enclosed in '*' characters.
    – Rob
    Commented Apr 13 at 11:23
24

Recipe for HTML output.

my.rst:

.. role:: red
  :class: red

.. role:: bolditalic
  :class: bolditalic

:red:`WARNING` :bolditalic:`Don't be stupid!`

my.css:

.red { color: red; }
.bolditalic {
  font-weight: bold;
  font-style: italic;
}

Build by:

rst2html --strip-comments --halt warning --stylesheet=my.css my.rst my.html
19

In sphinx this is possible through custom roles: You make a style in css, and make a role pointing to that style. Here's an full working example of underlined text: sphinx-dev thread.

Edit:

Here's a good example: ReST strikethrough

Edit 2:

That sphinx-dev link is not available any more, so here's the gist, it very similar to the strikethrough link above:

CSS:

span.underlined {
  text-decoration: underline;
}

Register role in RST:

.. role:: underlined
   :class: underlined

to use it later as

:underlined:`test`

All this can be in a single RST document:

.. raw:: html

   <style type="text/css">
     span.underlined {
       text-decoration: underline;
     }
   </style>

.. role:: underlined
   :class: underlined

:underlined:`test`

Test it with::

rst2html5.py test01.rst test01.html
2
  • Unfortunately the sphinx-dev thread link redirects back to the group.
    – LeoRochael
    Commented Apr 25, 2019 at 14:23
  • GOTCHA: Underscore _ in class roles are transformed in the build to hyphens - so best not use them AFAICT... Commented Mar 10 at 13:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.