ShowdownJS: A Powerful Markdown to HTML Converter for GitHub, Node.js, and the Browser

ShowdownJS is a versatile JavaScript library that converts Markdown text into HTML. It's designed to be used both client-side (in web browsers) and server-side (with Node.js). ShowdownJS is particularly well-suited for projects that need to work with GitHub Flavored Markdown (GFM), but it also supports other flavors.

GitHub Flavored Markdown (GFM) Support

ShowdownJS offers comprehensive support for GFM, which is widely adopted on platforms like GitHub. This ensures compatibility with the syntax and features commonly used in GitHub repositories and documentation.

• Code Blocks: Easily create code blocks with syntax highlighting.
• Task Lists: Use GFM task lists to create to-do lists with checkboxes.
• GitHub Mentions: Link @mentions to corresponding user profiles.

Installation and Usage

Installing and using ShowdownJS is straightforward:

Bower (Client-Side)

bower install showdown

npm (Server-Side)

npm install showdown

NuGet Package (Server-Side)

PM> Install-Package showdownjs

CDN

ShowdownJS can also be easily included in your project using a CDN like jsDelivr, cdnjs, or unpkg.

https://cdn.jsdelivr.net/npm/showdown@<version tag>/dist/showdown.min.js

Customization and Options

ShowdownJS provides a range of options that allow you to customize its behavior. This includes:

Valid Options

• omitExtraWLInCodeBlocks: Omit trailing newline in code blocks.
• noHeaderId: Disable automatic generation of header IDs.
• customizedHeaderId: Use text in curly braces as header IDs.
• ghCompatibleHeaderId: Generate GitHub-compatible header IDs.
• prefixHeaderId: Add a prefix to header IDs.
• rawPrefixHeaderId: Prevent Showdown from modifying the prefix.
• rawHeaderId: Remove only spaces and quotes from header IDs.
• headerLevelStart: Set the starting header level.
• parseImgDimensions: Enable image dimension support within Markdown syntax.
• simplifiedAutoLink: Enable automatic linking to URLs.
• literalMidWordUnderscores: Treat underscores in the middle of words literally.
• strikethrough: Enable strikethrough syntax.
• tables: Enable support for tables.
• tablesHeaderId: Add IDs to table header tags.
• ghCodeBlocks: Enable GFM code block style.
• tasklists: Enable GFM task lists.
• smoothLivePreview: Improve live preview experience.
• smartIndentationFix: Fix indentation issues related to ES6 template strings.
• disableForced4SpacesIndentedSublists: Allows sublists to be nested with 2 or 3 spaces.
• simpleLineBreaks: Parse line breaks as <br> without needing extra spaces.
• requireSpaceBeforeHeadingText: Requires a space between '#' and header text.
• ghMentions: Enable GitHub @mentions.
• ghMentionsLink: Customize the link generated by @mentions.
• encodeEmails: Encode email addresses using character entities.
• openLinksInNewWindow: Open all links in new windows.
• backslashEscapesHTMLTags: Support for HTML tag escaping.
• emoji: Enable emoji support.
• underline: Enable support for underline syntax.
• ellipsis: Replace three dots with the ellipsis unicode character.
• completeHTMLDocument: Output a complete HTML document.
• metadata: Enable support for document metadata.
• splitAdjacentBlockquotes: Split adjacent blockquote blocks.
• moreStyling: Adds useful classes for CSS styling.

Flavors and Presets

ShowdownJS offers presets, called flavors, to automatically configure the converter for popular Markdown flavors. These flavors provide pre-defined option sets that match the expected behavior of different Markdown implementations.

• original: Original Markdown flavor as defined by John Gruber's spec.
• vanilla: ShowdownJS's base flavor.
• github: GFM (GitHub Flavored Markdown).

Extending ShowdownJS

ShowdownJS supports extensions, which allow you to add custom functionality and features to the converter. You can find a list of existing extensions on the ShowdownJS wiki.

Browser Compatibility

ShowdownJS has been tested and is compatible with a wide range of modern browsers, including:

• Firefox 1.5 and 2.0
• Chrome 12.0
• Internet Explorer 6 and 7
• Safari 2.0.4
• Opera 8.54 and 9.10
• Netscape 8.1.2
• Konqueror 3.5.4

In general, it will work in any browser that supports JavaScript 1.5.

Security Considerations

ShowdownJS does not sanitize the input by default. This means that it is possible for malicious content to be injected and executed, potentially leading to XSS vulnerabilities. It is essential to implement appropriate security measures, such as input validation and output encoding, to mitigate these risks.

For more information about XSS vulnerabilities and mitigation strategies, refer to the ShowdownJS wiki article on Markdown's XSS Vulnerability.

Contributing to ShowdownJS

Contributions to ShowdownJS are highly appreciated! If you want to submit a feature request or fix an issue, follow these steps:

• Search GitHub for existing issues or pull requests related to your submission. Avoid duplicating effort.
• Create a new branch based on the develop branch for your changes: git checkout -b my-fix-branch develop
• Run the test suite before submitting your pull request to ensure all tests pass.
• Follow the coding style guidelines provided in the ShowdownJS code style guide.
• Submit separate pull requests for distinct issues or features. Large pull requests are harder to review.
• Include test cases for any new features or fixes.
• Use conventional commit messages to generate a clear changelog.
• Add your name to the CREDITS.md file.
• Rebase and force push your branch after requested changes: git rebase develop -i and git push origin my-fix-branch -f

Joining the ShowdownJS Team

ShowdownJS welcomes new team members to help with maintenance and development. If you're interested in contributing, express your interest in the relevant GitHub issue.

ShowdownJS is powered by JetBrains WebStorm.