StarMirror
/
showdown
mirror of https://github.com/showdownjs/showdown
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'develop' into feat/910-auto-linking-mention-from-html-to-markdown

feat/910-auto-linking-mention-from-html-to-markdown
Estevão Soares dos Santos 2022-04-16 20:10:29 +01:00
parent 3c2e25a3c7 1cf1908935
commit 947ec9bdd4
10 changed files with 1047 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

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

BIN
docs/assets/markdown-editor.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 129 KiB

20
docs/cli.md
View File

@ -150,4 +150,22 @@ showdown makehtml [options]
```sh
showdown makehtml -e ~/twitter.js -e ~/youtube.js
```
```
## 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).

24
docs/extensions-list.md Normal file
View File

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

716
docs/markdown-syntax.md Normal file
View File

@ -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 `<br>` 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 `<br>` (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 <h1> tag)
## The 2nd level heading (an <h2> tag)
…
###### The 6th level heading (an <h6> tag)
```
The space between `#` and the heading text is not required but you can make it mandatory by enabling the option [**`requireSpaceBeforeHeadingText`**][requireSpaceBeforeHeadingText].
[requireSpaceBeforeHeadingText]: available-options.md#requirespacebeforeheadingtext
You can wrap the headings in `#`. Both leading and trailing `#` will be removed.
```md
## My Heading ##
```
If, for some reason, you need to keep a leading or trailing `#`, you can either add a space or escape it:
```md
# # My header # #
#\# My Header \# #
```
### Setext style
You can also use [**setext style**][setext] headings, although only two levels are available.
```md
This is an H1
=============
This is an H2
-------------
```
!!! warning ""
There is an awkward effect when a paragraph is followed by a list. This effect appears on some circumstances, in live preview editors.
![awkward effect][]
You can prevent this by enabling the option [**`smoothPreview`**][smoothlivepreview].
[smoothlivepreview]: available-options.md#smoothlivepreview
### Header IDs
Showdown automatically generates bookmark anchors in titles by adding an id property to a heading.
```md
# My cool header with ID
```
```html
<h1 id="mycoolheaderwithid">My cool header with ID</h1>
```
This behavior can be modified with options:
- [**`noHeaderId`**][noHeaderId] disables automatic id generation;
- [**`ghCompatibleHeaderId`**][ghCompatibleHeaderId] generates header ids compatible with github style (spaces are replaced with dashes and a bunch of non alphanumeric chars are removed)
- [**`prefixHeaderId`**][prefixHeaderId] adds a prefix to the generated header ids (either automatic or custom).
- [**`headerLevelStart`**][headerLevelStart] sets the header starting level. For instance, setting this to 3 means that `# header` will be converted to `<h3>`.
Read the [README.md][readme] for more info
[noHeaderId]: available-options.md#noheaderid
[ghCompatibleHeaderId]: available-options.md#ghcompatibleheaderid
[prefixHeaderId]: available-options.md#prefixheaderid
[headerLevelStart]: available-options.md#headerlevelstart
## Blockquotes
You can indicate blockquotes with a `>`.
```md
In the words of Abraham Lincoln:
> Pardon my french
```
Blockquotes can have multiple paragraphs and can have other block elements inside.
```md
> A paragraph of text
>
> Another paragraph
>
> - A list
> - with items
```
## Bold and Italic
You can make text bold or italic.
```md
*This text will be italic*
**This text will be bold**
```
Both bold and italic can use either a `*` or an `_` around the text for styling. This allows you to combine both bold and italic if needed.
```md
**Everyone _must_ attend the meeting at 5 o'clock today.**
```
## Strikethrough
With the option [**`strikethrough`**][] enabled, Showdown supports strikethrough elements.
The syntax is the same as GFM, that is, by adding two tilde (`~~`) characters around
a word or groups of words.
```md
a ~~strikethrough~~ element
```
a <s>strikethrough</s> element
[strikethrough]: available-options.md#strikethrough
## Emojis
Since version 1.8.0, Showdown supports Github's emojis. A complete list of available emojis can be found [here][emoji list].
```md
this is a :smile: smile emoji
```
this is a :smile: smile emoji
## Code formatting
### Inline formats
Use single backticks (`) to format text in a special monospace format. Everything within the backticks appear as-is, with no other special formatting.
```md
Here's an idea: why don't we take `SuperiorProject` and turn it into `**Reasonable**Project`.
```
```html
<p>Here's an idea: why don't we take <code>SuperiorProject</code> and turn it into <code>**Reasonable**Project</code>.</p>
```
### Multiple lines
To create blocks of code you should indent it by four spaces.
```md
this is a piece
of
code
```
If the option [**`ghCodeBlocks`**][ghCodeBlocks] is activated (which is by default), you can use triple backticks <code>```</code> 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 `<p>` tags in the HTML output.
So this input:
```md
* Bird
* Magic
* Johnson
```
results in:
```html
<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
<li><p>Johnson</p></li>
</ul>
```
This differs from other Markdown implementations such as GFM (GitHub) or CommonMark.
### Nested blocks
List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab:
```md
1. This is a list item with two paragraphs. 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.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
```
This is valid for other block elements such as blockquotes:
```md
* A list item with a blockquote:
> This is a blockquote
> inside a list item.
```
or even other lists.
### Nested lists
You can create nested lists by indenting list items by **four** spaces.
```md
1. Item 1
1. A corollary to the above item.
2. Yet another point to consider.
2. Item 2
* A corollary that does not need to be ordered.
* This is indented four spaces
* You might want to consider making a new list.
3. Item 3
```
This behavior is consistent with the original spec but differs from other implementations such as GFM or CommonMark. Prior to version 1.5, you just needed to indent two spaces for it to be considered a sublist.
You can disable the **four spaces requirement** with option [**`disableForced4SpacesIndentedSublists`**][disableForced4SpacesIndentedSublists]
To nest a third (or more) sublist level, you need to indent 4 extra spaces (or 1 extra tab) for each level:
```md
1. level 1
1. Level 2
* Level 3
2. level 2
1. Level 3
1. Level 1
```
[disableForced4SpacesIndentedSublists]: available-options.md#disableforced4spacesindentedsublists
### Nested code blocks
You can nest fenced codeblocks the same way you nest other block elements, by indenting by four spaces or a tab:
```md
1. Some code:
```js
var foo = 'bar';
console.log(foo);
```
```
To put an *indented style* code block within a list item, the code block needs to be indented twice — 8 spaces or two tabs:
```md
1. Some code:
var foo = 'bar';
console.log(foo);
```
## Links
### Simple
If you wrap a valid URL or email in `<>` it will be turned into a link whose text is the link itself.
```md
link to <http://www.google.com/>
this is my email <somedude@mail.com>
```
In the case of email addresses, Showdown also performs a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots.
You can disable this obfuscation by setting [**`encodeEmails`**][encodeEmails] option to `false`.
With the option [**`simplifiedAutoLink`**][simplifiedAutoLink] enabled, Showdown will automagically turn every valid URL it finds in the text body into links without the need to wrap them in `<>`.
```md
link to http://www.google.com/
this is my email somedude@mail.com
```
[encodeEmails]: available-options.md#encodeemails
[simplifiedAutoLink]: available-options.md#simplifiedautolink
### Inline
You can create an inline link by wrapping link text in brackets `[ ]`, and then wrapping the link in parentheses `( )`.
For example, a hyperlink to `github.com/showdownjs/showdown`, with a link text that says, `Get Showdown!` will look as follows:
```
[Get Showdown!](https://github.com/showdownjs/showdown)
```
### Reference Style
You can also use the reference style, like this:
```md
this is a [link to google][1]
[1]: www.google.com
```
Showdown also supports implicit link references:
```md
this is a link to [google][]
[google]: www.google.com
```
## Images
In Markdown, the syntax for images is similar to that of links, supporting both inline and reference styles as well. The only difference in syntax for images is the leading exclamation mark before brackets: `![]`.
### Inline
Inline image syntax looks like this:
```md
![Alt text](url/to/image)
![Alt text](url/to/image "Optional title")
```
That is:
* An exclamation mark: `!`
* followed by a set of square brackets `[ ]` containing the alt attribute text for the image
* followed by a set of parentheses `( )` containing the URL or path to the image and an optional title attribute enclosed in double or single quotes.
### Reference Style
Reference-style image syntax looks like this:
```md
![Alt text][id]
```
Where `id` is the name of a defined image reference. Image references are defined using syntax identical to link references:
```md
[id]: url/to/image "Optional title attribute"
```
Implicit references are also supported:
```md
![showdown logo][]
[showdown logo]: http://showdownjs.github.io/demo/img/editor.logo.white.png
```
### Image dimensions
When the option [**`parseImgDimensions`**][parseImgDimensions] is activated, you can define the image dimensions, like this:
```md
![Alt text](url/to/image =250x250 "Optional title")
```
or in reference style:
```md
![Alt text][id]
[id]: url/to/image =250x250
```
[parseImgDimensions]: available-options.md#parseimgdimensions
### Base64 encoded images
Showdown supports Base64 encoded images, both reference and inline style.
**Since version 1.7.4**, Showdown supports wrapping of base64 strings, which are usually extremely long lines of text.
You can add newlines arbitrarily, as long as they are added after the `,` character.
inline style
```md
![Alt text](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAADCAIAAAA7l
jmRAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAY
SURBVBhXYwCC/2AAZYEoOAMs8Z+BgQEAXdcR7/Q1gssAAAAASUVORK5CYII=)
```
reference style
```md
![Alt text][id]
[id]:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAADCAIAAAA7l
jmRAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7D
AcdvqGQAAAAYSURBVBhXYwCC/2AAZYEoOAMs8Z+BgQEAXdcR7/Q1gssAAAAASUVORK5CYII=
```
!!! warning ""
With reference-style base64 image sources, regardless of "wrapping", a double newline is **required** after the base64 string to separate them from a paragraph or other text block (but references can be adjacent):
!!! example "Wrapped reference style"
```md
![Alt text][id]
![Alt text][id2]
[id]:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAADCAIAAAA7l
jmRAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7D
AcdvqGQAAAAYSURBVBhXYwCC/2AAZYEoOAMs8Z+BgQEAXdcR7/Q1gssAAAAASUVORK5CYII=
[id2]:
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAADCAIAAAA7l
jmRAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7D
AcdvqGQAAAAYSURBVBhXYwCC/2AAZYEoOAMs8Z+BgQEAXdcR7/Q1gssAAAAASUVORK5CYII=
this text needs to be separated from the references by 2 newlines
```
## Tables
Tables aren't part of the core Markdown spec, but they are part of GFM. You can enable them in Showdown via the option [**`tables`**][tables].
* Colons can be used to align columns.
* The outer pipes (`|`) are optional, matching GFM spec.
* You don't need to make the raw Markdown line up prettily.
* You can use other Markdown syntax inside them.
```md
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| **col 3 is** | right-aligned | $1600 |
| col 2 is | *centered* | $12 |
| zebra stripes | ~~are neat~~ | $1 |
```
[tables]: available-options.md#tables
## Mentions
Showdown supports GitHub mentions by enabling the option [**`ghMentions`**][mentions]. This will turn every `@username` into a link to their github profile.
```md
hey @tivie, check this out
```
Since version 1.6.2, you can customize the generated link in mentions with the option [**`ghMentionsLink`**][ghMentionsLink].
For example, setting this option to `http://mysite.com/{u}/profile`:
```html
<p>hey <a href="http://mysite.com/tivie/profile">@tivie</a>, check this out</p>
```
[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**
<div>this is *not* **parsed**</div>
```
```html
<p>some markdown <strong>here</strong></p>
<div>this is *not* **parsed**</div>
```
However, the content of `<code>` and `<pre><code>` tags is always escaped.
```md
some markdown **here** with <code>foo & bar <baz></baz></code>
```
```html
<p>some markdown <strong>here</strong> with <code>foo &amp; bar &lt;baz&gt;&lt;/baz&gt;</code></p>
```
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**
<div markdown="1">this is *not* **parsed**</div>
```
```html
<p>some markdown <strong>here</strong></p>
<div markdown="1"><p>this is <em>not</em> <strong>parsed</strong></p></div>
```
## 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 `<em>` 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
\<div>a literal div\</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
<div markdown="1">
Markdown does *not* work in here.
</div>
```
* 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
<ul>
<li><p>foo</p></li>
<li><p>bar</p></li>
<li><p>baz</p></li>
</ul>
```
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

60
docs/tutorials/add-default-class-to-html.md Normal file
View File

@ -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
<h1 class="ui large header">1st Heading</h1>
<h2 class="ui medium header">2nd Heading</h2>
<ul class="ui list">
<li class="ui item">first item</li>
<li class="ui item">second item</li>
</ul>
```
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
​​​​​<h1 class="ui large header">1st Heading</h1>​​​​​
​​​​​<h2 class="ui medium header">2nd Heading</h2>​​​​​
​​​​​<ul class="ui list">​​​​​
​​​​​<li class="ui item">first item</li>​​​​​
​​​​​<li class="ui item">second item</li>​​​​​
​​​​​</ul>​​​​​
```
## 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).

5
docs/tutorials/index.md Normal file
View File

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

143
docs/tutorials/markdown-editor-with-showdown.md Normal file
View File

@ -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
<!DOCTYPE HTML>
<html>
<head>
<meta charset="UTF-8"/>
<link rel="stylesheet" href="css/style.css"/>
</head>
<body>
<textarea id="sourceTA" rows="10" cols="82">
Showdown Tutorial
=================
This is a showdown tutorial.
Showdown supports a number of cool features, namely:
- headers
- lists
- and other stuff too
It is also possible to include code:
var foo = 'bar';
var baz = {
markdown: 'is great',
showdown: 'is awesome'
}
Don't forget to check the [extensions wiki][1].
[1]: https://github.com/showdownjs/showdown/wiki/extensions
</textarea>
<hr/>
<button id="runBtn" onClick="run()">Convert</button>
<hr/>
<div id="targetDiv"></div>
<script src="node_modules/showdown/dist/showdown.min.js"></script>
<script src="js/script.js"></script>
</body>
</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/

62
docs/tutorials/use-both-extension-types-together.md Normal file
View File

@ -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 `<pre>` 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 = '<p>%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/

6
mkdocs.yml
View File

@ -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
- Create an extension: create-extension.md
- List of known extensions: extensions-list.md
- Tutorials: tutorials/index.md