Create selective custom style using classes

If specific HTML elements (e.g. tables or lists) need to be styled differently as the output theme defines, a custom CSS file (e.g. custom.css) is used. However, this will then apply to all these elements, not a custom selection.

To apply a certain style to a manually configurable selection of element types, the class option can be used.

Example: Custom table

1. Create the element using the respective directive, e.g.:

   .. list-table:: USS Enterprise, Private Quarters Location
       :header-rows: 1
   
       * - Name
         - Quarter Location
       * - Jean-Luc Picard
         - Deck 5, Cabin 1
       * - Geordi La Forge
         - Deck 4, Cabin 12
   

2. Add the class option to the directive, here :class: red_header:

   .. list-table:: USS Enterprise, Private Quarters Location
       :header-rows: 1
       :class: red_header
   

3. You may build the HTML doc to easier extract the CSS path. You will see that the element has the specified name among its class attributes (e.g. class="red-header docutils align-default").

4. Define the style in your custom.css file, for example:

   .red-header thead tr.row-odd {
       background-color: #e60000;
   }
   

5. Build the HTML doc again. The style is now applied. In our example, the styled variant will render as

   USS Enterprise, Private Quarters Location

   Name	Quarter Location
   Jean-Luc Picard	Deck 5, Cabin 1
   Geordi La Forge	Deck 4, Cabin 12

   whereas the un-styled tables renders as

   USS Enterprise, Private Quarters Location

   Name	Quarter Location
   Jean-Luc Picard	Deck 5, Cabin 1
   Geordi La Forge	Deck 4, Cabin 12

Hint

You may add the same class option to any other compatible element you like to apply this style on. All docutil elements support the class option, although some styles rules might depend on a specific element type.

Hint

You can add multiple classes to one element, e.g.

.. list-table:: USS Enterprise, Private Quarters Location
    :header-rows: 1
    :class: red_bg_header, last_row_green_bg, italic_font

It’s better to add multiple classes with lesser style than a single class with lots of style.

Appendix: Custom admonition

Docutils features several admonitions. But it might become necessary to create additional ones, since none of the existing fit or a different style is needed for better understanding.

The steps are explained via an example, which demonstrates the creation of admonition for a Problem definition (for example used within a troubleshooting section).

1. Define the admonition:

   .. admonition:: Problem
       :class: problem
   
       Some content for the custom problem admonition which is not important here.
   

   This translates to the following HTML:

   <div class="problem admonition">
     <p class="admonition-title">Problem</p>
     <p>
       ::before
       Some content for the custom problem admonition which is not important here
     </p>
   </div>
   

2. Define the style for the custom admonition in the custom.css file, for our example (defining a red title background):

   .rst-content .problem .admonition-title {
       background: #ff9999;
   }
   

3. Define a custom symbol for the admonition. The default symbol, if any, is defined by the used HTML theme (default in sphinx-rtd-theme: exclamation mark). As sphinx-rtd-theme supports FontAwesome symbols, any freely available icon from https://fontawesome.com/icons can be used.

   1. Visit https://fontawesome.com/icons and find a suitable icon (make sure the Free filter is selected).

   2. Select the chosen icon and select 🔔 (Copy Glyph) to copy its glyph representation.

   3. Add an additional CSS rule to custom.css, in our example:

      .rst-content .problem .admonition-title::before {
          content: "";
      }
      

   4. Put the copied glyph (here: triangle-exclamation) into the content attribute between the quotes.

      Important

      It is possible, that the used editor is not able to display the characters and enters a simple square (for example � or ) as a replacement character. That does not mean, the browser won’t be able to display it.

   Important

   Apply Unicode symbol (for other sphinx themes)

   Not every theme supports FontAwesome symbols, but can still display any Unicode symbol.

   1. Visit https://symbl.cc/en/ and search for a suitable symbol.

   2. Copy the CSS Code of the symbol (for example \2615).

   3. Add a new CSS rule to custom.css, in this example:

      .rst-content .problem .admonition-title::before {
          content: "";
      }
      

   and add the copied CSS code between the quotes, for example:

   content: "\2625"
   

4. Build the HTML documentation. The admonition defined in step 1 should render to

   Problem

   Some content for the custom problem admonition which is not important here.