marked/docs/INDEX.md

Marked is

1. built for speed.<sup>*</sup>
2. a low-level markdown compiler for parsing markdown without caching or blocking for long periods of time.<sup>**</sup>
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>


<h2 id="demo">Demo</h2>

Checkout the [demo page](./demo/) to see marked in action ⛹️

These documentation pages are also rendered using marked 💯


<h2 id="installation">Installation</h2>

**CLI:** `npm install -g marked`

**In-browser:**
```
npm install marked
npm install @types/marked # For TypeScript projects
```
<h2 id="usage">Usage</h2>

### 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! 🚨

```
DOMPurify.sanitize(marked.parse(`<img src="x" onerror="alert('not happening')">`));
```

**⚠️ 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
// remove the most common zerowidth characters from the start of the file 
marked.parse(
  contents.replace(/^[\u200B\u200C\u200D\u200E\u200F\uFEFF]/,"")
)
```

**CLI**

``` bash
# Example with stdin input
$ marked -o hello.html
hello world
^D
$ cat hello.html
<p>hello world</p>
```

``` bash
# Example with string input
$ marked -s "*hello world*"
<p><em>hello world</em></p>
```

```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
```

**Browser**

```html
<!doctype html>
<html>
<head>
  <meta charset="utf-8"/>
  <title>Marked in the browser</title>
</head>
<body>
  <div id="content"></div>
  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
  <script>
    document.getElementById('content').innerHTML =
      marked.parse('# Marked in browser\n\nRendered by **marked**.');
  </script>
</body>
</html>
```

**Node.js**

```js
import { marked } from 'marked';
// or const { marked } = require('marked');

const html = marked.parse('# Marked in Node.js\n\nRendered by **marked**.');
```


Marked offers [advanced configurations](/using_advanced) and [extensibility](/using_pro) as well.

<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).

| Flavor                                                     | Version | Status                                                             |
| :--------------------------------------------------------- | :------ | :----------------------------------------------------------------- |
| The original markdown.pl                                   | --      |                                                                    |
| [CommonMark](http://spec.commonmark.org/0.30/)             | 0.30    | [Work in progress](https://github.com/markedjs/marked/issues/1202) |
| [GitHub Flavored Markdown](https://github.github.com/gfm/) | 0.29    | [Work in progress](https://github.com/markedjs/marked/issues/1202) |

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.

<h2 id="tools">List of Tools Using Marked</h2>

We actively support the usability of Marked in super-fast markdown transformation, some of Tools using `Marked` for single-page creations are 

| 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.                |
| [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.             |

<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.

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).
fix installation nav 2018-03-22 11:57:04 -05:00			`Marked is`
Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00
			`1. built for speed.<sup>*</sup>`
Try to get low-level bullet to fit on one line 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>`
Move existing docs to /docs dir 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>`

Add link to demo from readme 2018-03-25 20:46:27 -04:00
			`<h2 id="demo">Demo</h2>`

move demo to folder 2018-03-26 10:36:47 -05:00			`Checkout the [demo page](./demo/) to see marked in action ⛹️`
Add link to demo from readme 2018-03-25 20:46:27 -04:00
			`These documentation pages are also rendered using marked 💯`


Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00			`<h2 id="installation">Installation</h2>`

			CLI: `npm install -g marked`

docs: Info to install @types/marked for ts projects (#2577) 2022-09-12 20:15:41 +07:00			`In-browser:`
			```
			`npm install marked`
			`npm install @types/marked # For TypeScript projects`
			```
Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00			`<h2 id="usage">Usage</h2>`

docs: add js-xss to sanitizer warning (#2484) close: #2482 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! 🚨`
chore(docs): add a secure example to the documentation. (#2462) * Add a sanitized example * Remove ! * move example below warning Co-authored-by: Florian Hantke <florian.hantke@cispa.de> 2022-05-07 18:37:21 +02:00
			```
			DOMPurify.sanitize(marked.parse(`<img src="x" onerror="alert('not happening')">`));
			```
add warning to README and docs 2018-06-24 01:56:52 -05:00
docs: Add note about zero width unicode characters (#2139) (#2605) 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
			`// remove the most common zerowidth characters from the start of the file`
			`marked.parse(`
			`contents.replace(/^[\u200B\u200C\u200D\u200E\u200F\uFEFF]/,"")`
			`)`
			```

Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00			`CLI`

			``` bash
chore(docs): Improved CLI Examples (#2303) 2021-11-24 22:19:58 +01:00			`# Example with stdin input`
Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00			`$ marked -o hello.html`
			`hello world`
			`^D`
			`$ cat hello.html`
			`<p>hello world</p>`
			```

add doc example 2018-04-01 23:25:53 -05:00			``` bash
chore(docs): Improved CLI Examples (#2303) 2021-11-24 22:19:58 +01:00			`# Example with string input`
add doc example 2018-04-01 23:25:53 -05:00			`$ marked -s "hello world"`
			`<p><em>hello world</em></p>`
			```

chore(docs): Improved CLI Examples (#2303) 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`
			```

Move existing docs to /docs dir 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>`
Move script to the bottom 2018-03-25 20:36:41 -04:00			`<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>`
Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00			`<script>`
			`document.getElementById('content').innerHTML =`
fix: Convert to ESM (#2227) BREAKING CHANGE: - Default export removed. Use `import { marked } from 'marked'` or `const { marked } = require('marked')` instead. - `/lib/marked.js` removed. Use `/marked.min.js` in script tag instead. - When using marked in a script tag use `marked.parse(...)` instead of `marked(...)` 2021-11-02 07:32:17 -07:00			`marked.parse('# Marked in browser\n\nRendered by marked.');`
Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00			`</script>`
			`</body>`
			`</html>`
			```

Update docs/INDEX.md Co-authored-by: Steven <steven@ceriously.com> 2020-09-21 09:57:04 -05:00			`Node.js`
add inline markdown docs 2020-09-21 00:00:45 -05:00
			```js
fix: Convert to ESM (#2227) BREAKING CHANGE: - Default export removed. Use `import { marked } from 'marked'` or `const { marked } = require('marked')` instead. - `/lib/marked.js` removed. Use `/marked.min.js` in script tag instead. - When using marked in a script tag use `marked.parse(...)` instead of `marked(...)` 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.');`
add inline markdown docs 2020-09-21 00:00:45 -05:00			```

Move existing docs to /docs dir 2018-03-11 17:16:48 -04:00
Use cleanUrls 2020-08-29 17:55:07 -04:00			`Marked offers [advanced configurations](/using_advanced) and [extensibility](/using_pro) as well.`
Move existing docs to /docs dir 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).`

clarify level of support for Markdown flavors fixes #1718 2020-07-06 16:47:39 -04:00			`\| Flavor \| Version \| Status \|`
			`\| :--------------------------------------------------------- \| :------ \| :----------------------------------------------------------------- \|`
			`\| The original markdown.pl \| -- \| \|`
fix: Convert to ESM (#2227) BREAKING CHANGE: - Default export removed. Use `import { marked } from 'marked'` or `const { marked } = require('marked')` instead. - `/lib/marked.js` removed. Use `/marked.min.js` in script tag instead. - When using marked in a script tag use `marked.parse(...)` instead of `marked(...)` 2021-11-02 07:32:17 -07:00			`\| [CommonMark](http://spec.commonmark.org/0.30/) \| 0.30 \| [Work in progress](https://github.com/markedjs/marked/issues/1202) \|`
clarify level of support for Markdown flavors fixes #1718 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) \|`
Move existing docs to /docs dir 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.`

docs: Adding Tools using Marked in docs (#2603) * Updating INDEX.md * Update _document.html Adding tools to navigation. 2022-10-06 18:36:28 +05:30			`<h2 id="tools">List of Tools Using Marked</h2>`

			We actively support the usability of Marked in super-fast markdown transformation, some of Tools using `Marked` for single-page creations are

			`\| 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. \|`
			`\| [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. \|`

Move existing docs to /docs dir 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.`

Use cleanUrls 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).`