A fork of dart-markdown for easy customization of Markdown syntaxes.
Differences
- Support Github task lists, aka, check lists.
- Table enhancements:
- Allow the table syntax to be not balanced, e.g., the mismatch of number of headers and number of column in content (#13).
- Generates
<td></td>
instead of<td />
for empty cells or unbalanced content (#14). TableSyntax.escapeFoward
introduced for skiping pipe characters (|
) that shall not be considered as a column separator.TableSyntax.processCellContent
introduced for pre-processing cell's content
- Link enhancements:
LinkMapper
introduced for mapping a application-specific link to a real one, e.g.,#abc
mapped tohttps://foo/abc
.parseInlineLink
introduced for parsing URL in inline link.
- Easy to customize:
InlineParser.be
andBlockParser.be
introduced for easy customization. They are used in pair if all parsing shares the same set of syntaxes.Document
's constructor introduced additional arguments,options
,blockParserBuilder
andinlineParserBuilder
for easy customization.InlineSyntax.matches
introduced for easy overriding.InlineSyntax
's constructor introduces the caseSensitive argumentFencedCodeBlockSyntax.getLanguageClass
introduced for generating custom CSS classCondensedHtmlRenderer
andTextRenderer
introduced for customizing CSS easier.DelimiterRun.tryParse
depends onSimpleParser
, notInlineParser
.
Resources
Customizations
Who Uses
- Quire - a simple, collaborative, multi-level task management tool.
- Keikai - a sophisticated spreadsheet for big data
Introduction
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:markd/markdown.dart';
void main() {
print(markdownToHtml('Hello *Markdown*'));
//=> <p>Hello <em>Markdown</em></p>
}
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'sauto_identifiers
).const SetextHeaderWithIdSyntax()
- Setext-style headers have generated IDs for link anchors (akin to Pandoc'sauto_identifiers
).const TableSyntax()
- Table syntax familiar to GitHub, PHP Markdown Extra, and Pandoc users.
For example:
import 'package:markd/markdown.dart';
void main() {
print(markdownToHtml('Hello <span class="green">Markdown</span>',
inlineSyntaxes: [InlineHtmlSyntax()]));
//=> <p>Hello <span class="green">Markdown</span></p>
}
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 thegitHubFlavored
extension set with the addition of the block syntax parsers, HeaderWithIdSyntax and SetextHeaderWithIdSyntax, which addid
attributes to headers and inline syntax parser, EmojiSyntax, for parsing GitHub style emoji characters:-
Block Syntax Parser
const FencedCodeBlockSyntax()
const HeaderWithIdSyntax()
, which addsid
attributes to ATX-style headers, for easy intra-document linking.const SetextHeaderWithIdSyntax()
, which addsid
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:markd/markdown.dart';
void main() {
var syntaxes = [TextSyntax('nyan', sub: '~=[,,_,,]:3')];
print(markdownToHtml('nyan', inlineSyntaxes: syntaxes));
//=> <p>~=[,,_,,]:3</p>
}
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 resultstool/common_mark_stats.json
and the test summarytool/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
-
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.28
in the repository. (Including this one.) Verify the updated links are still valid. -
Commit changes, including a corresponding note in
CHANGELOG.md
.
Libraries
- markdown
- Parses text in a Markdown-like format and renders to HTML.