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.

[*]	This is a sidenote.

Frankly, for some Hugo-based blogs, reStructuredText may be overkill. But others may crave a clean solution that can ^superscript and _subscript without calling out to LaTeX. One that handles inline images (). One that understands the difference between a pull-quote and epigraphs. One that wraps text around images flushed either to the right or the left, and supports more formal figures when images need annotations. One that also manages citations [ReST], footnotes[1], and even sidenotes[*] expertly, One that can also enable sidebars to handle related thoughts. All in human-readable plain-text markup, without new Hugo codewords, or additional helper projects.

This Hugo Restructured 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 display of articles, and the CSS provided understands all 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.

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

Why reStructuredText

Hugo, with Goldmark and Blackfriday markdown processors already built in, why then should one bother with something beyond the default configuration? Why not work with these markdown extensions or take advantage of Hugo's shortcodes to implement features such as figures.

Because reStructuredText supports most, if not all, of these same features – but does so in a single, mature, consistent system that is in wide use for projects that scale up to even some of the most sophisticated documentation systems.

Rather than live with several different sets of implementations across several layers of the Hugo stack, take advantage of a supported input markup that was designed to do all of this within one well thought out system.

Because reStructuredText is both scalable and extensible, the degree of support it offers for many of these features is far more robust than many other solutions. One example above covers reStructuredText's support not just for footnotes, but also sidenotes and a parallel citations reference system. In the same vein, there is not just one table syntax, there are three different ways to build tables in markup. Again showing depth of implementation, reStructuredText supports both bare images as well as figures that have legends – legends that can have within all manner of markup: citations, quotations, even tables. Similarly, reStructuredText has several forms of blockquotes, enabling different display styles from an attention-grabbing pull-quote to a more understated epigraph.

Also because since reStructuredText follows a consistent design, it is possible to create a Hugo-centric CSS that allows useful concepts to be applied to whole ranges of elements. With this system, not only is it possible to flush an image over to the left or the right and have the main text wrap around, that same treatment can be applied to all sorts of elements from tables-of-contents to pull-quotes or 'warning' admonitions.

Some of the differences come from attention to details. Since reStructuredText is careful about the kind of HTML that it generates, there is greater support for the semantic-web features in HTML. For example, most web browsers use the same italics-based method of display for <EM> and <CITE> tags in HTML so it often doesn't matter whether a string was italicized for emphasis or for citation, but reStructuredText does know the difference and enables an author to write material that will be better recognized by a semantic browser.

On a related note, because the underlying HTML takes care to be correct, Hugo Restructured is setup to load and utilize explicitly particular weights and styles for the typeface used. So a page's italics will be rendered with the best oblique slanting the type designer could define rather than a browser's attempt to tilt each character on the fly – and the bold will be loud and proud, not just big and blurry.

End Thought

There are ways to accomplish most of the same features in other Hugo setups. For those who may appreciate the difference, the use of reStructuredText enables Hugo Restructured to offer all of these features within one stable, self-consistent system.

---

[1]	Yes, this is a footnote. The label of this footnote contains a link to return back to the footnote reference.

[ReST]

reStructuredText Documentation, https://docutils.sourceforge.io/rst.html