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