comrak/README.md

   1 ---
   2 title: Comrak
   3 homepage: https://github.com/kivikakk/comrak
   4 tagline: |
   5   Comrak is a Rust port of github's cmark-gfm.
   6 ---
   7
   8 To update or switch versions, run `webi comrak@stable` (or `@v0.11`, `@beta`,
   9 etc).
  10
  11 ## Cheat Sheet
  12
  13 > Comrak supports the five extensions to CommonMark defined in the GitHub
  14 > Flavored Markdown Spec: Tables, Task list items, Strikethrough, Autolinks, &
  15 > Disallowed Raw HTML
  16
  17 ```bash
  18 comrak --gfm index.md > index.html
  19 ```
  20
  21 Here you'll learn how to:
  22
  23 - Convert Markdown to HTML
  24 - Set Reasonable Defaults
  25 - Safely Render _Untrusted_ HTML
  26 - Render _Trusted_ HTML with Scripts
  27 - Temporarily Ignore Defaults
  28
  29 ## How to Convert Markdown to HTML
  30
  31 ```bash
  32 comrak --gfm --header-ids '' README.md > README.html
  33 ```
  34
  35 ## How to set Reasonable Defaults
  36
  37 You can update `~/.config/comrak/config` to change Comrak from it's very strict
  38 defaults to always include your favorite options.
  39
  40 Here's what I suggest:
  41
  42 ```bash
  43 echo "--gfm --header-ids ''" > ~/.config/comrak/config
  44 ```
  45
  46 See `comrak --help` for other options.
  47
  48 ## How to Render _Untrusted_ HTML
  49
  50 Comrak does NOT have an option to allow arbitrary HTML while protecting against
  51 unsafe links, such as `<a href="javascript:...">`.
  52
  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.
  55
  56 Example:
  57
  58 ```html
  59 <meta http-equiv="Content-Security-Policy" content="default-src *" />
  60 ```
  61
  62 Then, to sanitize `<script>` and `<iframe>` tags you must add `-e tagfilter`
  63 (which the `--gfm` option also enables).
  64
  65 ```bash
  66 comrak --unsafe --gfm --header-ids '' README.md
  67 ```
  68
  69 ## How to Render HTML & Scripts
  70
  71 The `--unsafe` option
  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`.
  74
  75 If you want Github-Flavored Markdown with trusted scripts, you'll need to enable
  76 its extensions by hand:
  77
  78 ```bash
  79 echo "
  80 # WARNING: allows <script>, <iframe>
  81 # and <a href=javascript:alert('')>
  82 --unsafe
  83
  84 # same as --gfm, but without -e tagfilter,
  85 # meaning ALL html tags are allowed
  86 -e strikethrough
  87 -e table
  88 -e autolink
  89 -e tasklist
  90 --github-pre-lang
  91
  92 # linkable headers (w/ empty prefix)
  93 --header-ids ''
  94
  95 # additional extensions
  96 -e superscript
  97 -e footnotes
  98 -e description-lists
  99
 100 " > ~/.config/comrak/allow-scripts
 101 ```
 102
 103 ```bash
 104 comrak --config ~/.config/comrak/allow-scripts README.md
 105 ```
 106
 107 ## How to Ignore Defaults
 108
 109 You can disable all options with `--config-file none`.
 110
 111 Example:
 112
 113 ```bash
 114 comrak --config-file none -e table README.md
 115 ```