News

This Hugo module allows rendering mathematical and chemical formulas in Markdown.

The popular Javascript library $\KaTeX$ is included for self-hosting.

Inline LaTeX

can get wrapped with the two Hugo shortcodes {{< math >}} and {{< chem >}}. They prevent distortions by the Markdown rendering. Already working LaTeX expressions surrounded by a $ or doubly escaped parenthesis are still fine, of course: $E = mc^2$.

LaTeX blocks

can be placed inside fenced code blocks with the identifiers math or chem. They also provide protection against distortions and have another advantage: We can use newlines in formulas as usual. Again, already working LaTeX expressions surrounded by two dollars or doubly escaped squared brackets are still fine.
$$\begin{equation}E = mc^2\end{equation}$$

The module is available on GitHub and includes a minimal Hugo example site for local rendering.

Author pages are now available and some layout elements have been improved.

• The release is available on GitHub.

• This extensive (but still incomplete) documentation site is available as the example project.

• In the coming weeks, I will improve and modularize some components of the theme to make them reusable: Fonts, plugins, image generation…

• The next beta release will include social icons and the necessary parameters for the project and for author pages to add links to social networks.

• And after that, I’m going to add a dark mode to the theme.

A new fluid-responsive Hugo theme is available for test runs.

The release is available on GitHub. The extensive (but incomplete) documentation is available as example project.

This site and especially the documentation section are a demonstration and a test of the theme.

Until I announce the release in the Hugo forum, the overview in the documentation for seasoned Hugo users will be ready:

• The usual one-page Markdown demonstration

• A few remarks about the concept and the goals of this theme.

• Current and planned features.

The next beta release will include author pages. I’m planning to implement them as taxonomy pages.

Two short partials create a local link to open the content file 
of the current page.

The first one renders the opening anchor tag with the VSCode link, the second one places the closing tag. The tags are generated only if Hugo runs in server mode and if a local file is present.

vscode_start.html

{{- if .Site.IsServer -}}
    {{- with .File -}}
        {{- $path := print "vscode://file" .Filename  -}}
        <a {{ printf "href=%q" $path | safeHTMLAttr }} rel="nofollow">
    {{- end -}}
{{- end -}}{{- /**/ -}}

vscode_end.html

{{ if .Site.IsServer }}
    {{- with .File }}
        </a>
    {{- end }}
{{ end }}{{- /**/ -}}

How to apply these partials

You can copy-paste these small snippets into your project, there is no need for a citation or something. The core functionality stems from VSCode.

The partials are also available as an Apache-licensed module: hugo-mod-open-in-vscode. This is the better option if you’re interested in possible updates.

The Perplex theme places them around the publishing date or — in case there is none — around the title.

Replacement codes let us avoid raw HTML in Markdown. 
A single partial replaces them with the inline tags 
lacking a syntax element in Goldmark.

The codes look like {*text}, where * is a placeholder for one or more ASCII characters. The superscript tag <sup> for example is marked by ^ and fits the following regular expression (Golang syntax):

replaceRE `\{\^([^}]*)\}` "<sup>$1</sup>"

This syntax does not collide with any other elements — as far as I know. And it’s safe because the replacements are applied after the Markdown rendering. Hugo discards all HTML in Markdown by default and also checks these codes before the regular expressions are applied.

All replacements are chained together in one Hugo partial, which can process every piece of rendered Markdown content in the templates.

These replacements are published as a tiny Hugo module on GitHub.

This approach is a workaround. To create extensions for Hugo’s Markdown renderer Goldmark would be the better solution.