markd 2.0.2+8

  • Readme
  • Changelog
  • Installing
  • 72

Build Status

A fork of dart-markdown for easy customization of Markdown syntaxes.


  • Github-like task lists supported.
  • LinkMapper introduced for mapping a logic link to a real one, e.g., #abc mapped to https://foo/abc.
  • parseInlineLink introduced for parsing URL in inline link.
  • and 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 and inlineParserBuilder for easy customization.
  • InlineSyntax.match introduced for easy overriding.
  • InlineSyntax's constructor introduces the caseSensitive argument
  • FencedCodeBlockSyntax.getLanguageClass introduced for generating custom CSS class
  • TableSyntax.processCellContent introduced for pre-processing cell's content



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

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:

  • new 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:markd/markdown.dart';

void main() {
  print(markdownToHtml('Hello <span class="green">Markdown</span>',
      inlineSyntaxes: [new 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 new Document() accept an extensionSet named parameter. Right now there are two extension sets:

  • ExtensionSet.none includes no extensions. With no extensions, Markdown documents will be parsed closely to how they might be parsed by the original Perl Markdown implementation.

  • ExtensionSet.commonMark includes two extensions so far, which bring this package's Markdown parsing closer to what is found in the CommonMark spec:

    • new InlineHtmlSyntax()
    • const FencedCodeBlockSyntax()
  • ExtensionSet.gitHubWeb includes seven extensions:

    • new EmojiSyntax()
    • new InlineHtmlSyntax()
    • 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 FencedCodeBlockSyntax()
    • new StrikethroughSyntax()
    • const TableSyntax()

Custom syntax extensions #

You can create and use your own syntaxes.

import 'package:markd/markdown.dart';

void main() {
  var syntaxes = [new 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 #

  1. Update the library and test code, making sure that tests still pass.
  2. Run dart 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.
  3. Verify that more tests now pass – or at least, no more tests fail.
  4. Make sure you include the updated stats files in your commit.

Updating the CommonMark test file for a spec update #

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

  2. Dump the test output overwriting the existing tests file.

    > cd /path/to/common_mark_dir
    > python3 test/ --dump-tests \
  3. Update the stats files as described above. Note any changes in the results.

  4. Update any references to the existing spec by search for in the repository. (Including this one.) Verify the updated links are still valid.

  5. Commit changes, including a corresponding note in

2.0.2+8 #

  • Bug fixed: #9, #10

2.0.2+5 #

  • Github-like task lists supported.
    • markdownToHtml() supports the readOnly argument to control whether the checkboxes in task lists are clickable.
  • Remove safeBlockSyntaxes.

2.0.2 #

  • Set max SDK version to <3.0.0, and adjust other dependencies.

2.0.1 #

  • Require Dart 2.0.0-dev.

2.0.0 #

  • Breaking change: The Link class has been renamed LinkReference, and the Document field, refLinks, has been renamed linkReferences.

  • Breaking change: Remove the deprecated ExtensionSet.gitHub field. Use ExtensionSet.gitHubFlavored instead.

  • Breaking change: Make all of the fields on Document read-only.

  • Overhaul support for emphasis (*foo* and _foo_) and strong emphasis (**foo** and __foo__), dramatically improving CommonMark compliance.

  • Overhaul support for links and images, again dramatically improving CommonMark compliance.

  • Improve support for tab characters, and horizontal rules.

  • Add support for GitHub Flavored Markdown's Strikethrough extension. See the GFM spec.

  • The above fixes raise compliance with the CommonMark specs to 93%, and compliance with the GFM specs to 92%.

  • Add an encodeHtml parameter to Document, which defaults to true. When false, HTML entities (such as &copy; and the < character) will not be escaped, useful when rendering Markdown in some output format other than HTML.

  • Allow the binary script to take a --extension-set option.

    A reminder: You can run bin/markdown.dart from anywhere via:

    $ pub global activate markdown
    $ markdown

1.1.1 #

  • Add support for GitHub's colon-based Emoji syntax. 🎉! This is available in the gitHubWeb extension set.

1.1.0 #

  • Make the constructor for ExtensionSet public, for tools like dartdoc.
  • Split the gitHub ExtensionSet into two sets: gitHubFlavored, which represents the GitHub Flavored Markdown spec, and gitHubWeb, which represents what GitHub actually renders Markdown.

1.0.0 #

  • Fix issue where accept could cause an exception.
  • Remove deprecated escapeHtml function.
  • Fix compliance with auto-links, including support for email addresses.
  • Updated ExtensionSet.gitHub to more closely align with GitHub markdown.

0.11.4 #

  • Fix bug with lazy blockquote continuations (#162)
  • Fix bug with list item continuations (#156)

0.11.3 #

  • Deprecate escapeHtml. This code exists in dart:convert.

0.11.2 #

  • Fix reference code links inside blockquotes.
  • Add src/util.dart to exports.

0.11.1 #

  • Add version information:
    • dart bin/markdown.dart --version now shows the package version number.
    • The playground app now shows the version number.
  • Improve autolink parsing.
  • Add new table syntax: TableSyntax.
  • Add new ExtensionSet that includes the table syntax: ExtensionSet.gitHub.
  • For development: added tool/
  • Support multiline Setext headers.
  • Handle loose-vs-strict list items better.
  • Support ordered lists that start with a number other than 1.

0.11.0+1 #

0.11.0 #

  • Parse HTML blocks more accurately, according to CommonMark.
  • Support shortcut reference links.
  • Don't allow an indented code block to interrupt a paragraph.
  • Change definition of "loose" and "strict" lists (items wrapped in paragraph tags vs not) to CommonMark's. The primary difference is that any single list item can trigger the entire list to be marked as "loose", rather than defining "looseness" on each specific item.
  • Fix paragraph continuations in blockquotes and list items.
  • Fix silly typing bug with tool/common_mark_stats.dart, which resulted in a dramatic overestimate of our CommonMark compliance.
  • There are now 427/613 (69%) passing CommonMark v0.25 specs.

0.10.1 #

  • Parse hard line breaks properly (#86). Thanks @mehaase!
  • Fix processing of [ ... ] syntax when no resolver is specified (#92).
  • There are now 401/613 (65%) passing CommonMark v0.24 specs. (Actually: after 0f64c8f the actual number of passing tests was 352/613 (57%).)

0.10.0 #

  • BREAKING: Now following the CommonMark spec for fenced code blocks. If a language (info string) is provided, it is added as a class to the code element with a language- prefix.
  • BREAKING: Now following the CommonMark spec for images. Previously, ![text](img.png) would compile too <a href="img.prg"><img src="img.prg" alt="text"></img></a>. That same code will now compile to <img src="img.png" alt="text" />.
  • Fix all strong mode errors.

0.9.0 #

  • BREAKING: The text [foo] (bar) no longer renders as an inline link (#53).
  • BREAKING: Change list parsing to allow lists to begin immediately after a preceding block element, without a blank line in between.
  • Formalize an API for Markdown extensions (#43).
  • Introduce ExtensionSets. FencedCodeBlock is considered an extension, but existing usage of markdownToHtml() and new Document() will use the default extension set, which is ExtensionSet.commonMark, which includes FencedCodeBlock.
  • Inline HTML syntax support; This is also considered an extension (#18).
  • The text [foo]() now renders as an inline link.
  • Whitespace now allowed between a link's destination and title (#65).
  • Header identifier support in the HeaderWithIdSyntax and SetextHeaderWithIdSyntax extensions.
  • Implement backslash-escaping so that Markdown syntax can be escaped, such as [foo]\(bar) ==> <p>[foo](bar)</p>.
  • Support for hard line breaks with either \\\n or \n (#30, #60).
  • New public method for BlockParser: peek(int linesAhead), meant for use in subclasses.
  • New public members for ListSyntax: blocksInList and determineBlockItems(), meant for use in subclasses.
  • Improve public docs (better, and more of them).

0.8.0 #

  • Breaking: Remove (probably unused) fields: LinkSyntax.resolved, InlineParser.currentSource.
  • Switch tests to use test instead of unittest.
  • Fix a few bugs in inline code syntax.
  • Ignore underscores inside words (#41).

0.7.2 #

  • Allow resolving links that contain inline syntax (#42).

0.7.1+3 #

  • Updated homepage.

0.7.1+2 #

  • Formatted code.

  • Updated readme.

Use this package as an executable

1. Install it

You can install the package from the command line:

$ pub global activate markd

2. Use it

The package has the following executables:

$ markdown

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  markd: ^2.0.2+8

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:markd/markdown.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Oct 21, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21


Detected platforms: Flutter, web, other

No platform restriction found in libraries.

Health suggestions

Fix lib/src/inline_parser.dart. (-3.45 points)

Analysis of lib/src/inline_parser.dart reported 7 hints, including:

line 164 col 9: DO use curly braces for all flow control structures.

line 191 col 9: Use isNotEmpty instead of length

line 217 col 51: Use = to separate a named parameter from its default value.

line 557 col 67: Use = to separate a named parameter from its default value.

line 649 col 69: Use = to separate a named parameter from its default value.

Fix lib/src/document.dart. (-2.48 points)

Analysis of lib/src/document.dart reported 5 hints:

line 39 col 45: Use = to separate a named parameter from its default value.

line 40 col 47: Use = to separate a named parameter from its default value.

line 42 col 44: Use = to separate a named parameter from its default value.

line 57 col 37: Use = to separate a named parameter from its default value.

line 57 col 58: Use = to separate a named parameter from its default value.

Fix lib/src/block_parser.dart. (-1.49 points)

Analysis of lib/src/block_parser.dart reported 3 hints:

line 606 col 11: Use isNotEmpty instead of length

line 728 col 11: DO use curly braces for all flow control structures.

line 766 col 7: DO use curly braces for all flow control structures.

Fix additional 3 files with analysis or formatting issues. (-1.99 points)

Additional issues in the following files:

  • lib/src/html_renderer.dart (3 hints)
  • lib/src/ast.dart (1 hint)
  • lib/src/link_parser.dart (Run dartfmt to format lib/src/link_parser.dart.)

Maintenance issues and suggestions

Use constrained dependencies. (-20 points)

The pubspec.yaml contains 1 dependency without version constraints. Specify version ranges for the following dependencies: rikulo_commons.

The package description is too short. (-20 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and markd.dart. Packages with multiple examples should provide example/

For more information see the pub package layout conventions.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
args ^1.0.0 1.5.2
charcode ^1.1.0 1.1.2
rikulo_commons any 3.3.0
Transitive dependencies
logging 0.11.3+2
mime 0.9.6+3
Dev dependencies
build_runner ^0.9.1
build_web_compilers ^0.4.0
collection ^1.2.0
expected_output ^1.2.1
html >=0.12.2 <0.14.0
js ^0.6.1
path ^1.3.1
test ^1.2.0
yaml ^2.1.8