Skip to content

Commit

Permalink
markup/rst: use MathJax for rst math output and use short pygments hi…
Browse files Browse the repository at this point in the history
…ghlighting

* As noted in gohugoio#7759, rst2html exports math using the "HTML math.css"
  formatter by default. This means that any math typeset in
  reStructuredText is not formatted using MathJax which is not ideal.
  This commit adds a --math-output parameter configure rst2html to
  output math ready for MathJax to process. Note that I had to pick a
  URL for MathJax, but it doesn't end up in the resulting output because
  the <script> tag is in the header which gets cut out by code further
  down.

* As noted in gohugoio#5349, rst2html can generate HTML with short or long form
  class names for syntax highlighting. Pygments (via the pygmentize
  command) seems to generate short form by default without any way to
  switch this. This means most/any stylesheets for code provided with
  various themes won't work when using rST output. This can easily be
  fixed by providing the --syntax-highlight=short flag to rst2html.

Fixes: gohugoio#5349
Fixes: gohugoio#7759

Co-authored-by: Stephen Finucane <[email protected]>
Signed-off-by: Sumner Evans <[email protected]>
  • Loading branch information
sumnerevans and stephenfin committed Dec 25, 2021
1 parent 1dbfc0f commit 4b4ba1c
Show file tree
Hide file tree
Showing 4 changed files with 40 additions and 3 deletions.
3 changes: 3 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ jobs:
run: |
pip install docutils
rst2html.py --version
- name: Install pygments
run: |
pip install pygments
- if: matrix.os == 'ubuntu-latest'
name: Install pandoc on Linux
run: |
Expand Down
2 changes: 1 addition & 1 deletion docs/content/en/content-management/formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ tool on your machine to be able to use these formats.
Hugo passes reasonable default arguments to these external helpers by default:

- `asciidoctor`: `--no-header-footer -`
- `rst2html`: `--leave-comments --initial-header-level=2`
- `rst2html`: `--leave-comments --initial-header-level=2 --syntax-highlight=short --math-output "MathJax https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js"`
- `pandoc`: `--mathjax`

{{% warning "Performance of External Helpers" %}}
Expand Down
8 changes: 6 additions & 2 deletions markup/rst/convert.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,10 +82,14 @@ 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 := []string{path,
"--leave-comments", "--initial-header-level=2", "--syntax-highlight=short",
"--math-output", "MathJax https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js"}
result, err = internal.ExternallyRenderContent(c.cfg, ctx, src, pythonBinary, args)
} else {
args := []string{"--leave-comments", "--initial-header-level=2"}
args := []string{
"--leave-comments", "--initial-header-level=2", "--syntax-highlight=short",
"--math-output", "MathJax https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js"}
result, err = internal.ExternallyRenderContent(c.cfg, ctx, src, binaryName, args)
}

Expand Down
30 changes: 30 additions & 0 deletions markup/rst/convert_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,33 @@ 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 TestConvertMathJax(t *testing.T) {
if !Supports() {
t.Skip("rst not installed")
}
c := qt.New(t)
p, err := Provider.New(converter.ProviderConfig{Logger: loggers.NewErrorLogger()})
c.Assert(err, qt.IsNil)
conv, err := p.New(converter.DocumentContext{})
c.Assert(err, qt.IsNil)
b, err := conv.Convert(converter.RenderContext{Src: []byte(":math:`ax^2 + bx + c = 0`")})
c.Assert(err, qt.IsNil)
c.Assert(string(b.Bytes()), qt.Equals,
"<div class=\"document\">\n\n\n<p><span class=\"math\">\\(ax^2 + bx + c = 0\\)</span></p>\n</div>")
}

func TestConvertCodeFormatting(t *testing.T) {
if !Supports() {
t.Skip("rst not installed")
}
c := qt.New(t)
p, err := Provider.New(converter.ProviderConfig{Logger: loggers.NewErrorLogger()})
c.Assert(err, qt.IsNil)
conv, err := p.New(converter.DocumentContext{})
c.Assert(err, qt.IsNil)
b, err := conv.Convert(converter.RenderContext{Src: []byte(".. code:: c\n\n int i = 0;")})
c.Assert(err, qt.IsNil)
c.Assert(string(b.Bytes()), qt.Equals,
"<div class=\"document\">\n\n\n<pre class=\"code c literal-block\">\n<span class=\"kt\">int</span> <span class=\"n\">i</span> <span class=\"o\">=</span> <span class=\"mi\">0</span><span class=\"p\">;</span>\n</pre>\n</div>")
}

0 comments on commit 4b4ba1c

Please sign in to comment.