title, homepage, tagline
| title | homepage | tagline |
|---|---|---|
| Comrak | https://github.com/kivikakk/comrak | Comrak is a Rust port of github's cmark-gfm. |
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.
Example:
comrak --config-file none -e table README.md