how to get hugo-compatible inline equations

[falkmielke]

Description

I am trying to get math equations to a hugo-compatible markdown format¹.
This seems to be a recurring topic; I have read a number of guides and other questions, and got a few steps further.
One thing I cannot solve is inline equations using single backslash brackets, e.g. \(\sigma\).

Example, also available in a repo context here:

---
title: ""
from: markdown+tex_math_single_backslash
html-math-method: mathjax
format:
  hugo-md:
    toc: false
    preserve_yaml: true
output:
  hugo-md:
    maths: true
    variant: gfm+footnotes+tex_math_gfm
---

I am losing my \( \sigma \)!

```{=markdown}
But I would like to keep \( \sigma \)...
```

via

quarto render hugomd_testing.qmd --to hugo-md

this becomes

I am losing my $\sigma$!

But I would like to keep \(\sigma\)...

... which does not render well with mathjax:

When omitting from: markdown+tex_math_single_backslash, the sigma symbol in brackets is lost; I got one step further thanks to this issue.

Still, during rendering, the inline math brackets get converted to dollars.
Compared to raw markdown export, where brackets are retained, and math renders nicely².
(edit: note that hugo discourages single dollar for inline maths: "using it may result in unintended formatting if you use the $ symbol outside of math contexts".)

Is there a setting to encourage pandoc to keep the brackets?

Thank you in advance!

Footnotes

1. ultimately, we use github actions to deploy a hugo website from rendered markdowns; I am moving from Rmarkdown to hugo. ↩

2. using html-math-method: webtex is a workaround, because it links in svg symbols; yet I would prefer the other engines. ↩

[cderv]

First, when you write in a .qmd, you need to use Quarto Markdown syntax as we document. So inline needs to be $ .. $. This is so that the format is parsed correctly.

If you want to write hugo directly, then you need to use raw directly as you with the block

I am losing my \( \sigma \)!

```{=markdown}
But I would like to keep \( \sigma \)...
```

So to keep it you could do

Keeping it: `\( \sigma \)`{=markdown}

If you want \( in output, this is about the writer. As we document in webtex alternative section, format: hugo-md will output $ for math.

Through Pandoc, you can tweak the output by configure how the Pandoc writer behave. This is advanced (as not documented and requiring knowing how format: hugo-md works, and how pandoc works) but you can do this

---
title: Test
format: 
  hugo-md:
    variant: -tex_math_dollars+tex_math_single_backslash
---

I am losing my $\sigma$

```{=markdown}
But I would like to keep \( \sigma \)...
```

• First you need to opt out using the dollars sign which is the default (-tex_math_dollars)
• And you need to activate single backlash syntax (+tex_math_single_backslash)

This will output the following

I am losing my \(\sigma\)

But I would like to keep \( \sigma \)...

which I think it what you want;

Using $..$ is usually ok - I was not aware when using katex it was a problem.

Hope it helps

[falkmielke]

Thank you for taking the time, @cderv !
This indeed answers my question, much appreciated.

• I will stick to quarto markdown syntax
• the extensions via variant yaml help me to control the output.

I also now found that I had only been checking the pandoc extensions for gfm, because someone used gfm for a preset document I used. I could now find the options you pointed at with pandoc --list-extensions=markdown. Very useful.

[cderv]

I also now found that I had only been checking the pandoc extensions for gfm, because someone used gfm for a preset document I used. I could now find the options you pointed at with pandoc --list-extensions=markdown. Very useful.

Keep in mind that Quarto is a bit different than Pandoc. Beware that hugo-md is not completely gfm

it is quite advanced usage to tweak variants and you'll need to dig the source code to understand how format works. I am putting this here for reference if anyone search for such information:

format: hugo-md is defined as a Custom format and the variant used is

quarto-cli/src/resources/extensions/quarto/hugo/_extension.yml

Lines 22 to 24 in 2ae62ed

	formats:
	md:
	variant: gfm+yaml_metadata_block+definition_lists+smart

-md refers to the internal markdown format - it is markdown_strict + chosen extension to mimic commonmark

quarto-cli/src/format/formats.ts

Lines 140 to 144 in 2ae62ed

	case "md":
	writerFormat = markdownWithCommonmarkExtensionsFormat();
	lookupTo = "commonmark";
	pandocTo = "markdown_strict";
	break;

but variants passed in the extension setting sets base format to gfm instead.

And gfm is based on commonmark + some extensions

quarto-cli/src/format/formats.ts

Lines 152 to 155 in 2ae62ed

	case "gfm":
	writerFormat = gfmFormat();
	pandocTo = to;
	break;

quarto-cli/src/format/markdown/format-markdown.ts

Lines 32 to 39 in 2ae62ed

	export function gfmFormat(): Format {
	return createFormat(kDisplayNameGFM, "md", markdownFormat(kDisplayNameGFM), {
	pandoc: {
	to: "commonmark",
	},
	render: {
	[kVariant]: kGfmCommonmarkVariant,
	},

quarto-cli/src/format/markdown/format-markdown-consts.ts

Lines 7 to 18 in 2ae62ed

	export const kGfmCommonmarkExtensions = [
	"+autolink_bare_uris",
	"+emoji",
	"+footnotes",
	"+gfm_auto_identifiers",
	"+pipe_tables",
	"+strikeout",
	"+task_lists",
	"+tex_math_dollars",
	];
	export const kGfmCommonmarkVariant = kGfmCommonmarkExtensions.join("");

You can see that we do opt in most of available extension for commonmark

❯ quarto pandoc --list-extensions=commonmark
-alerts
-ascii_identifiers
-attributes
-autolink_bare_uris
-bracketed_spans
-definition_lists
-east_asian_line_breaks
-emoji
-fancy_lists
-fenced_divs
-footnotes
-gfm_auto_identifiers
-hard_line_breaks
-implicit_figures
-implicit_header_references
-pipe_tables
-raw_attribute
+raw_html
-rebase_relative_paths
-smart
-sourcepos
-strikeout
-subscript
-superscript
-task_lists
-tex_math_dollars
-tex_math_gfm
-wikilinks_title_after_pipe
-wikilinks_title_before_pipe
-yaml_metadata_block

I am sharing this in case you want to do more advanced things. Adding back my warning, this is advanced to use variants and we don't have yet done advanced documentation.

Hope it helps.

[falkmielke]

Yes, this helps a lot! We certainly have advanced use cases, and are just beginning to explore quarto (with positive experiences).
Thank you for your kind help and the advanced documentation!