3 homepage: https://github.com/kivikakk/comrak
5 Comrak is a Rust port of github's cmark-gfm.
8 To update or switch versions, run `webi comrak@stable` (or `@v0.11`, `@beta`,
13 > Comrak supports the five extensions to CommonMark defined in the GitHub
14 > Flavored Markdown Spec: Tables, Task list items, Strikethrough, Autolinks, &
18 comrak --gfm index.md > index.html
21 Here you'll learn how to:
23 - Convert Markdown to HTML
24 - Set Reasonable Defaults
25 - Safely Render _Untrusted_ HTML
26 - Render _Trusted_ HTML with Scripts
27 - Temporarily Ignore Defaults
29 ## How to Convert Markdown to HTML
32 comrak --gfm --header-ids '' README.md > README.html
35 ## How to set Reasonable Defaults
37 You can update `~/.config/comrak/config` to change Comrak from it's very strict
38 defaults to always include your favorite options.
40 Here's what I suggest:
43 echo "--gfm --header-ids ''" > ~/.config/comrak/config
46 See `comrak --help` for other options.
48 ## How to Render _Untrusted_ HTML
50 Comrak does NOT have an option to allow arbitrary HTML while protecting against
51 unsafe links, such as `<a href="javascript:...">`.
53 Therefore, you **MUST enable CSP** for comrak-rendered site to disallow unsafe
54 inline scripts. This can be done via a `<meta>` tag or HTTP headers.
59 <meta http-equiv="Content-Security-Policy" content="default-src *" />
62 Then, to sanitize `<script>` and `<iframe>` tags you must add `-e tagfilter`
63 (which the `--gfm` option also enables).
66 comrak --unsafe --gfm --header-ids '' README.md
69 ## How to Render HTML & Scripts
72 [may not work as expected](https://github.com/kivikakk/comrak/issues/160) with
73 `--gfm`, as it is still somewhat neutered by `-e tagfilter`.
75 If you want Github-Flavored Markdown with trusted scripts, you'll need to enable
76 its extensions by hand:
80 # WARNING: allows <script>, <iframe>
81 # and <a href=javascript:alert('')>
84 # same as --gfm, but without -e tagfilter,
85 # meaning ALL html tags are allowed
92 # linkable headers (w/ empty prefix)
95 # additional extensions
100 " > ~/.config/comrak/allow-scripts
104 comrak --config ~/.config/comrak/allow-scripts README.md
107 ## How to Ignore Defaults
109 You can disable all options with `--config-file none`.
114 comrak --config-file none -e table README.md