Using Hugo Restructured
Using Hugo Restructured, by Alexander Carlton,

Using reStructuredText in Hugo

Hugo does support reStructuredText as one of the additional formats in Hugo. However, there is not a lot of documentation about how to use reStructuredText (or ReST) in a Hugo setup.

The Hugo and reStructuredText post provides a decent example of what can be done with this setup. What follows here is some basic information and details not covered in that demonstration page.

reStructuredText Background

/img/rst-rotated.png

By default, Hugo uses markdown syntax as the input markup, and this offers several extensions to the deliberately simplistic markdown syntax.

Rather than use extensions to what was defined to be simple, working with Hugo and reStructuredText enables the same clean workflow that a plaintext markup language provides but with a markup language that was designed from the start to handle far more than a simple blog page.

For example, BlackFriday and other markdown processors have added a form of footnotes to the original syntax. reStructuredText not only defined a clean footnote syntax, this syntax can separate sequences of footnotes (one set numbered[1], the other set tracked by a series of symbols[*]) and even support a separate set of citation references [ReST] as is done for academic journals. Hence, as has been done for the notes in this paragraph, it is possible to have a set of notes that are defined at the end of the page and another set of notes that are defined and displayed inline with the content.

Perhaps much more relevant to a Hugo audience, reStructuredText provides support for a variety of useful features for those who would like to move beyond just a column of text. reStructuredText supports both images as well as figures (images that have a caption or legend associated with the image), sidebars (independent threads of text that are formatted into a separate column next to main running text), also pull quotes which are different from epigraphs, as well as admonitions (call out boxes for tips or warnings).

reStructuredText also offers a clean way to specify additional parameters for each elements in an article. With this, there is a standard way for an author to specify that a figure is to be flushed to the left, or the right, rather than centered in the column. This also allows us a way to specify if a sidebar is narrow, or extra wide.

Learning reStructuredText

The basics of reStructuredText is not very different from any other plaintext markup, so it is easy to get started. Separate paragraphs with blank lines, use an asterisk pattern such as *emphasis* to mark emphasis, use double asterisks such as **bold** to be bold.

Much of the basics are demonstrated in the Quick Start Guide and are covered in the Quick Syntax Overview.

Perhaps the most difficult concept in basic reStructuredText is how hyperlinks are formatted. To enable better readability of the raw text, in reStructuredText hyperlinks are treated like footnotes and citations; the main text just has a reference to a link, and the ugly details of the URL itself is defined elsewhere in the document.

The full power of reStructuredText comes in its extensible Directives such as Figures and Tables. By use of a specific syntax for these directives, it is easy to specify different options for each use, and the same system allows implementations to define extensions such as Hugo Restructured's narrow and wide options for sidebars.

/img/rst.png

Hugo Specific Extensions

reStructuredText, and the entire Docutils system, is both powerful and flexible, capable of generating entire volume-sets of documentation. Hugo Restructured focuses Docutil's tools on the relatively simple needs of blog-centric Hugo – but while the content for blogs may be relatively simple compared to a documentation system's more typical material, difficulties arise from the reality that the audience for blog content often encompasses a much wider and richer variety of browser environments.

The CSS provided with Hugo Restructured is based on the HTML generated by Docutils. Any content that follows reStructuredText definitions should be well handled.

There are a few areas where this shift of focus and emphasis can be greatly assisted if the authors respect a few details in the markup they write. Since reStructuredText is designed to be extensible, many useful effects can be achieved through existing CSS definitions with nothing more than a bit of care to define a few optional values when using some of the more powerful directives.

Making Figures Responsive

The HTML generated by the Docutils that support reStructuredText is generally constructed well enough to be adaptable to a wide range of usages. However, being specific in the markup can help make the figures more responsive to mobile visitors and the many varieties of browser display sizes.

/img/rst.png

Specifically, for the figure directives it may help to specify a :figwidth: option as a percentage, e.g. 30%, as this allows the figure to scale the image's display size to match the relative size of the column in the user's browser display. Note: Specifying a fixed number of pixels as the width for figures can lead to problems as browsers adapt to different window sizes.

In addition, providing an additional :width: option, even :width: 100% just to restate the desire to use 100% of the width, provides a necessary definition so that the image can be constrained to remain within the figure's defined space. Without this additional :width: option, images may spill out beyond the figure to either obscure the other content or run off the far edge of the page.

Sidebars

reStructuredText defines a sidebar directive that creates a side channel of content with a title that can be displayed alongside the main column of the article.

Overriding the Sidebar Defaults

Hugo Restructured enables a sidebar-like treatment for several other elements. Pull-quotes, admonitions, and topics can be given the same treatment if they are defined to include a class of "sidebar". Thus these items can be shifted from their usual placement across the entire width of the column to instead become floating elements beside the main body of content.

Adding a :class: titleless option to a topic, sidebar, or admonition directive will suppress the display of that block's title. This is occasionally helpful when a block's title ends up being more distracting than useful.

Add a :class: narrow or :class: wide option to the sidebar definition and the matching CSS specification will be used, so sidebars can be made to target 20% (narrow) or 40% (default) or 60% (wide) of the width of the column.

Furthermore, several of the other directives, notably the admonition and topic directives, can be given a "sidebar" treatment rather than their default front-and-center appearance. Just by specifying an optional :class: sidebar to the directive's definition. This can be useful for those cases where the author chooses to place less emphasis on the material in the directive.

Finally, if a full-size pull-quote is too much, the CSS provided with this theme enables this same "sidebar" treatment of pull-quotes. However, the markup syntax is a bit more cumbersome since the definition for pull-quote in reStructuredText does not include optional arguments. Still, the use of reStructuredText's class directive will assign the specified class to whatever is the directive that follows.

.. class:: sidebar align-left

.. pull-quote::
   Predictably, demonstrating too many features within a single webpage
   leads to overly cluttered looking results.
/img/rst-rotated.png

Left and Right Alignments

The figure and image directives already understand :align: left and :align: right options. Hugo Restructured's CSS implements the means to push these elements flush left or flush right and allows the main text to flow around these elements.

Tip

Admonitions can be pushed to the left.

Additionally, Hugo Restructured's CSS enables similar treatments for sidebar, admonition, and pull-quote elements whenever these elements are given a class parameter of align-left or align-right.

.. admonition:: Tip
   :class: align-left

   Admonitions can be pushed to the left.

Code Displays

As has been demonstrated elsewhere in this page, Hugo Restructured includes support for code blocks.

The Docutils package that implements reStructuredText utilizes the Pygments package to perform parsing and marking of code blocks – this is the same package that Hugo used prior to switching to the Go-native Chroma code processor.

Hugo Restructured's CSS implements a somewhat muted coloring based on Pygment's "lovelace" style. Those that are interested, the CSS can be replaced by a different style. Because Docutils uses the "long-form" option for class names this does mean that Pygment's default method of generating style definitions does not work directly – the short class names need to be swapped with the longer class names that by default show in the comments.

Something like the following Unix script can be useful to get suitable CSS:

#!/bin/bash

style=$1
if [ "$style" = "" ]
then
        echo "Need to specify a style name that Pygments recognizes"
        exit 1
fi

regularexpression='s/^\.(\w+) \{ (.*) \} \/\* (.*) \*\//.\L$3 { $2 } \/* $1 *\//'
        # first match: a character string after a period at the beginning
        # second match: the stuff between the curly braces
        # third match: the stuff between the comment markers
        # output: lower case of 3rd match, 2nd inside braces, 1st in comment


pygmentize -f html -S $style | perl -pe "$regularexpression"

exit $?

Hugo Restructured's Classes

Along the way there have been a few potentially useful classes added to Hugo Restructured's CSS.

Classes for Sidebars

As noted above, sidebars (and other elements that can be given a sidebar class) can have additional classes added to their definition to enable potentially useful effects.

The complete list of optional classes for sidebars is below.

align-left
By default sidebars are flushed right, with a class of align-left the specified sidebar item will be flushed left. Works similarly to figures that specify an option of :align: left.
align-right
This can override a left leaning item to instead be flushed right.
align-center
Let an element span the width of the available column with its content centered in the available space.
titleless
Suppresses the visibility of a title; sometimes useful with the sidebar directive that insists that every properly defined sidebar must display a title.
narrow
Reduce the width of the sidebar from 40% to 20% of the main column.
wide
Expand the sidebar to cover 60% of the main column.

Bulletless Lists

For those cases where a fully formatted list is over kill (and perhaps would not fit in a narrow sidebar), a list can be given the class bulletless which would lead the list being formatted without bullets and with a notably smaller amount of indentation.

Responsive Lists

By default, the indentation for a nested list is a fixed amount of pixels – which can be a problem on small devices, especially if the list is attempting to fit within a sidebar or other place where width is limited.

The CSS for Hugo Restructured implements a responsive class for lists which will drop the bullets from an unnumbered list and will shrink the amount of indentation.

This is the difference between:

  • One
    • Two
      • Three

and (which will look the same unless the browser display is narrow):

  • One
    • Two
      • Three

implemented as:

.. class:: responsive

* One
   * Two
      * Three

This CSS does recognize attempts to place a table of contents in a sidebar and will use this responsive form in those cases.

Responsive Tables

When the display gets narrow (such as on some mobile devices) some standard HTML tables become difficult to read. For example, tables that have many columns:

Mon Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
°C 5 7 9 11 14 16 19 19 17 13 10 7
°F 41 45 48 52 57 61 66 66 63 55 50 45

These may not fit into narrow displays – resulting in page content that runs off the end of the display and hence cannot be seen at all. In the more severe cases it may be necessary on small devices to reorient a wide table in more of a long-list format so that small screens can scroll through the entire content. Hugo Restructured add an optional responsive class for table definitions that will trigger an alternative display when the browser display is very narrow.

The table below is a copy of the table above with the addition of this responsive class to the definition. Notice that the table format will be displayed differently when the width of the browser is recognized to be narrow.

Mon Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
°C 5 7 9 11 14 16 19 19 17 13 10 7
°F 41 45 48 52 57 61 66 66 63 55 50 45

Responsive tables in markup is something of a cure for a corner-case that is probably best avoided rather than addressed. Still, there are cases where this kind of transformation can be useful, so Hugo Restructured offers this as a simple solution that perhaps may help.


[1]This is a numeric note, implemented as a traditional footnote (shown at the end of the page). The footnote label is a link to return back to the previous part of the page.
[ReST]reStructuredText Documentation, https://docutils.sourceforge.io/rst.html