Open LLM text
Share with AI
Ask Claude Ask ChatGPT Ask Copilot

rst.html

learn how to use the RST rendering shortcode

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
NameAgeOccupationBiography
Alice30Data ScientistAlice has over 10 years of experience in data analysis and has published multiple papers on machine learning.
Bob25Graphic DesignerBob is an award-winning graphic designer specializing in digital art and user interfaces.
Charlie45EngineerCharlie has worked in various engineering fields, including mechanical and electrical engineering, for over 20 years.
Dana38PhysicianDana, an expert in pediatric medicine, has been practicing for 15 years and has contributed to several healthcare journals.
rst
.. 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

golang
{{- $path := .Get 0 -}}
{{- $fullPath := printf "content/%s.rst" $path -}}
{{- $resource := resources.Get $fullPath -}}
{{- $content := "" -}}

{{- if $resource -}}
    {{- $content = $resource.Content -}}
{{- else -}}
    {{/* Fallback: try reading directly from file system */}}
    {{- $content = readFile $fullPath -}}
    {{- if not $content -}}
        {{- errorf "RST shortcode: File not found in assets/%s or directly in the file system at %s on page %s" $fullPath $fullPath .Page.RelPermalink -}}
        <div class="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded mb-4">
            <strong>RST Error:</strong> File "{{ $fullPath }}" not found.
        </div>
    {{- end -}}
{{- end -}}

{{- if $content -}}
    {{- $opts := dict "markup" "rst" -}}
    {{- $rendered := .Page.RenderString $opts $content -}}
    {{- $rendered | safeHTML -}}
{{- end -}}