## 1. Project Overview & Quickstart (showdownjs/api-reference)

# api-reference

Open-source repository showdownjs/api-reference

### Repository Details
- **Repository:** [showdownjs/api-reference](https://github.com/showdownjs/api-reference)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (showdownjs/showdownjs.github.io)

## File: README.md

# showdownjs.github.io

[](https://github.com/showdownjs/showdownjs.github.io/actions/workflows/docs.yml) [](https://github.com/showdownjs/showdownjs.github.io/actions/workflows/pages/pages-build-deployment)

[Showdown website](https://showdownjs.com/) and [documentation](https://showdownjs.com/docs/)

---

## File: manifest.json

{
    "name": "",
    "icons": [
        {
            "src": "/android-chrome-192x192.png",
            "sizes": "192x192",
            "type": "image/png"
        },
        {
            "src": "/android-chrome-512x512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ],
    "theme_color": "#ffffff",
    "background_color": "#ffffff",
    "display": "standalone"
}

---

## File: params.json

{
  "name": "Showdown",
  "tagline": "An extensible Markdown to HTML converter written in Javascript",
  "body": "Showdown is a Javascript Markdown to HTML converter. Showdown can be used client side (in the browser) or server side (with NodeJs).",
  "google": "",
  "note": "Don't delete this file! It's used internally to help with page regeneration."
}

---

## File: blog/annoucement-showdown-2.0.md

«««
title: Annoucement: Showdown 2.0,
author: Estevão Soares dos Santos,
author_avatar: img/avatars/tivie.jpg,
date: 2017-12-12,
language: en,
image: img/blog/2017.12.12.jpg,
summary: Showdown version 1.0.0 was released almost 3 years ago, back in May 2015.
    Since then, it has seen a lot of improvements, with a boost to performance and a significant number of features now
    included in the core of the library. However, do to backwards compatibility constrains, we are still supporting a
    lot of legacy features, that prevent us from moving the software forward.
    With that in mind, **it is time to start thinking about Showdown version 2.0.**
    For the next major release of Showdown we have planned a range of **significant changes and additions**.
»»»
Showdown version 1.0.0 was released almost 3 years ago, back in May 2015.
Since then, it has seen a lot of improvements, with a boost to performance and
a significant number of features now included in the core of the library.

However, do to backwards compatibility constrains, we are still supporting a lot
of legacy features, that prevent us from moving the software forward.

With that in mind, **it is time to start thinking about Showdown version 2.0.**

For the next major release of Showdown we have planned a range of **significant changes
and additions**. Here are a few of the most important ones:

## Reverse Conversion (HTML to MD)

Being a popular request by our users, we though that a new major version is the perfect
opportunity to implement this feature.

This feature requires a number of changes throughout the code and API. For instance,
the extension system must be redesigned to allow for extensions to hook unto both
processes (HTML->MD and MD->HTML). Event and option names must also reflect this
since, as they stand now, they might cause confusion.

## Extensions

We are (finally) **completely dropping support for legacy extensions**. Although there are a
couple old ones still in the wild, most of them (if not all) have already
migrated to the modern extension system.

We are also revamping the extension system. For starters, **we're dropping old "lang"
and "output" extension in favour of event extensions**.

The **API of event extensions will also change** in order to mimic the browser events
and play nicely with other libraries and frameworks.

## Subparsers

**Subparsers will also see a major code refactoring**, with performance improvements.
Although performance is no longer an issue, mainly due to the way new browsers
handle Regular Expressions, there are a couple of issues that still need to be addressed.
Most of the issues can be fixed if we drop support for old browsers and old nodejs versions.

## Development

Formally, Showdown 2.0 will start development in the beginning of 2018 and all
development efforts will be put into it.
This means **Showdown 1.x will now enter maintenance mode, that is, no new features
will be added** and only important bugfixes will be committed.

We expect to release an alpha version of Showdown 2.0 somewhere around ~~August 2018,~~
the fall of 2018. ***So, if you are as excited as we are, stay tuned for more information***.

---

## File: blog/patreon-launch.md

«««
title: We Just Launched Patreon!,
author: Estevão Soares dos Santos,
author_avatar: img/avatars/tivie.jpg,
date: 2018-11-03,
language: en,
image: img/blog/2018.11.03.jpg,
summary: I'm very happy to say that Patreon is Up! Check out the cool rewards I have planned for you. And there is also a surprise announcement regarding a new release...
»»»

I am very proud to announce the launch of [Showdown's Patreon page!][patreon] 

This allows you to support me as a developer and make a better future for this library.

Please check out the very very cool rewards I planned for you and/or your company!

Also, [if I have 10 pledges by the end of the weekend][pledges], I will launch version 1.9 with some awesome new features by the end of next week...otherwise I will hold it hostage till next year! 

Nah just kidding, I will launch it by then anyway. 

# What's planned for version 1.9

While I'm working on version 2.0 ([which is a major refactor of Showdown][1]), I though it would be nice to publish a new minor version of showdown, with some of the features (as experimental features) already developed for version 2.0. This way you can start experimenting with it and tell me what you think.

The most exciting (and requested) new feature, IMHO, is the **"HTML to Markdown Converter"**. This neat feature will enable you to parse and convert an HTML document into markdown.

I will also backport some pending bugfixes too.

So, stay tunned and... don't forget to donate! :grin:




[patreon]: https://www.patreon.com/showdownjs
[pledges]: https://www.patreon.com/bePatron?u=11141581
[1]: http://showdownjs.com/#!/blog/rewriting-the-parser-challenges-and-opportunities

---

## File: blog/posts.json

[
  {
    "id": 1,
    "canonical": "annoucement-showdown-2.0",
    "url": "blog/annoucement-showdown-2.0.md",
    "metadata": {
      "title": "Annoucement: Showdown 2.0",
      "author": "Estevão Soares dos Santos",
      "author_avatar": "img/avatars/tivie.jpg",
      "date": "2017-12-12",
      "language": "en",
      "image": "blog/img/2017.12.12.jpg",
      "summary": "Showdown version 1.0.0 was released almost 3 years ago, back in May 2015. Since then, it has seen a lot of improvements, with a boost to performance and a significant number of features now included in the core of the library. However, do to backwards compatibility constrains, we are still supporting a lot of legacy features, that prevent us from moving the software forward.\n\nWith that in mind, **it is time to start thinking about Showdown version 2.0.** For the next major release of Showdown we have planned a range of **significant changes and additions**."
    }
  },
  {
    "id": 2,
    "canonical": "rewriting-the-parser-challenges-and-opportunities",
    "url": "blog/rewriting-the-parser-challenges-and-opportunities.md",
    "metadata": {
      "title": "Rewriting the parser: Challenges and opportunities",
      "author": "Estevão Soares dos Santos",
      "author_avatar": "img/avatars/tivie.jpg",
      "date": "2018-09-25",
      "language": "en",
      "image": "blog/img/2018.09.25.jpg",
      "summary": "There comes a time when tough (and exciting) choices need to be made. With a version 2.0 in the oven (and the exciting reverse parser already completed), it seemed an excellent opportunity for doing something that I wished for a long time: rewriting showdown's parser from scratch. But maybe that challenge was a lot more tough than I first anticipated!"
    }
  },
  {
    "id": 3,
    "canonical": "showdown-1.8.7-released",
    "url": "blog/showdown-1.8.7-released.md",
    "metadata": {
      "title": "Showdown 1.8.7 released",
      "author": "Estevão Soares dos Santos",
      "author_avatar": "img/avatars/tivie.jpg",
      "date": "2018-10-16",
      "language": "en",
      "image": "blog/img/2018.10.16.jpg",
      "summary": "While everyone's waiting for the new Showdown 2.0, we released version 1.8.7 with some improvements and several bugfixes"
    }
  },
  {
    "id": 4,
    "canonical": "patreon-launch",
    "url": "blog/patreon-launch.md",
    "metadata": {
      "title": "We Just Launched Patreon!",
      "author": "Estevão Soares dos Santos",
      "author_avatar": "img/avatars/tivie.jpg",
      "date": "2018-11-03",
      "language": "en",
      "image": "blog/img/2018.11.03.jpg",
      "summary": "I'm very happy to say that Patreon is Up! Check out the cool rewards I have planned for you. And there is also a surprise announcement regarding a new release..."
    }
  },
  {
    "id": 5,
    "canonical": "showdown-1.9.0-released",
    "url": "blog/showdown-1.9.0-released.md",
    "metadata": {
      "title": "Showdown 1.9.0 Released",
      "author": "Estevão Soares dos Santos",
      "author_avatar": "img/avatars/tivie.jpg",
      "date": "2018-11-10",
      "language": "en",
      "image": "blog/img/2018.10.16.jpg",
      "summary": "We are very happy to announce the release of version 1.9.0, with a new and exciting feature: the HTML to Markdown converter!"
    }
  },
  {
    "id": 5,
    "canonical": "showdown-2.1.0-released",
    "url": "blog/showdown-2.1.0-released.md",
    "metadata": {
      "title": "Showdown 2.1.0 Released",
      "author": "Estevão Soares dos Santos",
      "author_avatar": "img/avatars/tivie.jpg",
      "date": "2022-04-21",
      "language": "en",
      "image": "blog/img/2018.10.16.jpg",
      "summary": "We are very happy to announce the release of version 2.1.0 which fixes some bugs and security issues!"
    }
  }
]

---

## File: blog/rewriting-the-parser-challenges-and-opportunities.md

«««
title: Rewriting the parser: Challenges and opportunities,
author: Estevão Soares dos Santos,
author_avatar: img/avatars/tivie.jpg,
date: 2018-09-25,
language: en,
image: img/blog/2018.09.25.jpg,
summary: There comes a time when tough (and exciting) choices need to be made. With a version 2.0 in the oven 
    (and the exciting reverse parser already completed), it seemed an excellent opportunity for doing something 
    that I wished for a long time: rewriting showdown's parser from scratch. But maybe that challenge was a lot 
    more tough than I first anticipated!
»»»

***There comes a time when tough (and exciting) choices need to be made. With a version 2.0 in the oven 
(and the exciting reverse parser already completed), it seemed an excellent opportunity for doing something that 
I wished for a long time: rewriting showdown's parser from scratch.***

But maybe that challenge was a lot more tough than I first anticipated!

## The old parser

The old parser was based on replacing markdown text *in loco* and in the original string with HTML, through a series of 
Regular Expression.
While this was true to showdown's origins in John Gruber's Markdown.pl, during the last 3 years it became clear that
Regex, at least by itself, was not suitable for the parsing job.

Don't get me wrong, Regex is a great tool: *not only does it works for 99% of use cases*, it also makes it extremely easy
to develop extensions that complement showdown's features, even for beginner programmers.

The problem, however, are those pesky edge cases... that 1% of weird scenarios that ended up making showdown's Regular Expressions
increasingly complex over time

In fact, when you compare v 1.0 to v. 1.8.6, it's plain to see that almost all bug fixes (with notable exceptions)
were, in fact, edge case fixes.

## Regex Madness

Some regexes grew so weirdly that I ended up needing to split them in chunks and do some convoluted stuff to keep them minimally sane.
For instance, it takes 6 RegExps just to parse `__foo__bar__baz__`.
```javascript
  if (options.literalMidWordUnderscores) {
    text = text.replace(/\b___(\S[\s\S]*)___\b/g, function (wm, txt) {
      return parseInside (txt, '<strong><em>', '</em></strong>');
    });
    text = text.replace(/\b__(\S[\s\S]*)__\b/g, function (wm, txt) {
      return parseInside (txt, '<strong>', '</strong>');
    });
    text = text.replace(/\b_(\S[\s\S]*?)_\b/g, function (wm, txt) {
      return parseInside (txt, '<em>', '</em>');
    });
  } else {
    text = text.replace(/___(\S[\s\S]*?)___/g, function (wm, m) {
      return (/\S$/.test(m)) ? parseInside (m, '<strong><em>', '</em></strong>') : wm;
    });
    text = text.replace(/__(\S[\s\S]*?)__/g, function (wm, m) {
      return (/\S$/.test(m)) ? parseInside (m, '<strong>', '</strong>') : wm;
    });
    text = text.replace(/_([^\s_][\s\S]*?)_/g, function (wm, m) {
      // !/^_[^_]/.test(m) - test if it doesn't start with __ (since it seems redundant, we removed it)
      return (/\S$/.test(m)) ? parseInside (m, '<em>', '</em>') : wm;
    });
  }
```

Others, which were inherited from when I took over the project, were just plainly poorly coded and 
[hid some nasty bugs within](https://codereview.stackexchange.com/questions/150277/regex-to-parse-horizontal-rules-in-markdown).

Javascript's regex limitations (such as no support for Lookbehind or atomic and possessive grouping) meant that I needed to rely
on the language's quirks and look for hacks to overcome those limitations.
At some point I even had to adapt a [recursive RegExp extension](https://github.com/showdownjs/showdown/blob/version_1.x/src/helpers.js#L210)
which seems an overkill for a syntax that doesn't really care about balanced stuff.

And some stuff was just []impossible to fix](https://github.com/showdownjs/showdown/issues/549) without making the parser
very VERY slow for everyone. 


## Enter the new parser

For all those reasons, and some more, I felt that version 2.0 should have a shinny and **proper new parser** that read
the code sequentially and was aware of context (use more code logic and less RexExp wizardry :tada:). The new parser is, 
in fact, a lot more similar to a PEG parser than a RegExp converter with in place substitutions.

Some key features include:

  - **Sequential**
  
    The new parser reads the input sequentially. When a syntax element match is found, it "stores" the element without
    changing the original string. This means that Showdown no longer relies on (nor needs) a specific order in which 
    sub parsers are invoked.

  - **Full separation of the *parsing* and *conversion* steps**
    
    Instead of making in place substitutions of the original input, the new parser creates an intermediary abstract layer,
    an object that is a *node tree* of elements, similar to the DOM Tree in the browser, which makes it easy to manipulate
    each node before outputting it as a string again, in other format.
    
    
  - **Output manipulation is extremely easy and customizable through templates**
  
    The node tree (and each individual node) can be manipulated as you see fit since it's, in practice, an agnostic 
    representation of an element. Each node has a template for each supported format: HTML and Markdown. But you can 
    even add more formats if you wish. 
    
    What is cool is that, **not only can you can manipulate the tree (add, delete or swap nodes)**, you can also **tweak 
    or completely change the output of all nodes of a type or even a specific, individual node**.
    
  - **Extensions are a lot more powerful now**
  
    The extension system is being completely redone and will tie in really really well with the new parser and 
    **Reverse Converter**.
    
  - **Faster (it seems)**
    
    RegExps, specially the complex ones, are slow. So, moving away from them, and only using RegExp for quick checks,
    should speed up the parser a lot. Well, at least in theory.
    

## Not everything are roses though

Unfortunately, to accomplish this and successfully move away from RexExp, 3 things were needed:

1. Keep the extension logic simple (while making it more powerful)
2. Time
3. Accurately estimate number 2 (time needed vs free time)


While I feel that the first one is being accomplished quite nicely (if I may say so myself), **I might have over estimated
my free time** and I definitely failed at number 3. Which meant I had to keep delaying the alpha release for v2.0, which
I intended to release in mid 2018.

Between work and family, the little free time I get, I dedicate it to this library. I do feel that things 
are still going on the right track, albeit a lot more slowly than expected (and than I wished for).

Regardless, **I'm really excited about the new features for version 2.0, specially the reverse converter and how it will tie in 
toegether with the new parser and event system**


## I would really, really, really appreciate if you could donate, you know?

For all those reasons, working on the 2.0 version consumes a lot of my free time which, unfortunately, I don't have that much lately.

I would really, REALLY appreciate if you could donate. Your contribution will mean a lot to me and really help me 
dedicate less time to my dayjob (and those annoying extra hours) and more time developing this (awesome) library.

So... if you like my work and find our library useful, 
please donate ~~[through Patreon (coming soon)](https://www.patreon.com/showdownjs) or~~ 
directly [through paypal](https://www.paypal.me/tiviesantos)!! 

Thank you!!

---

## File: blog/showdown-1.8.7-released.md

«««
title: Showdown 1.8.7 released,
author: Estevão Soares dos Santos,
author_avatar: img/avatars/tivie.jpg,
date: 2018-10-16,
language: en,
image: img/blog/2018.10.16.jpg,
summary: While everyone's waiting for the new Showdown 2.0, I released version 1.8.7 with some improvements and several bugfixes.
»»»

Showdown's version 2.0 is coming together although not as fast as I wanted, maybe 
[due to the extensive refactor done to the parser][rewriting-the-parser]. But while the community is patiently  waiting, 
I felt that some important bugfixes could (and should) be backported to v 1.x.


## What's new in 1.8.7?

Some long awaited bugfixes were backported, namely:


* **emojis:** fix emoji excessive size

* **gfm-codeblocks:**

    * add support for spaces before language declaration
    
    * leading space no longer breaks gfm codeblocks
    
* **images:** fix js error when using image references

* **literalMidWordAsterisks:** now parses single characters enclosed by * correctly

* **mentions:** allow for usernames with dot, underscore and dash

* **nbsp:** fix replacing of nbsp with regular spaces



You can download/use the new version from [github], [npm] and [CDNJS].


[rewriting-the-parser]: http://shwodownjs.com/#!/blog/rewriting-the-parser-challenge-or-opportunity
[npm]: https://www.npmjs.com/package/showdown
[github]: https://github.com/showdownjs/showdown
[CDNJS]: https://cdnjs.com/libraries/showdown

---

## File: blog/showdown-1.9.0-released.md

«««
title: Annoucement: Showdown 1.9.0 released,
author: Estevão Soares dos Santos,
author_avatar: img/avatars/tivie.jpg,
date: 2018-11-10,
language: en,
image: img/blog/2018.10.16.jpg,
summary: We are very happy to announce the release of version 1.9.0, with a new and exciting feature: the HTML to Markdown converter!
»»»

The final minor version of Showdown is now up! Enjoy it while I continue to work on version 2.0.

Version 1.9.0 introduces a new feature, the HTML to Markdown converter. 
This feature is still experimental and is a partial backport of the new Reverse Converter planned for version 2.0.

# Bug Fixes
italicsAndBold: fix issue with consecutive spans (#608) (5c0d67e), closes #544
underline: fix issue with consecutive spans (81edc70)

# Features
converter.makeMarkdown: [EXPERIMENTAL] add an HTML to Markdown converter (e4b0e69), closes #388 #233


You can download/use the [new version here.](https://github.com/showdownjs/showdown/releases)

---

## File: blog/showdown-2.1.0-released.md

«««
title: Annoucement: Showdown 2.1.0 released,
author: Estevão Soares dos Santos,
author_avatar: img/avatars/tivie.jpg,
date: 2022-04-21,
language: en,
image: img/blog/2018.10.16.jpg,
summary: We are very happy to announce the release of version 2.1.0 which fixes some bugs and security issues
»»»

Release 2.1.0 comprises a complete refactor of the CLI tool. There are only a few changes beyond 1.9.1 as noted below. 
The major driver of this update is to remove the yargs dependency, switching to commander, a more lightweight (and no-dependecies)
library.

Also, the license changed from BSD-3-Clause to MIT

The changes relative to version 1.9.x are as follow:

### Breaking Changes
* Supported Node Versions were set to match the [node release schedule](https://nodejs.org/en/about/releases/) which at
  the time of writing includes Node 12.x, 14.x, 16.x and 17.x
* The `yargs` dependency was removed.
* The Showdown license has been changed from BSD-3-Clause to MIT
* The CLI no longer accepts "extra options". Instead you should pass the `-c` flag. To update:

    before:
    ```
    showdown makehtml -i foo.md -o bar.html --strikethrough --emoji
    ```

    after:
    ```
    showdown makehtml -i foo.md -o bar.html -c strikethrough -c emoji
    ```

### Bug Fixes

* allow escaping of colons ([25c4420](https://github.com/showdownjs/showdown/commit/25c4420))
* reduce npm package size  ([35730b7](https://github.com/showdownjs/showdown/commit/35730b7)), closes [#619](https://github.com/showdownjs/showdown/issues/619)

### Features

* Added `ellipsis` option to configure if the ellipsis unicode character is used or not. ( Thanks @VladimirV99 )
* Added a default security policy. Please report security issues to the issues tab on GitHub.


You can download/use the [new version here.](https://github.com/showdownjs/showdown/releases)

---

## File: .github/workflows/docs.yml

name: documentation

on:
  push:
    branches:    
      - 'main'
  repository_dispatch:

jobs:
  build_docs:
    name: 📚 Build documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Checkout showdown repo
        uses: actions/checkout@v3
        with:
          path: repo
      
      - name: ➕ Copy website artifacts
        id: website
        run: |
          rsync -acvh ./ ./public --exclude README.md --exclude repo --delete
      
      - name: 👷 📚 Build documentation
        id: build_docs
        working-directory: ./repo
        run: |
          docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build
          rsync -acvh ./public/ ../public/docs

      - name: 🚀 Deploy to GitHub Pages 
        if: steps.build_docs.outcome == 'success'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}