webinstall.dev/comrak Star on GitHub

Comrak is a Rust port of github's cmark-gfm.

https://github.com/kivikakk/comrak| Installer Source| Releases (json) (tab)

To update or switch versions, run webi comrak@stable (or @v0.11, @beta, etc).

Files

These are the files / directories that are created and/or modified with this install:

~/.config/envman/PATH.env
~/.local/bin/comrak
~/.config/comrak/config

Cheat Sheet

Comrak supports the five extensions to CommonMark defined in the GitHub Flavored Markdown Spec: Tables, Task list items, Strikethrough, Autolinks, & Disallowed Raw HTML

comrak --gfm index.md > index.html

Here you'll learn how to:

  • Convert Markdown to HTML
  • Set Reasonable Defaults
  • Safely Render Untrusted HTML
  • Render Trusted HTML with Scripts
  • Temporarily Ignore Defaults

How to Convert Markdown to HTML

comrak --gfm --header-ids '' README.md > README.html

How to set Reasonable Defaults

You can update ~/.config/comrak/config to change Comrak from it's very strict defaults to always include your favorite options.

Here's what I suggest:

echo "--gfm --header-ids ''" > ~/.config/comrak/config

See comrak --help for other options.

How to Render Untrusted HTML

Comrak does NOT have an option to allow arbitrary HTML while protecting against unsafe links, such as <a href="/?originalUrl=https%3A%2F%2Fwebinstall.dev%2F%26quot%3Bjavascript%3A...%26quot%3B%26gt%3B%253C%2Fcode">.

Therefore, you MUST enable CSP for comrak-rendered site to disallow unsafe inline scripts. This can be done via a <meta> tag or HTTP headers.

Example:

<meta http-equiv="Content-Security-Policy" content="default-src *" />

Then, to sanitize <script> and <iframe> tags you must add -e tagfilter (which the --gfm option also enables).

comrak --unsafe --gfm --header-ids '' README.md

How to Render HTML & Scripts

The --unsafe option may not work as expected with --gfm, as it is still somewhat neutered by -e tagfilter.

If you want Github-Flavored Markdown with trusted scripts, you'll need to enable its extensions by hand:

echo "
# WARNING: allows <script>, <iframe>
# and <a href="/?originalUrl=javascript%3Aalert(%26%2339%3B%26%2339%3B)%26gt%3B--unsafe%23%2520same%2520as%2520--gfm%2C%2520but%2520without%2520-e%2520tagfilter%2C%23%2520meaning%2520ALL%2520html%2520tags%2520are%2520allowed-e%2520strikethrough-e%2520table-e%2520autolink-e%2520tasklist--github-pre-lang%23%2520linkable%2520headers%2520(w%2F%2520empty%2520prefix)--header-ids%2520%26%2339%3B%26%2339%3B%23%2520additional%2520extensions-e%2520superscript-e%2520footnotes-e%2520description-lists%26quot%3B%2520%26gt%3B%2520~%2F.config%2Fcomrak%2Fallow-scripts%253C%2Fcode">
comrak --config ~/.config/comrak/allow-scripts README.md

How to Ignore Defaults

You can disable all options with --config-file none.

Example:

comrak --config-file none -e table README.md

Contribute

Report an Issue Submit Installer Star on GitHub