2018-03-22 11:57:04 -05:00
Marked is
2018-03-11 17:16:48 -04:00
1. built for speed.< sup > *</ sup >
2018-04-04 22:43:24 -04:00
2. a low-level markdown compiler for parsing markdown without caching or blocking for long periods of time.< sup > **</ sup >
2018-03-11 17:16:48 -04:00
3. light-weight while implementing all markdown features from the supported flavors & specifications.< sup > ***</ sup >
4. available as a command line interface (CLI) and running in client- or server-side JavaScript projects.
< p > < small > < sup > *< / sup > Still working on metrics for comparative analysis and definition.< / small > < br >
< small > < sup > **< / sup > As few dependencies as possible.< / small > < br >
< small > < sup > ***< / sup > Strict compliance could result in slower processing when running comparative benchmarking.< / small > < / p >
2018-03-25 20:46:27 -04:00
< h2 id = "demo" > Demo< / h2 >
2018-03-26 10:36:47 -05:00
Checkout the [demo page ](./demo/ ) to see marked in action ⛹️
2018-03-25 20:46:27 -04:00
These documentation pages are also rendered using marked 💯
2018-03-11 17:16:48 -04:00
< h2 id = "installation" > Installation< / h2 >
**CLI:** `npm install -g marked`
2022-09-12 20:15:41 +07:00
**In-browser:**
```
npm install marked
```
2018-03-11 17:16:48 -04:00
< h2 id = "usage" > Usage< / h2 >
2022-05-29 13:20:40 +08:00
### Warning: 🚨 Marked does not [sanitize](/using_advanced#options) the output HTML. If you are processing potentially unsafe strings, it's important to filter for possible XSS attacks. Some filtering options include [DOMPurify](https://github.com/cure53/DOMPurify) (recommended), [js-xss](https://github.com/leizongmin/js-xss), [sanitize-html](https://github.com/apostrophecms/sanitize-html) and [insane](https://github.com/bevacqua/insane) on the *output* HTML! 🚨
2022-05-07 18:37:21 +02:00
```
DOMPurify.sanitize(marked.parse(`<img src="x" onerror="alert('not happening')">` ));
```
2018-06-24 01:56:52 -05:00
2022-10-11 15:24:48 +02:00
**⚠️ Input: special ZERO WIDTH unicode characters (for example `\uFEFF` ) might interfere with parsing. Some text editors add them at the start of the file (see: [#2139 ](https://github.com/markedjs/marked/issues/2139 )).**
```js
2023-06-09 22:10:12 -05:00
// remove the most common zerowidth characters from the start of the file
2022-10-11 15:24:48 +02:00
marked.parse(
contents.replace(/^[\u200B\u200C\u200D\u200E\u200F\uFEFF]/,"")
)
```
2018-03-11 17:16:48 -04:00
**CLI**
``` bash
2021-11-24 22:19:58 +01:00
# Example with stdin input
2018-03-11 17:16:48 -04:00
$ marked -o hello.html
hello world
^D
$ cat hello.html
< p > hello world< / p >
```
2018-04-01 23:25:53 -05:00
``` bash
2021-11-24 22:19:58 +01:00
# Example with string input
2018-04-01 23:25:53 -05:00
$ marked -s "*hello world*"
< p > < em > hello world< / em > < / p >
```
2021-11-24 22:19:58 +01:00
```bash
# Example with file input
echo "**bold text example**" > readme.md
$ marked -i readme.md -o readme.html
$ cat readme.html
< p > < strong > bold text example< / strong > < / p >
```
```bash
# Print all options
$ marked --help
```
2023-09-02 21:39:45 -06:00
*CLI Config*
A config file can be used to configure the marked cli.
If it is a `.json` file it should be a JSON object that will be passed to marked as options.
If `.js` is used it should have a default export of a marked options object or a function that takes `marked` as a parameter.
It can use the `marked` parameter to install extensions using `marked.use` .
By default the marked cli will look for a config file in your home directory in the following order.
- `~/.marked.json`
- `~/.marked.js`
- `~/.marked/index.js`
```bash
# Example with custom config
echo '{ "breaks": true }' > config.json
$ marked -s 'line1\nline2' -c config.json
< p > line1< br > line2< / p >
```
2018-03-11 17:16:48 -04:00
**Browser**
```html
<!doctype html>
< html >
< head >
< meta charset = "utf-8" / >
< title > Marked in the browser< / title >
< / head >
< body >
< div id = "content" > < / div >
2018-03-25 20:36:41 -04:00
< script src = "https://cdn.jsdelivr.net/npm/marked/marked.min.js" > < / script >
2018-03-11 17:16:48 -04:00
< script >
document.getElementById('content').innerHTML =
2021-11-02 07:32:17 -07:00
marked.parse('# Marked in browser\n\nRendered by **marked** .');
2018-03-11 17:16:48 -04:00
< / script >
< / body >
< / html >
```
2023-11-28 08:12:06 -07:00
or import esm module
```html
< script type = "module" >
import { marked } from "https://cdn.jsdelivr.net/npm/marked/lib/marked.esm.js";
document.getElementById('content').innerHTML =
marked.parse('# Marked in the browser\n\nRendered by **marked** .');
< / script >
```
2018-03-11 17:16:48 -04:00
2020-09-21 09:57:04 -05:00
**Node.js**
2020-09-21 00:00:45 -05:00
```js
2021-11-02 07:32:17 -07:00
import { marked } from 'marked';
// or const { marked } = require('marked');
const html = marked.parse('# Marked in Node.js\n\nRendered by **marked** .');
2020-09-21 00:00:45 -05:00
```
2018-03-11 17:16:48 -04:00
2020-08-29 17:55:07 -04:00
Marked offers [advanced configurations ](/using_advanced ) and [extensibility ](/using_pro ) as well.
2018-03-11 17:16:48 -04:00
< h2 id = "specifications" > Supported Markdown specifications< / h2 >
We actively support the features of the following [Markdown flavors ](https://github.com/commonmark/CommonMark/wiki/Markdown-Flavors ).
2020-07-06 16:47:39 -04:00
| Flavor | Version | Status |
| :--------------------------------------------------------- | :------ | :----------------------------------------------------------------- |
| The original markdown.pl | -- | |
2024-02-03 08:21:29 -08:00
| [CommonMark ](http://spec.commonmark.org/0.31.2/ ) | 0.31 | [Work in progress ](https://github.com/markedjs/marked/issues/1202 ) |
2020-07-06 16:47:39 -04:00
| [GitHub Flavored Markdown ](https://github.github.com/gfm/ ) | 0.29 | [Work in progress ](https://github.com/markedjs/marked/issues/1202 ) |
2018-03-11 17:16:48 -04:00
By supporting the above Markdown flavors, it's possible that Marked can help you use other flavors as well; however, these are not actively supported by the community.
2022-10-06 18:36:28 +05:30
< h2 id = "tools" > List of Tools Using Marked< / h2 >
2023-06-09 22:10:12 -05:00
We actively support the usability of Marked in super-fast markdown transformation, some of Tools using `Marked` for single-page creations are
2022-10-06 18:36:28 +05:30
| Tools | Description |
| :----------------------------------------------------------------- | :------------------------------------------------------------------------ |
| [zero-md ](https://zerodevx.github.io/zero-md/ ) | A native markdown-to-html web component to load and display an external MD file.It uses Marked for super-fast markdown transformation. |
| [texme ](https://github.com/susam/texme ) | TeXMe is a lightweight JavaScript utility to create self-rendering Markdown + LaTeX documents. |
| [StrapDown.js ](https://naereen.github.io/StrapDown.js/ ) | StrapDown.js is an awesome on-the-fly Markdown to HTML text processor. |
2023-07-15 19:50:42 -05:00
| [raito ](https://raito.arnaud.at/ ) | Mini Markdown Wiki/CMS in 8kb of JavaScript. |
2022-10-06 18:36:28 +05:30
| [Homebrewery ](https://homebrewery.naturalcrit.com/ ) | The Homebrewery is a tool for making authentic looking D& D content using Markdown. It is distributed under the terms of the MIT. |
2018-03-11 17:16:48 -04:00
< h2 id = "security" > Security< / h2 >
The only completely secure system is the one that doesn't exist in the first place. Having said that, we take the security of Marked very seriously.
2020-08-29 17:55:07 -04:00
Therefore, please disclose potential security issues by email to the project [committers ](/authors ) as well as the [listed owners within NPM ](https://docs.npmjs.com/cli/owner ). We will provide an initial assessment of security reports within 48 hours and should apply patches within 2 weeks (also, feel free to contribute a fix for the issue).
