mirror of
https://github.com/webinstall/webi-installers.git
synced 2026-03-04 02:10:18 +00:00
116 lines
2.5 KiB
Markdown
116 lines
2.5 KiB
Markdown
---
|
|
title: Comrak
|
|
homepage: https://github.com/kivikakk/comrak
|
|
tagline: |
|
|
Comrak is a Rust port of github's cmark-gfm.
|
|
---
|
|
|
|
To update or switch versions, run `webi comrak@stable` (or `@v0.11`, `@beta`,
|
|
etc).
|
|
|
|
## 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```html
|
|
<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).
|
|
|
|
```bash
|
|
comrak --unsafe --gfm --header-ids '' README.md
|
|
```
|
|
|
|
## How to Render HTML & Scripts
|
|
|
|
The `--unsafe` option
|
|
[may not work as expected](https://github.com/kivikakk/comrak/issues/160) 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:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
```bash
|
|
comrak --config ~/.config/comrak/allow-scripts README.md
|
|
```
|
|
|
|
## How to Ignore Defaults
|
|
|
|
You can disable all options with `--config-file none`.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
comrak --config-file none -e table README.md
|
|
```
|