html

Showdown Markdown: A GitHub Flavored Markdown Guide

This article is a comprehensive guide to Showdown's Markdown syntax, a JavaScript implementation of GitHub Flavored Markdown (GFM), designed to help you create web content compatible with github. Showdown aims to follow the original Markdown spec while supporting additional features found in GFM.

Showdown provides a powerful tool for converting Markdown to HTML, making it easy to create clean, readable content for your web projects.

Heading Styles for Clarity

Headings are an essential part of organizing your content. Showdown supports two popular heading styles: Atx Style and Setext Style.

• Atx Style: You use # symbols to indicate heading levels, with the number of # symbols corresponding to the heading size (h1, h2, etc.)
• Setext Style: This style uses equals signs (===) for h1 headings and hyphens (---) for h2 headings.

Code Blocks: Presenting Code Effectively

Showdown offers several ways to format code blocks, ensuring that your code snippets are displayed correctly and legibly.

• Indented Code: Indent code lines by four spaces to create a code block. This method allows for quick and simple code formatting.
• Fenced Code Blocks: Use triple backticks () to create a fenced code block, making it easy to highlight and specify the language of the code. This is a very common approach in github.

Lists: Structured Organization for Your Content

Showdown supports both unordered (bulleted) and ordered (numbered) lists, making it easy to create structured content.

• Unordered Lists: Start each list item with a *, -, or + symbol, followed by one or more spaces or a tab.
• Ordered Lists: Begin each list item with a number followed by a period (.) and one or more spaces or a tab. The numbers you use don't affect the output, making ordered lists very flexible.
• Nested Lists: Create nested lists by indenting the list items by four spaces or a tab. This helps visually represent the hierarchy of your information.

Links: Connecting Your Content to the Web

Showdown provides multiple ways to create links within your Markdown text, allowing you to seamlessly link your content to other websites or resources.

• Autolinking: Showdown automatically transforms valid URLs and email addresses into clickable links when the simplifiedAutoLink option is enabled. This simplifies the process of creating links.
• Inline Link Syntax: Wrap the link text in brackets ([ ]) and the URL in parentheses (( )). This is the most common way to create links in github.
• Reference Style: Use a reference link definition to create links, providing a way to manage multiple links with a single definition.

Images: Adding Visuals to Your Content

Showdown supports inline and reference styles for embedding images into your markdown. This allows you to create visually appealing content by incorporating images seamlessly.

• Inline Images: Use an exclamation mark (!), followed by square brackets containing alt text and parentheses containing the image URL and optional title text.
• Reference Images: Use an exclamation mark (!), followed by square brackets containing alt text, and another set of square brackets with the image reference ID. Define the reference ID with the image URL and optional title text.

Tables: Structuring Data and Information

While tables are not part of the core Markdown spec, they are widely supported in GFM, and Showdown includes them when the tables option is enabled.

Tables can be used to create visually appealing presentations of data, enhancing the organization and readability of your markdown content.

• Column Alignment: Use colons (:) within the table header row to specify column alignment, like left-align, center-align, or right-align.

Handling HTML in Markdown

Showdown generally leaves HTML tags untouched in the output, allowing you to embed custom HTML elements for advanced styling or functionality. However, tags like <code> and <pre><code> are always escaped to ensure proper code formatting.

For situations where you want to enable Markdown parsing within specific HTML tags, you can use the markdown attribute or data-markdown attribute on the HTML tag. This allows you to combine Markdown syntax and HTML for more complex content.

Showdown and GitHub Mentions

Showdown provides the ability to turn github mentions into clickable links to users' profiles on github. This feature can be enabled using the ghMentions option.

This feature is useful for creating dynamic content where you want to link to specific github users within your Markdown text.

You can even customize the generated link using the ghMentionsLink option. This allows you to control how mentions are linked based on your specific project requirements.

Escaping Entities: Ensuring Correct Interpretation

Showdown allows you to use backslashes (\) to escape characters that have special meaning in Markdown syntax. This ensures that these characters are displayed literally rather than being interpreted by the Markdown parser.

This feature is essential for maintaining control over how certain characters are rendered in your Markdown content, especially when you need to display characters that might otherwise be treated as Markdown elements.

Known Differences

Showdown generally aims to be consistent with the original Markdown spec, but there are a few known differences. It's helpful to be aware of these differences to avoid any potential unexpected results.

• Markdown Attribute: In older versions of Showdown, the markdown="1" attribute was ignored. This means that Markdown within a <div> tag with the markdown attribute would not be parsed.
• Nested Square Brackets: Nested square brackets in link titles are only supported up to two levels deep. If you need deeper nesting, you can use backslashes to escape the square brackets.
• List Paragraphing: Showdown handles list paragraphing differently from other implementations. A list is considered a single paragraph if only a single line break separates items. But if any item is separated by two line breaks, the entire list becomes multi-paragraph.