Hugo and reStructured Text
Hugo supports reStructuredText as one of the additional formats for input markup.
OK. So what?...
Markup syntax that is readable and simple, yet powerful enough for non-trivial use.
—reStructuredText Documentation
reStructuredText Demo
reStructuredText is a plaintext markup developed by people who write documentation as their primary job. As described in the project goals, the desire was "to design a markup syntax [...] that is readable and simple, yet powerful enough for non-trivial use." This is a markup that can comfortably handle a large range of tasks which frustrate the simpler systems and yet it retains the direct utility of a markup based on easy-to-read plain text.
Frankly, for many Hugo-based blogs, reStructuredText may be overkill.
But some of us crave a clean solution that can
superscript and subscript without calling out to LaTeX,
handle inline images (
),
understand the difference between a pull-quote and epigraphs,
flush images to either the right or the left,
even support more formal figures when images need annotations,
also handle footnotes[1] and citations expertly,
as well as manage sidenotes to display related thoughts.
All in human-readable plain-text markup,
without new Hugo codewords, or additional helper projects.
This Restructuredtext Hugo theme works with the HTML generated by the docutils package that is supported within Hugo's additional helpers. The templates in this theme provide straightforward displays of articles, and the CSS provided understands each of the features of the generated HTML.
Predictably, demonstrating too many features within a short webpage leads to overly cluttered looking results. Nevertheless, it is hoped this sample still offers an intriguing taste of what can be done with reStructuredText in Hugo. As a shortcut to providing more complete examples, the other postings in the rest section of this site are copies of documents straight from the reStructuredText reference materials. All of these reference materials work well in this Hugo theme pretty much as is, no notable changes are required.
Everything should be as simple as it can be, but not simpler.
—Albert Einstein as quoted by Roger Sessions, 1950.
Make it easy to read.
—Roger Black
Implementation Details
reStructuredText, and the entire Docutils system, is both powerful and flexible, capable of generating entire volume-sets of documentation. Here we are focusing these tools on the relatively simple needs of blog-centric Hugo, but while blog content is relatively simple the audience for this content often encompasses a much wider variety of browser environments.
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 vistors 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 adapt its absolute size to match the relative size of the column in the user's browser display. Specifying a fixed pixel width for figures can lead to problems as browsers adapt to different window sizes.
Repeat of the movable type picture, this time without including the :width: 100% option; note how the image may extend outside the column when the browser window is made smaller.
Furthermore, providing an additional :width: 100% option to the figure definition provides the detail necessary to ensure that the image within the figure will be scaled to the best size to remain constrained within the figure's full area. The figure here to the right is an example of what happens if the the :width: 100% option is left out. This image to the right is identical to the image near the top right of this article, and this figure definition is the same except for lacking the :width: option; the difference is the image is no longer constrained to fit within the figure boundaries.
Overriding the Sidebar Directive
The CSS used here includes a small tweak for sidebars: an option for wide or narrow sidebars.
Adding a :class: titleless option to a topic, sidebar, or admonition directive will supress 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 be 20% (narrow) or 40% (default) or 60% (wide) of the width of the column.
Predictably, demonstrating too many features within a short webpage leads to overly cluttered looking results.
Furthermore, several of the directives, notably the admonition and topic directives, by specifying an optional :class: sidebar to the markup can be given a "sidebar" treatment rather than their default front-and-center appearance. 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 short webpage leads to overly cluttered looking results.
Code Highlighting
The Docutils package that manages reStructuredText does support syntax highlighting with Pygments. If the argument to the code directive is a language understood by the version of Pygments installed on the Hugo system, then the block will be generated with reasonably classified inline elements.
The Docutils parser is independent of the default Hugo markdown parser and hence does not invoke Hugo's default syntax highlighting, and so does not include the Chroma highlighter that is part of the more recent releases of Hugo.
Full support for syntax highlighting may come if/when there is a native Go implementation of reStructuredText. Unfortunately, while there are different implementations of reStructuredText in Go, none has yet reached sufficient maturity to be included in Hugo and the ticket for this enhancement request was closed in late 2017 for lack of activity.
1 def my_function(): 2 "just a test" 3 print 8/2
If Pygments was successfully installed on the Hugo system,
the snippet of Python code above should have some syntax highlighting.
Inline code is also supported,
for example: print "some highlight"
would be formatted in similar coloring to the block above.
| [1] | Yes, this is a footnote. |