A Go Markdown-to-HTML renderer built on goldmark. One function call turns an untrusted Markdown document into sanitized HTML with GitHub-style extras. No configuration required.
- GitHub-flavored Markdown: tables, strikethrough, task lists, autolinks,
footnotes, and emoji (
:tada:). - Heading ids from GitHub's anchor rule, with permalink anchors. A
## Heading {#custom-id}suffix is text, the way GitHub reads it; keep an old fragment alive with<a name="x">. - GitHub alerts:
> [!NOTE],[!TIP],[!IMPORTANT],[!WARNING],[!CAUTION], with titles. - Code fences highlighted by chroma
with CSS classes, using the
githubstyle. - Mermaid fences rendered as
<pre class="mermaid">for a client-side renderer: Mermaid or Pele. - Math with
$...$and$$...$$, the two forms GitHub reads, converted to MathJax delimiters. - YAML front matter rendered as a table above the document.
- Sized images:
. - Raw HTML passes through a sanitizer policy modeled on GitHub's subset.
go get github.com/brutasse/petroglyph
import "github.com/brutasse/petroglyph"
html, flags := petroglyph.Convert(source)Convert renders the whole document: optional front matter, body, sanitized
raw HTML, wrapped tables, and alert titles. On a render failure it returns
the source as escaped <pre> text instead of failing.
The returned Flags tell you which optional scripts the page needs:
if flags.Math {
// load MathJax
}
if flags.Mermaid {
// load a mermaid renderer: Mermaid or Pele
}This keeps pages free of JavaScript they do not use.
petroglyph.GFMParserandpetroglyph.GFMHTMLRendererare the goldmark v2 extensions behindConvert. Pass them toparser.WithExtensionsandhtml.WithExtensionswhen you want control over parsing or rendering. You then sanitize the output yourself.GFMHTMLRendererhas to stay last in a longer extension list: goldmark lets the last extension win each node kind, which is how the fence, heading, image and math renderers replace the defaults.petroglyph.New()returns a*Markdownholding the configured parser and HTML renderer. Use it withpetroglyph.Needs(doc, source)when you already hold the parsed document.petroglyph.DisplayPolicy()returns the bluemonday policyConvertapplies. Reuse it to sanitize other markup the same way.
Convert emits these classes. Your stylesheet decides how they look; the
library ships no CSS.
| Markup | Meaning |
|---|---|
.table-wrap |
wrapper div around every table, for overflow-x: auto |
.frontmatter |
table generated from YAML front matter |
.codeblock |
wrapper div around a highlighted code fence |
.chroma |
chroma-generated code markup (class-based) |
.mermaid |
<pre> holding a mermaid diagram source: the container a client-side renderer draws into |
.markdown-alert .markdown-alert-note and friends |
alert blockquotes |
.markdown-alert-title |
title paragraph inside an alert |
.heading-anchor |
the # permalink link inside a heading |
.fallback |
<pre> used when rendering failed |
Generate the chroma stylesheet once with the same style the formatter uses:
f := chromahtml.New(chromahtml.WithClasses(true))
css, _ := os.Create("chroma.css")
defer css.Close()
f.WriteCSS(css, styles.Get("github"))showcase.md exercises every feature. Render it with Convert to inspect
the full markup, or use it as a fixture in your own stylesheet work.
Math output uses the \(...\) and \[...\] delimiters, which MathJax
activates by default. A page shows math by loading MathJax when
Flags.Math is set.
A ```mermaid fence becomes <pre class="mermaid"> and sets
Flags.Mermaid. petroglyph ships no diagram code. The page picks a
client-side renderer, and that renderer replaces the contents of each
pre.mermaid with its own SVG. Load one renderer per page: Mermaid and
Pele both read the diagram source from the <pre> element, so the second
one draws over the first.
Mermaid scans pre.mermaid elements by itself,
so startOnLoad is the only call a static page needs:
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12/dist/mermaid.esm.min.mjs';
mermaid.initialize({ startOnLoad: true });
</script>Call mermaid.run() yourself when parts of the page arrive after load.
securityLevel defaults to strict: Mermaid escapes HTML in diagram text
and disables click handlers. Keep that level for documents you do not
trust. Themes come from mermaid.initialize (theme, themeVariables),
and Mermaid adds its own stylesheet rules to the page. Bundle the library
with npm install mermaid instead of the CDN.
Pele renders a diagram when you call mount(). The
browser script defines the global pele:
<script src="https://cdn.jsdelivr.net/npm/pele@1/dist/pele.global.js"></script>
<script>
for (const el of document.querySelectorAll('pre.mermaid'))
pele.mount(el, el.textContent, { links: false, images: false });
</script>mount() needs no initialization call, sizes each diagram to its
container, redraws on container resize and on web-font load, and shows a
syntax error in place instead of throwing. Diagram colors come from the
--pele-* CSS variables, set on .pele or on any ancestor element.
The links and images options carry weight for untrusted documents.
Pele allows http, https, mailto, and tel links and http and
https images by default, and setting both options to false removes
them. Bundle the library with npm install pele and
import { mount } from 'pele' instead of the CDN.
Convert renders raw HTML (goldmark unsafe mode) and then filters the
result through DisplayPolicy. The policy extends bluemonday's UGC policy
with the classes, ids, checkbox inputs, and <a name> anchors this renderer
generates or documents. Treat
the output as display-safe, not script-safe: it can carry class and
id attributes, so do not serve your own trust-critical DOM ids that a
document could collide with.
MIT. See LICENSE.