rst.html

The {{%rst%}} shortcode a tool for rendering reStructuredText content in your Hugo site. This is useful for maintaining complex information such as tables, code blocks, and other elements that are difficult to maintain in Markdown.

Before you start

  • Create a requirements.txt file at the root of your Hugo project and add rst2html;
  • Ensure that you install the rst2html5 tool on your system to use RST in Hugo. You can install it using pip install docutils.
  • To render RST in Hugo, add '^rst2html.py$' to the security.exec.allow parameter in your configuration. You can see an example of this in the theme’s config details at config/_default/security.yaml.

How it works

Table

{{<csv "shared/rst/table">}}

List Table Example
Name Age Occupation Biography
Alice 30 Data Scientist Alice has over 10 years of experience in data analysis and has published multiple papers on machine learning.
Bob 25 Graphic Designer Bob is an award-winning graphic designer specializing in digital art and user interfaces.
Charlie 45 Engineer Charlie has worked in various engineering fields, including mechanical and electrical engineering, for over 20 years.
Dana 38 Physician Dana, an expert in pediatric medicine, has been practicing for 15 years and has contributed to several healthcare journals. 
.. list-table:: List Table Example
   :widths: 20 20 30 30
   :header-rows: 1

   * - Name
     - Age
     - Occupation
     - Biography
   * - Alice
     - 30
     - Data Scientist
     - Alice has over 10 years of experience in data analysis and has published multiple papers on machine learning.
   * - Bob
     - 25
     - Graphic Designer
     - Bob is an award-winning graphic designer specializing in digital art and user interfaces.
   * - Charlie
     - 45
     - Engineer
     - Charlie has worked in various engineering fields, including mechanical and electrical engineering, for over 20 years.
   * - Dana
     - 38
     - Physician
     - Dana, an expert in pediatric medicine, has been practicing for 15 years and has contributed to several healthcare journals.

Source code 

{{- $path := .Get 0 -}} <!-- Get the path from the shortcode argument -->
{{- $content := readFile (print "content/" $path ".rst") -}} <!-- Read the RST file content -->
{{- $opts := dict "markup" "rst" -}}
{{- $table := .Page.RenderString $opts  $content -}} <!-- Render the RST content as HTML -->
{{- $table | safeHTML -}} <!-- Output the HTML content -->
prod.html tabs.html