The "B side", for some folks old enough to remember, was the flip-side of a vinyl record. In those days, most of the attention and hype was focused on the A side, and the B side of a record often contained the "other" music – the stuff perhaps intended for a slightly different audience, an audience that might be seeking something a bit deeper and more interesting.

Hugo B-side is not necessarily the "hit" solution for Hugo sites. But it might be worth considering for those looking to go beyond the basics and spend time with something that supports a richer feature set.

The main visual difference of Hugo B-side is the heavy use of the sidebar: a second column available for notes, for other images, or whatever. With side-by-side placement of the main thought and the side comment (together, but not mixed-up together) the author is able to offer the reader multiple views of a subject without forcing the reader to interrupt the main focus. An example of this effect can be seen in the Tufte page which is derived from the "Tufte CSS" example page.

The other significant difference is that Hugo B-side is based on reStructuredText for markup since the common markup formats do not support a reasonable method for denoting what content is primary and what content belongs in the secondary space. Some of what is possible with reStructuredText can be seen in the Hugo and reStructuredText page.

Using reStructuredText in Hugo

Hugo does support reStructuredText as one of the additional formats; 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


By default, Hugo uses BlackFriday 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, the goal of working with Hugo and reStructuredText is to enable the same clean plaintext-based workflow 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], another 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 alongside 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 B-side's fullwidth and sidebar options for figures.


Hugo Specific Extensions

reStructuredText, and the entire Docutils system, is both powerful and flexible, capable of generating entire volume-sets of documentation. Hugo B-side focuses Docutil's tools on the relatively simple needs of blog-centric Hugo – with the added feature of a responsive page design that will adapt the elements to suit each browser environment.

The CSS provided with Hugo B-side 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.


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 pixel 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.


This Hugo B-side theme is based on the idea that each article shall have a main column and a sidebar where notes and smaller images and other secondary materials can be placed.

reStructuredText defines a sidebar directive, and Hugo B-side will use that extra space on the right side for all elements within that directive, and all elements given a option of sidebar.

Overriding the Sidebar Defaults

Hugo B-side 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.

Left and Right Alignments

The figure and image directives already understand :align: left and :align: right options. Hugo B-side's CSS implements "right" by placing the figure or image in the sidebar, and "left" is done by flushing the figure/image to the left edge and flowing the main text around.


Admonitions can be pushed to the sidebar. On displays where there is no sidebar, the admonition will span the main column.

Additionally, Hugo B-side'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 sidebar.

Finally, Hugo B-side implements a fullwidth option which will allow an element to span across both the main column and the sidebar space – designed to manage larger images, this can also be useful sometimes for admonitions or pull-quotes and the like.

Code Displays

As has been demonstrated elsewhere in this page, Hugo B-side 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 B-side'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:


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

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 B-side's Classes

Along the way there have been a few potentially useful classes added to Hugo B-side'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.

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.
This can override a left leaning item to instead be flushed right.
Let an element span the width of the available column with its content centered in the available space.
Suppresses the visibility of a title; sometimes useful with the sidebar directive that insists that every properly defined sidebar must display a title.
Reduce the width of the sidebar from 40% to 20% of the main column.
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 B-side 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 B-side 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 B-side 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,