diff --git a/README.md b/README.md
index 1c4516e..c27e7de 100644
--- a/README.md
+++ b/README.md
@@ -446,6 +446,19 @@ var showdown = require('showdown'),
converter = new showdown.Converter({ extensions: ['myExtension'] });
```
+## Building
+
+Building your clone of the repository is easy.
+> Prerequesites: [Node.js](https://nodejs.org/) v12, [npm](https://www.npmjs.com/package/npm) and [npx](https://www.npmjs.com/package/npx) must be installed.
+
+1. run `npm install`.
+2. run `npx grunt build` (see [`Gruntfile.js`](/Gruntfile.js)). This command:
+
+ 1. Cleans the repo.
+ 2. Checks code quality ([JSHint](https://jshint.com/) and [ESLint](https://eslint.org/)).
+ 3. Runs tests.
+ 4. Creates the [distributable](/showdown.js) and [minified](/showdown.min.js) files in the [`dist`](/dist) folder.
+
## Tests
A suite of tests is available which require Node.js. Once Node is installed, run the following command from
diff --git a/docs/assets/markdown-editor.png b/docs/assets/markdown-editor.png
new file mode 100644
index 0000000..b053399
Binary files /dev/null and b/docs/assets/markdown-editor.png differ
diff --git a/docs/cli.md b/docs/cli.md
index ddda916..d14754f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -150,4 +150,22 @@ showdown makehtml [options]
```sh
showdown makehtml -e ~/twitter.js -e ~/youtube.js
- ```
\ No newline at end of file
+ ```
+
+## Extra options
+
+You can specify any of the [supported options](available-options.md), and they will be passed to the converter.
+For example, you can enable strikethrough support via the following command:
+
+```
+showdown makehtml -i foo.md -o bar.html --strikethrough
+```
+
+this command is equivalent of doing:
+
+```js
+var conv = new showdown.Converter({strikethrough: true});
+```
+
+!!! warning ""
+ In the CLI tool, all the extra options are **disabled** by default. This is the opposite of what is defined for node and browser, where some options, like `ghCodeBlocks` are enabled (for backward compatibility and historical reasons).
diff --git a/docs/extensions-list.md b/docs/extensions-list.md
new file mode 100644
index 0000000..6a953ba
--- /dev/null
+++ b/docs/extensions-list.md
@@ -0,0 +1,24 @@
+## Official
+
+* [twitter-extension][1] - Adds support of Twitter usernames and hastags
+* [prettify-extension][2] - Adds [Google Prettify][3] hints to HTML output
+
+## Community
+
+* [showdown-icon][4] - Adds support of Glyphicon and font-awesome into Markdown
+* [showdown-xss-filter][5] - Filters XSS, using leizongmin/js-xss
+* [showdown-toc][6] - Adds Table of Contents
+* [showdown-footnotes][7] - Adds simple footnotes
+* [katex-latex][8] - Displays math using KaTeX and LaTeX or AsciiMath
+
+!!! note ""
+ If you have a Showdown extension you would like to add here, you can [raise an issue](https://github.com/showdownjs/showdown/issues).
+
+[1]: https://github.com/showdownjs/twitter-extension
+[2]: https://github.com/showdownjs/prettify-extension
+[3]: https://github.com/googlearchive/code-prettify
+[4]: https://github.com/dbtek/showdown-icon
+[5]: https://github.com/VisionistInc/showdown-xss-filter
+[6]: https://github.com/ravisorg/showdown-toc
+[7]: https://github.com/Kriegslustig/showdown-footnotes
+[8]: https://obedm503.github.io/showdown-katex
diff --git a/docs/markdown-syntax.md b/docs/markdown-syntax.md
new file mode 100644
index 0000000..4c4b8b7
--- /dev/null
+++ b/docs/markdown-syntax.md
@@ -0,0 +1,716 @@
+## Introduction
+
+Showdown was created by John Fraser as a direct port of the original parser written by Markdown's creator, John Gruber.
+
+Although Showdown has evolved since its inception, in "vanilla mode", it tries to follow the [original markdown spec][md-spec] (henceforth referred as vanilla) as much as possible. There are, however, a few important differences, mainly due to inconsistencies in the original spec, which Showdown addressed following the author's advice as stated in the [markdown's "official" newsletter][md-newsletter].
+
+Showdown also supports opt-in features, that is, an "extra" syntax that is not defined in the original spec. Users can enable these features via options (All the new syntax elements are disabled by default).
+
+This document provides a quick reference of the supported syntax and the differences in output from the original markdown.pl implementation.
+
+## Paragraphs
+
+Paragraphs in Showdown are **one or more lines of consecutive text** followed by one or more blank lines.
+
+```md
+On July 2, an alien mothership entered Earth's orbit and deployed several dozen
+saucer-shaped "destroyer" spacecraft, each 15 miles (24 km) wide.
+
+On July 3, the Black Knights, a squadron of Marine Corps F/A-18 Hornets,
+participated in an assault on a destroyer near the city of Los Angeles.
+```
+
+The implication of the "one or more consecutive lines of text" is that Showdown supports
+"hard-wrapped" text paragraphs. It means the following examples produce the same output:
+
+```md
+A very long line of text
+```
+
+```md
+A very
+long line
+of text
+```
+
+If you **do** want to add soft line breaks (which translate to `
` in HTML) to a paragraph,
+you can do so by adding 3 space characters to the end of the line.
+
+You can also force every line break in paragraphs to translate to `
` (as Github does) by
+enabling the option [**`simpleLineBreaks`**][simpleLineBreaks].
+
+[simpleLineBreaks]: available-options.md#simplelinebreaks
+
+## Headings
+
+### Atx Style
+
+You can create a heading by adding one or more `#` symbols before your heading text. The number of `#` determines the level of the heading. This is similar to [**atx style**][atx].
+
+```md
+# The 1st level heading (an
Here's an idea: why don't we take SuperiorProject
and turn it into **Reasonable**Project
.
```
to format text as its own distinct block.
+
+ Check out this neat program I wrote:
+
+ ```
+ x = 0
+ x = 2 + 2
+ what is x
+ ```
+
+[ghCodeBlocks]: available-options.md#ghcodeblocks
+
+## Lists
+
+Showdown supports unordered (bulleted) and ordered (numbered) lists.
+
+### Unordered lists
+
+You can make an unordered list by preceding list items with either `*`, `-`, or `+`. Markers are interchangeable too.
+
+```md
+* Item
++ Item
+- Item
+```
+
+### Ordered lists
+
+You can make an ordered list by preceding list items with a number.
+
+```md
+1. Item 1
+2. Item 2
+3. Item 3
+```
+
+!!! earning ""
+ The actual numbers you use to mark the list have no effect on the HTML output that Showdown produces. So you can use the same number in all items if you wish to. For example:
+
+ ```md
+ 1. Item 1
+ 1. Item 2
+ 1. Item 3
+
+ 2. Item 1
+ 2. Item 2
+ 2. Item 3
+ ```
+
+### TaskLists (GFM Style)
+
+Showdown supports GFM-styled takslists if the [**`tasklists`**][tasklists] option is enabled.
+
+```md
+ - [x] checked list item
+ - [ ] unchecked list item
+```
+
+ - [x] checked list item
+ - [ ] unchecked list item
+
+
+[tasklists]: available-options.md#tasklists
+
+### List syntax
+
+List markers typically start at the left margin, but may be indented by up to three spaces.
+
+```md
+* valid list item
+ * this is valid too
+ * this is too
+```
+
+List markers must be followed by one or more spaces or a tab.
+
+To make lists look nicer, you can wrap items with hanging indents:
+
+```md
+* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+ Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
+ viverra nec, fringilla in, laoreet vitae, risus.
+* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
+ Suspendisse id sem consectetuer libero luctus adipiscing.
+```
+
+But if you want to be lazy, you don't have to :grin:
+
+If one list item is separated by a blank line, Showdown will wrap all the list items in `` tags in the HTML output. +So this input: + +```md +* Bird + +* Magic +* Johnson +``` + +results in: + +```html +
Bird
Magic
Johnson
hey @tivie, check this out
+``` + +[mentions]: available-options.md#ghmentions +[ghMentionsLink]: available-options.md#ghmentionslink + +## Handle HTML in markdown documents + +Showdown, in most cases, leaves HTML tags untouched in the output document: + +```md +some markdown **here** +some markdown here
+` and `` tags is always escaped.
+
+```md
+some markdown **here** with foo & bar
+```
+
+```html
+some markdown here with foo & bar <baz></baz>
+```
+
+If you want to enable markdown parsing inside a specific HTML tag, you can use the html attribute **`markdown`**, **`markdown="1"`**, or **`data-markdown="1"`**.
+
+```md
+some markdown **here**
+this is *not* **parsed**
+```
+
+```html
+some markdown here
+this is not parsed
+```
+
+## Escape entities
+
+### Escape markdown entities
+
+Showdown allows you to use backslash (`\`) to escape characters that have special meaning in markdown's syntax and generate literal characters instead. For example, if you want to surround a word with literal underscores (instead of an HTML `` tag), you can use backslashes before the underscores, like this:
+
+```md
+\_literal underscores\_
+```
+
+Showdown provides backslash escapes for the following characters:
+
+```
+\ backslash
+` backtick
+* asterisk
+_ underscore
+{} curly braces
+[] square brackets
+() parentheses
+# hash mark
++ plus sign
+- minus sign (hyphen)
+. dot
+! exclamation mark
+```
+
+### Escape HTML tags
+
+Since [version 1.7.2](https://github.com/showdownjs/showdown/tree/1.7.2), backslash escaping of HTML tags is supported when [**`backslashEscapesHTMLTags`**][backslashEscapesHTMLTags] option is enabled.
+
+```md
+\a literal div\
+```
+
+[backslashEscapesHTMLTags]: available-options.md#backslashescapeshtmltags
+
+## Known differences and gotchas
+
+In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7. What follows is a list of all known deviations. Please file an issue if you find more.
+
+* **Since version 1.4.0, Showdown supports the markdown="1" attribute**, but for older versions, this attribute is ignored. This means:
+
+ ```md
+
+ Markdown does *not* work in here.
+
+ ```
+
+* You can only nest square brackets in link titles to a depth of two levels:
+
+ [[fine]](http://www.github.com/)
+ [[[broken]]](http://www.github.com/)
+
+ If you need more, you can escape them with backslashes.
+
+* A list is **single paragraph** if it has only **1 line break separating items** and it becomes **multi-paragraph if ANY of its items is separated by 2 line breaks**:
+
+ ```md
+ - foo
+
+ - bar
+ - baz
+ ```
+
+ becomes
+
+ ```html
+
+ foo
+ bar
+ baz
+
+ ```
+
+This new ruleset is based on the comments of Markdown's author John Gruber in the [Markdown discussion list][md-newsletter].
+
+[md-spec]: http://daringfireball.net/projects/markdown/
+[md-newsletter]: https://pairlist6.pair.net/mailman/listinfo/markdown-discuss
+[atx]: http://www.aaronsw.com/2002/atx/intro
+[setext]: https://en.wikipedia.org/wiki/Setext
+[readme]: https://github.com/showdownjs/showdown/blob/master/README.md
+[awkward effect]: http://i.imgur.com/YQ9iHTL.gif
+[emoji list]: https://github.com/showdownjs/showdown/wiki/emojis
\ No newline at end of file
diff --git a/docs/tutorials/add-default-class-to-html.md b/docs/tutorials/add-default-class-to-html.md
new file mode 100644
index 0000000..6181c83
--- /dev/null
+++ b/docs/tutorials/add-default-class-to-html.md
@@ -0,0 +1,60 @@
+# Add default class for each HTML element
+
+Many people use CSS kits like Bootstrap, Semantic UI, or others that require default name classes for HTML elements:
+
+```html
+1st Heading
+2nd Heading
+
+ - first item
+ - second item
+
+```
+
+Showdown does not support this out-of-the-box. But you can create an extension for this:
+
+```js
+const showdown = require('showdown');
+
+const classMap = {
+ h1: 'ui large header',
+ h2: 'ui medium header',
+ ul: 'ui list',
+ li: 'ui item'
+}
+
+const bindings = Object.keys(classMap)
+ .map(key => ({
+ type: 'output',
+ regex: new RegExp(`<${key}(.*)>`, 'g'),
+ replace: `<${key} class="${classMap[key]}" $1>`
+ }));
+
+const conv = new showdown.Converter({
+ extensions: [...bindings]
+});
+
+const text = `
+# 1st Heading
+## 2nd Heading
+
+- first item
+- second item
+`;
+```
+
+With this extension, the output will be as follows:
+
+```html
+1st Heading
+2nd Heading
+
+ - first item
+ - second item
+
+```
+
+## Credits
+
+* Initial creator: [@zusamann](https://github.com/zusamann), [(original issue)](https://github.com/showdownjs/showdown/issues/376).
+* Updated by [@Kameelridder](https://github.com/Kameelridder), [(original issue)](https://github.com/showdownjs/showdown/issues/509).
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
new file mode 100644
index 0000000..86720a8
--- /dev/null
+++ b/docs/tutorials/index.md
@@ -0,0 +1,5 @@
+# Tutorials
+
+* [Add default class for each HTML element](add-default-class-to-html.md)
+* [Markdown editor with Showdown](markdown-editor-with-showdown.md)
+* [Use language and output extensions on the same block](use-both-extension-types-together.md)
\ No newline at end of file
diff --git a/docs/tutorials/markdown-editor-with-showdown.md b/docs/tutorials/markdown-editor-with-showdown.md
new file mode 100644
index 0000000..8a2ace5
--- /dev/null
+++ b/docs/tutorials/markdown-editor-with-showdown.md
@@ -0,0 +1,143 @@
+# Markdown editor with Showdown
+
+## Introduction
+
+In this tutorial, you will create a simple in-browser Markdown editor using Showdown and some of its extensions. The purpose is to show how easy it is to include and configure Showdown in your project.
+
+The fully working example you can see in [Fiddle][1].
+
+## Step 1: Prepare project
+
+1. Install [node.js](https://nodejs.org/en/).
+1. Install project package management tool
+
+ !!! info ""
+ Showdown core library doesn't have any dependencies so the setup is pretty straightforward. However, you are strongly encouraged to use a package manager such as [**npm**](http://npmjs.com) or [**yarn**](https://yarnpkg.com) to manage project dependencies.
+
+ To install package management tool:
+
+ 1. Create a directory called `showdown-editor` and recreate the following structure:
+
+ ```
+ showdown-editor
+ ├── css
+ │ └── style.css
+ ├── js
+ │ └── script.js
+ └── index.html
+ ```
+
+ 1. Initialize `package.json` file by running the following interactive console command:
+
+ ```
+ npm init -y
+ ```
+
+ This command creates `package.json` file in the root of the project folder, and populates the default content that you can change later if you wish.
+
+## Step 2: Install Showdown
+
+Inside the `showdown-editor` directory, run the following command:
+
+```
+npm install showdown --save
+```
+
+This command will install `showdown` inside the `node_modules` directory and save `showdown` as a dependency in the `package.json` file.
+
+## Step 3: Update project files
+
+Add the following content to the corresponding project files:
+
+=== "index.html"
+
+ ```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ```
+
+ !!! warning ""
+ Please note how Showdown and the script file are included to the `index.html` via the `script` tag at the bottom of the file.
+
+=== "style.css"
+
+ ```css
+ #sourceTA {
+ display: block;
+ }
+ #targetDiv {
+ border: 1px dashed #333333;
+ width: 600px;
+ height: 400px;
+ }
+ ```
+
+=== "script.js"
+
+ ```js
+ function run() {
+ var text = document.getElementById('sourceTA').value,
+ target = document.getElementById('targetDiv'),
+ converter = new showdown.Converter(),
+ html = converter.makeHtml(text);
+
+ target.innerHTML = html;
+ }
+ ```
+
+ The `script.js` file is simple: when the `runBtn` button is clicked, the script gets the text of the textarea, passes it through Showdown to convert the markdown text into HTML. The resulting HTML is then put inside the `targetDiv`, replacing the previous content.
+
+## Step 4: Check the result
+
+1. Open your `index.html` file. You should see your editor with prefilled markdown text in the text area.
+1. Click `Convert` button. You show see the text to be converted to HTML:
+
+ ![](../assets/markdown-editor.png)
+
+The fully working example you can see in [Fiddle][1].
+
+## Conclusion
+
+Congratulations! :tada: You have successfully created a simple Markdown editor!
+
+[1]: http://jsfiddle.net/tivie/6bnpptkb/
\ No newline at end of file
diff --git a/docs/tutorials/use-both-extension-types-together.md b/docs/tutorials/use-both-extension-types-together.md
new file mode 100644
index 0000000..6b673b7
--- /dev/null
+++ b/docs/tutorials/use-both-extension-types-together.md
@@ -0,0 +1,62 @@
+# Use language and output extensions on the same block
+
+## Overview
+
+Showdown allows you to define and use any number of extensions that act on the same block. These extensions can be executed sequentially or at different moments.
+
+This enables you to pre-parse/mark a block of text but defer any modifications for the last by using a combination of language and output extensions.
+
+This is useful if you, for example, don't want Showdown to parse the contents of your new language construct.
+
+## Example
+
+Let's say you create an extension that captures everything between `%start%` and `%end%`. However, that content should not be modified by Showdown. Obviously, you can use `` tags but that is beside the point.
+
+Although Showdown doesn't have any flag to prevent parsing the content of an extension, the same effect can be easily achieved by using lang and output extensions together.
+
+!!! example ""
+ The fully working example you can see in [Fiddle][1].
+
+### Code
+
+[Create your extensions](../create-extension.md) with the following content:
+
+```js
+showdown.extension('myExt', function() {
+ var matches = [];
+ return [
+ {
+ type: 'lang',
+ regex: /%start%([^]+?)%end%/gi,
+ replace: function(s, match) {
+ matches.push(match);
+ var n = matches.length - 1;
+ return '%PLACEHOLDER' + n + '%';
+ }
+ },
+ {
+ type: 'output',
+ filter: function (text) {
+ for (var i=0; i< matches.length; ++i) {
+ var pat = '%PLACEHOLDER' + i + '% *<\/p>';
+ text = text.replace(new RegExp(pat, 'gi'), matches[i]);
+ }
+ //reset array
+ matches = [];
+ return text;
+ }
+ }
+ ]
+});
+```
+
+In this example, you created a [`lang` extension](../create-extension.md#type) that:
+
+1. Checks for the pseudo tags `%start%` and `%end%`.
+1. Extracts everything in between the tags.
+1. Saves the content between the tags in a variable.
+1. Replaces the saved content with a placeholder to identify the exact position of the extracted text.
+
+and an [`output` extension](../create-extension.md#type) that replaces the placeholder with the saved content, once Showdown is finished parsing.
+
+[1]: http://jsfiddle.net/tivie/1rqr7xy8/
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 6dd4ae7..a65425c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -15,6 +15,7 @@ markdown_extensions:
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
+ - pymdownx.tasklist
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
@@ -32,6 +33,7 @@ nav:
- Donations: donations.md
- Quickstart:
- Quickstart: quickstart.md
+ - Showdown's Markdown syntax: markdown-syntax.md
- Compatibility: compatibility.md
- Configuration:
- Showdown options: configuration.md
@@ -41,4 +43,6 @@ nav:
- Integrations: integrations.md
- Extensions:
- Overview: extensions.md
- - Create an extension: create-extension.md
\ No newline at end of file
+ - Create an extension: create-extension.md
+ - List of known extensions: extensions-list.md
+ - Tutorials: tutorials/index.md
\ No newline at end of file