A theme for Hugo that takes advantage of reStructuredText as the input markup.
See the live demo.
Features
- Responsive page layout (scales from 300 to 1300 pixels wide)
- Supports reStructuredText markup features
Including
- Images and figures, both right- and left-aligned
- Footnotes and citations
- Pull-quotes, and epigraphs
- Sidebars (implemented in narrow, standard, and wide forms)
- Admonitions and topics, notably topics containing a table of contents
- Support for inline Math and Code directives directives
- Tables, including reStructuredText's alternative markup: list-tables, field lists, and bibliographic fields
Also
- Pages begin with a splash of color with support for hero images or background gradients
All of these features and more are demonstrated in the live demo.
Installation is much like any other Hugo theme.
Obviously you'll need a working Hugo environment.
In addition, to handle the reStructuredText you'll need Docutils (which relies on Pygments for the colored syntax highlighting in code displays). Both of these are readily available through the usual Python methods (e.g. "pip install docutils").
Inside the folder of your Hugo site run:
$ cd themes
$ git clone https://github.com/fisodd/hugo-restructured.git
For more information read install and use themes or begin with Hugo's get started help page.
Inside the
exampleSite
folder of this theme, there is a file called
config.toml.
Use this configuration as an example,
and modify to suit your needs.
Hugo recognizes files ending with a ".rst" suffix as reStructuredText and will call out to the docutils python package to process these files.
example:
$ hugo new content/post/first-post.rst
To learn more about reStructuredText markup, start with a reStructuredText Primer.
The top part of each page has an area of color or potentially an image.
For any page or post you can specify a hero image for this area
by including the local path in front matter
(see content in the exampleSite folder for examples):
hero_image: '/images/gohugo-default-sample-hero-image.jpg'
An image is not required. The hero background can also be configured by the 'hero_shade' setting. The 'hero_shade' setting in the front matter can take a full CSS background definition, and can be used to set any HTML color, or even use a gradient instead by specifying a linear gradient.
example: hero_shade = "background: linear_gradient(to right, blue, pink);"
In order to see your site in action, run Hugo's built-in local server.
$ hugo server
Now enter localhost:1313 in the address bar of your browser.
This theme is released under the MIT License.
The specifics can be found within the License
The author learned most of what he has learned about Hugo themes by studying the excellent example of the Ananke theme. I am very grateful for the clean implementation and the helpful comments.
Also, many, many thanks to all the folks who make Hugo rock.