markup/rst: Make syntax highlighting configurable

Add markup.rst.syntaxHighlight and pass Docutils' --syntax-highlight option only when configured away from the rst2html default.

Fixes #5349

Author: xndvaz

docs/content/en/configuration/markup.md

@@ -304,6 +304,19 @@ Run `hugo build --logLevel debug` to examine Hugo's call to the Asciidoctor exec
 INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
 ```
 
+## reStructuredText
+
+This is the default configuration for the reStructuredText renderer:
+
+{{< code-toggle config=markup.rst />}}
+
+### reStructuredText settings explained
+
+syntaxHighlight
+: (`string`) The token name set passed to Docutils' `--syntax-highlight` option, one of `long`, `short`, or `none`. Default is `long`.
+
+  To highlight code blocks, Docutils must be able to import [Pygments].
+
 ## Highlight
 
 This is the default configuration.
@@ -359,6 +372,7 @@ ordered
 [Pandoc]: https://pandoc.org/
 [PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
 [PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
+[Pygments]: https://pygments.org/
 [reStructuredText]: https://docutils.sourceforge.io/rst.html
 [security policy]: /configuration/security/
 [subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub

docs/content/en/content-management/formats.md

@@ -118,7 +118,17 @@ Hugo passes these CLI flags when calling the rst2html executable:
 --leave-comments --initial-header-level=2
 ```
 
+To use short syntax highlighting class names, configure the reStructuredText renderer:
+
+{{< code-toggle file=hugo >}}
+[markup.rst]
+syntaxHighlight = 'short'
+{{< /code-toggle >}}
+
+Docutils requires [Pygments] to highlight code blocks.
+
 [Docutils]: https://docutils.sourceforge.io/
+[Pygments]: https://pygments.org/
 [reStructuredText]: https://docutils.sourceforge.io/rst.html
 
 ## Classification

docs/data/docs.yaml

@@ -1366,6 +1366,8 @@ config:
       style: monokai
       tabWidth: 4
       wrapperClass: highlight
+    rst:
+      syntaxHighlight: long
     tableOfContents:
       endLevel: 3
       ordered: false

hugolib/rst_integration_test.go

@@ -0,0 +1,61 @@
+// Copyright 2026 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package hugolib
+
+import (
+	"runtime"
+	"strings"
+	"testing"
+
+	qt "github.com/frankban/quicktest"
+	"github.com/gohugoio/hugo/markup/rst"
+)
+
+func TestRSTSyntaxHighlightConfigIssue5349(t *testing.T) {
+	if !rst.Supports() {
+		t.Skip("rst not installed")
+	}
+
+	execAllow := `'^rst2html(\.py)?$'`
+	if runtime.GOOS == "windows" {
+		execAllow = `'^python(\.exe)?$'`
+	}
+
+	files := strings.ReplaceAll(`
+-- hugo.toml --
+baseURL = "https://example.org"
+disableKinds = ["home", "section", "taxonomy", "term", "rss", "sitemap"]
+[security.exec]
+allow = [RST_EXEC_ALLOW]
+[markup.rst]
+syntaxHighlight = 'none'
+-- layouts/page.html --
+{{ .Content }}
+-- content/p.rst --
+---
+title: p
+---
+
+.. code:: go
+
+   if true {}
+`, "RST_EXEC_ALLOW", execAllow)
+
+	b := Test(t, files)
+	content := b.FileContent("public/p/index.html")
+	b.Assert(content, qt.Contains, `if true {}`)
+	b.Assert(content, qt.Not(qt.Contains), `Pygments package not found`)
+	b.Assert(content, qt.Not(qt.Contains), `<span class="keyword">if</span>`)
+	b.Assert(content, qt.Not(qt.Contains), `<span class="k">if</span>`)
+}

markup/markup_config/config.go

@@ -19,6 +19,7 @@ import (
 	"github.com/gohugoio/hugo/markup/asciidocext/asciidocext_config"
 	"github.com/gohugoio/hugo/markup/goldmark/goldmark_config"
 	"github.com/gohugoio/hugo/markup/highlight"
+	"github.com/gohugoio/hugo/markup/rst/rst_config"
 	"github.com/gohugoio/hugo/markup/tableofcontents"
 	"github.com/mitchellh/mapstructure"
 )
@@ -39,6 +40,9 @@ type Config struct {
 
 	// Configuration for the AsciiDoc external markdown engine.
 	AsciiDocExt asciidocext_config.Config
+
+	// Configuration for the reStructuredText external markdown engine.
+	RST rst_config.Config
 }
 
 func (c *Config) Init() error {
@@ -119,4 +123,5 @@ var Default = Config{
 
 	Goldmark:    goldmark_config.Default,
 	AsciiDocExt: asciidocext_config.Default,
+	RST:         rst_config.Default,
 }

markup/markup_config/config_test.go

@@ -39,6 +39,9 @@ func TestConfig(t *testing.T) {
 				"safeMode":             "save",
 				"extensions":           []string{"asciidoctor-html5s"},
 			},
+			"rst": map[string]any{
+				"syntaxHighlight": "short",
+			},
 		})
 
 		conf, err := Decode(v)
@@ -50,6 +53,7 @@ func TestConfig(t *testing.T) {
 
 		c.Assert(conf.AsciiDocExt.WorkingFolderCurrent, qt.Equals, true)
 		c.Assert(conf.AsciiDocExt.Extensions[0], qt.Equals, "asciidoctor-html5s")
+		c.Assert(conf.RST.SyntaxHighlight, qt.Equals, "short")
 	})
 
 	// We changed the typographer extension config from a bool to a struct in 0.112.0.

markup/rst/convert.go

@@ -25,6 +25,7 @@ import (
 
 	"github.com/gohugoio/hugo/markup/converter"
 	"github.com/gohugoio/hugo/markup/internal"
+	"github.com/gohugoio/hugo/markup/rst/rst_config"
 )
 
 // Provider is the package entry point.
@@ -81,10 +82,10 @@ func (c *rstConverter) getRstContent(src []byte, ctx converter.DocumentContext)
 	// handle Windows manually because it doesn't do shebangs
 	if runtime.GOOS == "windows" {
 		pythonBinary, _ := internal.GetPythonBinaryAndExecPath()
-		args := []string{binaryPath, "--leave-comments", "--initial-header-level=2"}
+		args := append([]string{binaryPath}, c.parseArgs()...)
 		result, err = internal.ExternallyRenderContent(c.cfg, ctx, src, pythonBinary, args)
 	} else {
-		args := []string{"--leave-comments", "--initial-header-level=2"}
+		args := c.parseArgs()
 		result, err = internal.ExternallyRenderContent(c.cfg, ctx, src, binaryName, args)
 	}
 
@@ -106,6 +107,36 @@ func (c *rstConverter) getRstContent(src []byte, ctx converter.DocumentContext)
 	return result[bodyStart+7 : bodyEnd], err
 }
 
+func (c *rstConverter) parseArgs() []string {
+	cfg := rst_config.Default
+	if c.cfg.Conf != nil {
+		cfg = c.cfg.MarkupConfig().RST
+	}
+
+	if cfg.SyntaxHighlight != rst_config.CliDefault.SyntaxHighlight && !rst_config.AllowedSyntaxHighlight[cfg.SyntaxHighlight] {
+		if c.cfg.Logger != nil {
+			c.cfg.Logger.Errorf(
+				"Unsupported reStructuredText value %q for option %q was passed in and will be ignored.",
+				cfg.SyntaxHighlight,
+				"syntaxHighlight",
+			)
+		}
+		cfg.SyntaxHighlight = rst_config.CliDefault.SyntaxHighlight
+	}
+
+	return parseArgs(cfg)
+}
+
+func parseArgs(cfg rst_config.Config) []string {
+	args := []string{"--leave-comments", "--initial-header-level=2"}
+
+	if cfg.SyntaxHighlight != rst_config.CliDefault.SyntaxHighlight && rst_config.AllowedSyntaxHighlight[cfg.SyntaxHighlight] {
+		args = append(args, "--syntax-highlight="+cfg.SyntaxHighlight)
+	}
+
+	return args
+}
+
 var rst2Binaries = []string{"rst2html", "rst2html.py"}
 
 func getRstBinaryNameAndPath() (string, string) {

markup/rst/convert_test.go

@@ -21,6 +21,7 @@ import (
 	"github.com/gohugoio/hugo/config/security"
 
 	"github.com/gohugoio/hugo/markup/converter"
+	"github.com/gohugoio/hugo/markup/rst/rst_config"
 
 	qt "github.com/frankban/quicktest"
 )
@@ -45,3 +46,35 @@ func TestConvert(t *testing.T) {
 	c.Assert(err, qt.IsNil)
 	c.Assert(string(b.Bytes()), qt.Equals, "<div class=\"document\">\n\n\n<p>testContent</p>\n</div>")
 }
+
+func TestParseArgs(t *testing.T) {
+	c := qt.New(t)
+
+	for _, test := range []struct {
+		name     string
+		value    string
+		expected []string
+	}{
+		{
+			name:     "Default",
+			value:    "long",
+			expected: []string{"--leave-comments", "--initial-header-level=2"},
+		},
+		{
+			name:     "Short",
+			value:    "short",
+			expected: []string{"--leave-comments", "--initial-header-level=2", "--syntax-highlight=short"},
+		},
+		{
+			name:     "None",
+			value:    "none",
+			expected: []string{"--leave-comments", "--initial-header-level=2", "--syntax-highlight=none"},
+		},
+	} {
+		c.Run(test.name, func(c *qt.C) {
+			c.Parallel()
+
+			c.Assert(parseArgs(rst_config.Config{SyntaxHighlight: test.value}), qt.DeepEquals, test.expected)
+		})
+	}
+}

markup/rst/rst_config/config.go

@@ -0,0 +1,39 @@
+// Copyright 2026 The Hugo Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package rst_config holds reStructuredText related configuration.
+package rst_config
+
+var (
+	// Default holds Hugo's default reStructuredText configuration.
+	Default = Config{
+		SyntaxHighlight: "long",
+	}
+
+	// CliDefault holds rst2html CLI defaults.
+	CliDefault = Config{
+		SyntaxHighlight: "long",
+	}
+
+	AllowedSyntaxHighlight = map[string]bool{
+		"long":  true,
+		"short": true,
+		"none":  true,
+	}
+)
+
+// Config configures reStructuredText.
+type Config struct {
+	// SyntaxHighlight sets Docutils' Pygments token names: "long", "short", or "none".
+	SyntaxHighlight string
+}