markdown

Description:

markdown

A portable Markdown library written in Dart. It can parse Markdown into
HTML on both the client and server.
Play with it at
dart-lang.github.io/markdown.
Usage #
import 'package:markdown/markdown.dart';

void main() {
print(markdownToHtml('Hello *Markdown*'));
//=> <p>Hello <em>Markdown</em></p>
}
copied to clipboard
Syntax extensions #
A few Markdown extensions, beyond what was specified in the original
Perl Markdown implementation, are supported. By default, the ones supported
in CommonMark are enabled. Any individual extension can be enabled by
specifying an Array of extension syntaxes in the blockSyntaxes or
inlineSyntaxes argument of markdownToHtml.
The currently supported inline extension syntaxes are:

InlineHtmlSyntax() - approximately CommonMark's
definition of "Raw HTML".

The currently supported block extension syntaxes are:

const FencedCodeBlockSyntax() - Code blocks familiar to Pandoc and PHP
Markdown Extra users.
const HeaderWithIdSyntax() - ATX-style headers have generated IDs, for link
anchors (akin to Pandoc's auto_identifiers).
const SetextHeaderWithIdSyntax() - Setext-style headers have generated IDs
for link anchors (akin to Pandoc's
auto_identifiers).
const TableSyntax() - Table syntax familiar to GitHub, PHP Markdown Extra,
and Pandoc users.

For example:
import 'package:markdown/markdown.dart';

void main() {
print(markdownToHtml('Hello <span class="green">Markdown</span>',
inlineSyntaxes: [InlineHtmlSyntax()]));
//=> <p>Hello <span class="green">Markdown</span></p>
}
copied to clipboard
Extension sets #
To make extension management easy, you can also just specify an extension set.
Both markdownToHtml() and Document() accept an extensionSet named
parameter. Currently, there are four pre-defined extension sets:


ExtensionSet.none includes no extensions. With no extensions, Markdown
documents will be parsed with a default set of block and inline syntax
parsers that closely match how the document might be parsed by the original
Perl Markdown implementation.


ExtensionSet.commonMark includes two extensions in addition to the default
parsers to bring the parsed output closer to the CommonMark specification:


Block Syntax Parser

const FencedCodeBlockSyntax()



Inline Syntax Parser

InlineHtmlSyntax()





ExtensionSet.gitHubFlavored includes five extensions in addition to the default
parsers to bring the parsed output close to the GitHub Flavored Markdown
specification:


Block Syntax Parser

const FencedCodeBlockSyntax()
const TableSyntax()



Inline Syntax Parser

InlineHtmlSyntax()
StrikethroughSyntax()
AutolinkExtensionSyntax()





ExtensionSet.gitHubWeb includes eight extensions. The same set of parsers use
in the gitHubFlavored extension set with the addition of the block syntax parsers,
HeaderWithIdSyntax and SetextHeaderWithIdSyntax, which add id attributes to
headers and inline syntax parser, EmojiSyntax, for parsing GitHub style emoji
characters:


Block Syntax Parser

const FencedCodeBlockSyntax()
const HeaderWithIdSyntax(), which adds id attributes to ATX-style
headers, for easy intra-document linking.
const SetextHeaderWithIdSyntax(), which adds id attributes to
Setext-style headers, for easy intra-document linking.
const TableSyntax()



Inline Syntax Parser

InlineHtmlSyntax()
StrikethroughSyntax()
EmojiSyntax()
AutolinkExtensionSyntax()





Custom syntax extensions #
You can create and use your own syntaxes.
import 'package:markdown/markdown.dart';

void main() {
var syntaxes = [TextSyntax('nyan', sub: '~=[,,_,,]:3')];
print(markdownToHtml('nyan', inlineSyntaxes: syntaxes));
//=> <p>~=[,,_,,]:3</p>
}
copied to clipboard
HTML sanitization #
This package offers no features in the way of HTML sanitization. Read Estevão
Soares dos Santos's great article, "Markdown's XSS Vulnerability (and how to
mitigate it)", to learn more.
The authors recommend that you perform any necessary sanitization on the
resulting HTML, for example via dart:html's NodeValidator.
CommonMark compliance #
This package contains a number of files in the tool directory for tracking
compliance with CommonMark.
Updating CommonMark stats when changing the implementation

Update the library and test code, making sure that tests still pass.
Run dart run tool/stats.dart --update-files to update the
per-test results tool/common_mark_stats.json and the test summary
tool/common_mark_stats.txt.
Verify that more tests now pass – or at least, no more tests fail.
Make sure you include the updated stats files in your commit.

Updating the CommonMark test file for a spec update


Check out the CommonMark source. Make sure you checkout a major release.


Dump the test output overwriting the existing tests file.
> cd /path/to/common_mark_dir
> python3 test/spec_tests.py --dump-tests > \
/path/to/markdown.dart/tool/common_mark_tests.json
copied to clipboard


Update the stats files as described above. Note any changes in the results.


Update any references to the existing spec by search for
https://spec.commonmark.org/0.30/ in the repository. (Including this one.)
Verify the updated links are still valid.


Commit changes, including a corresponding note in CHANGELOG.md.