Comrak | webinstall.dev

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="javascript:...">.

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=javascript:alert('')>
--unsafe

# same as --gfm, but without -e tagfilter,
# meaning ALL html tags are allowed
-e strikethrough
-e table
-e autolink
-e tasklist
--github-pre-lang

# linkable headers (w/ empty prefix)
--header-ids ''

# additional extensions
-e superscript
-e footnotes
-e description-lists

" > ~/.config/comrak/allow-scripts

comrak --config ~/.config/comrak/allow-scripts README.md

How to Ignore Defaults

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