smarkdown/README.md

# Smarkdown

[![npm](https://badgen.net/npm/v/smarkdown)](https://www.npmjs.com/package/smarkdown)
[![gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/smarkdown/dist/smarkdown.min.js?compression=gzip)](https://cdn.jsdelivr.net/npm/smarkdown/dist/smarkdown.min.js)
[![install size](https://badgen.net/packagephobia/install/smarkdown)](https://packagephobia.now.sh/result?p=smarkdown)
[![downloads](https://badgen.net/npm/dt/smarkdown)](https://www.npmjs.com/package/smarkdown)
[![Build Status](https://travis-ci.org/yahtnif/smarkdown.svg?branch=master)](https://travis-ci.org/yahtnif/smarkdown)

> Markdown parser, simplicity and extensibility. Fork of [marked](https://github.com/markedjs/marked) and [marked-ts](https://github.com/KostyaTretyak/marked-ts).


## Features

* **Awesome:** ES6, TypeScript, Rollup, Jest...
* **Extensible:** Add your own [extensions](#extensions)
* **Fast:** Low-level compiler for parsing markdown without caching or blocking for long periods of time
* **Lightweight:** It's 9kb of minified and gzipped


## Table of contents

* [Installation](#installation)
* [Usage](#usage)
* [Option](#option)
* [Extension](#extension)
* [Renderer](#renderer)
* [Comparison](#comparison)
* [License](#license)


## Installation

```sh
npm install smarkdown
# or
yarn add smarkdown
```

**browser (CDN):**

* [jsDelivr](https://www.jsdelivr.com/package/npm/smarkdown)
* [unpkg](https://unpkg.com/smarkdown/)


## Usage

Import the library as a module:

```js
import Smarkdown from 'smarkdown'
```

Or import the library with a script tag:

```html
<script src="https://cdn.jsdelivr.net/npm/smarkdown/dist/smarkdown.min.js"></script>
```

Example:

```js
// Resetting option
Smarkdown.resetOption()

// Setting option
Smarkdown.setOption({
  breaks: true
})

const str = 'I am using **Smarkdown**.'

console.log(Smarkdown.parse(str))
// <p>I am using <strong>Smarkdown</strong>.</p>

console.log(Smarkdown.parse(str, { nop: true }))
// I am using <strong>Smarkdown</strong>.
```

### Syntax highlighting

````js
// highlight.js
import Smarkdown from 'smarkdown'
import { highlight } from 'highlight.js'

Smarkdown.setOption({
  highlight: (code, lang) => {
    return lang && highlight.getLanguage(lang)
      ? highlight.highlight(lang, code).value
      : highlight.highlightAuto(code).value
  }
})
````

````js
// prismjs
import Smarkdown from 'smarkdown'
import Prism from 'prismjs'
import 'prismjs/components/prism-markdown'

Smarkdown.setOption({
  highlight: (code, lang) => {
    const language = Prism.languages[lang] ? lang : 'markdown'

    return Prism.highlight(code, Prism.languages[language], language)
  }
})
````


## Option

| Name | Type | Default | Note |
| :-: | :-: | :-: | :-: |
| baseUrl | String | null | A prefix url for any relative link. |
| breaks | Boolean | false | If true, add `<br>` on a single line break (copies GitHub). Requires `gfm` be `true`. |
| disabledRules | Array | [] | If set to `['lheading']`, will disable headers of an underline-ish style. |
| extra | Boolean | false | If true, enable `footnote`. Requires `gfm` be `true`. |
| gfm | Boolean | true | If true, use approved [GitHub Flavored Markdown (GFM) specification](https://github.github.com/gfm/). |
| headerId | Boolean \| String | false | Include an `id` attribute when emitting headings.<br>If true, for all headings.<br>If set to `on`, for “non-close” atx-style headings (## h2, etc).<br>If set to `off`, for “close” atx-style headings (## h2 ##, etc).|
| headerPrefix | String | '' | A string to prefix the id attribute when emitting headings. |
| highlight | Function | (code, lang) => string | A function to highlight code blocks, see [Syntax highlighting](#syntax-highlighting) |
| langAttribute | Boolean | false | If `true`, add `data-lang` attribute to highlight block code. |
| langPrefix | String | 'language-' | A string to prefix the className in a `<code>` block. Useful for syntax highlighting. |
| linksInNewTab | Boolean \| Function | false | If true, open links in new tabs. |
| mangle | Boolean | true | If true, autolinked email address is escaped with HTML character references. |
| nop | Boolean | false | If `true`, an inline text will not be taken in paragraph. |
| pedantic | Boolean | false | If true, conform to the original `markdown.pl` as much as possible. Don't fix original markdown bugs or behavior. Turns off and overrides `gfm`. |
| renderer | Renderer | Renderer | An object containing functions to render tokens to HTML. See [Renderer](#renderer) for more details. |
| sanitize | Boolean | false | If true, sanitize the HTML passed into `markdownString` with the `sanitizer` function. |
| sanitizer | Function | null | A function to sanitize the HTML passed into `markdownString`. |
| silent | Boolean | false | If true, the parser does not throw any exception. |
| slug | Function | str => built_in_slug(str) | Slugify `id` attribute for heading and footnote. |
| smartLists | Boolean | false | If true, use smarter list behavior than those found in `markdown.pl`. |
| smartypants | Boolean | false | If true, use "smart" typographic punctuation for things like quotes and dashes. |
| trimLinkText | Function | null | Useful for text truncation. |
| xhtml | Boolean | false | Self-close the tags for void elements (&lt;br/&gt;, &lt;img/&gt;, etc.) with a "/" as required by XHTML. |


## Extension

Using `Smarkdown.setRule(regExp, callback, [, option])`, which takes a regular expression as the first argument, and returns result `regExp.exec(string)` to `callback(execArr)`, which can be passed as a second argument.

`regExp` **MUST** start with `^`.

Extension option:

| Name | Type | Default | inline | block |
| :-: | :-: | :-: | :-: | :-: |
| priority | Number | null | ✓ | ✓ |
| checkPreChar | Function | null | ✓ | |

### Inline

```js
/**
 * sub
 *
 * H~2~O
 * H<sub>2</sub>O
 */
const subRegex = /^~(?=\S)([\s\S]*?\S)~/
Smarkdown.setRule(subRegex, function(execArr) {
  return `<sub>${this.output(execArr[1])}</sub>`
})

/**
 * sup
 *
 * 1^st^
 * 1<sup>st</sup>
 */
const supRegex = /^\^(?=\S)([\s\S]*?\S)\^/
Smarkdown.setRule(supRegex, function(execArr) {
  return `<sup>${this.output(execArr[1])}</sup>`
})

/**
 * mark
 *
 * ==Experience== is the best teacher.
 * <mark>Experience</mark> is the best teacher.
 */
const markRegex = /^==(?=\S)([\s\S]*?\S)==/
Smarkdown.setRule(markRegex, function(execArr) {
  return `<mark>${this.output(execArr[1])}</mark>`
})

/**
 * hashtag
 *
 * #tag
 * <span class="hashtag">tag</span>
 */
const hashtagRegex = /^#([^\s#]+)((?:\b)|(?=\s|$))/
Smarkdown.setRule(
  hashtagRegex,
  function(execArr) {
    return `<span class="hashtag">${execArr[1]}</span>`
  }, {
    checkPreChar (char) {
      return !char || /\s|\B/.test(char)
    }
  }
)

/**
 * ruby annotation
 *
 * [注音]{zhuyin}
 * <ruby>注音<rt>zhuyin</rt></ruby>
 */
const rubyAnnotationRegex = /^\[([^\[\]{}]+)\]\{([^\[\]{}]+)\}/
Smarkdown.setRule(
  rubyAnnotationRegex,
  function(execArr) {
    return `<ruby>${execArr[1]}<rt>${execArr[2]}</rt></ruby>`
  },
  {
    priority: 1
  }
)

/**
 * small text
 *
 * --small text-- => <span class="small-text">small text</span>
 */
const smallTextRegex = /^--(?=\S)([\s\S]*?\S)--/
Smarkdown.setRule(smallTextRegex, function(execArr) {
  return `<span class="small-text">${execArr[1]}</span>`
})

/**
 * large text
 *
 * ++large text++ => <span class="large-text is-1">large text</span>
 * +++large text+++ => <span class="large-text is-2">large text</span>
 * ++++large text++++ => <span class="large-text is-3">large text</span>
 */
const largeTextRegex = /^(\+{2,})(?=\S)([\s\S]*?\S)\+{2,}/
Smarkdown.setRule(largeTextRegex, function(execArr) {
  let size = execArr[1].length - 1

  if (size > 3) {
    size = 3
  }

  return `<span class="large-text is-${size}">${execArr[2]}</span>`
})
```

### Block

```js
// block container
const extRegex = /^::: *([\w-_]+) *\n([\s\S]*?)\n:::\s?/
Smarkdown.setRule(extRegex, (execArr) => {
  return `<div class="${execArr[1]}">${execArr[2]}</div>`
})

const str = `::: warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit lorem ipsum dolor.
:::`

console.log(Smarkdown.parse(str))

// <div class="warning">Lorem ipsum dolor sit amet, consectetur adipiscing elit lorem ipsum dolor.</div>
```

### Unset

```js
Smarkdown.unsetRule(regExp)
```


## Renderer

### Methods

```js
//*** Block level renderer methods. ***

blockquote(quote)

code(code, lang, escaped)

footnote(footnotes)

heading(text, level, raw, ends)

hr()

html(html)

list(body, ordered, start, isTaskList)

listitem(text, checked)

paragraph(text)

table(header, body)

tablerow(content)

tablecell(content, flags)

//*** Inline level renderer methods. ***

br()

codespan(text)

del(text)

em(text)

fnref(refname)

image(href, title, text)

link(href, title, text)

strong(text)

text(text)
```

### Overriding Renderer methods

```js
import Smarkdown from 'smarkdown'

class NewRenderer extends Smarkdown.Renderer {
  // Overriding parent method.
  table(header, body) {
    if (body) body = '<tbody>' + body + '</tbody>'

    // add class .table to table
    return `
<table class="table">
<thead>
${header}</thead>
${body}</table>
`
  }
}

Smarkdown.setOption({ renderer: NewRenderer })
// or pass new option to new Renderer
Smarkdown.setOption({ renderer: new NewRenderer(NewOption) })
```


## Comparison

| | Smarkdown | Marked | markdown-it |
| :-: | :-: | :-: | :-: |
| Version | [![npm](https://badgen.net/npm/v/smarkdown)](https://www.npmjs.com/package/smarkdown) | [![npm](https://badgen.net/npm/v/marked)](https://www.npmjs.com/package/marked) | [![npm](https://badgen.net/npm/v/markdown-it)](https://www.npmjs.com/package/markdown-it) |
| Minified & Gzipped | [![gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/smarkdown/dist/smarkdown.min.js?compression=gzip)](https://cdn.jsdelivr.net/npm/smarkdown/dist/smarkdown.min.js) | [![gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/marked/marked.min.js?compression=gzip)](https://cdn.jsdelivr.net/npm/marked/marked.min.js) | [![gzip size](https://img.badgesize.io/https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js?compression=gzip)](https://cdn.jsdelivr.net/npm/markdown-it/dist/markdown-it.min.js) |


## License

[MIT](http://opensource.org/licenses/MIT)