mdown 0.12.0+2

  • README.md
  • Installing
  • Versions
  • 60

mdown

Build Status codecov Pub CommonMark spec

mdown is fast and CommonMark-compliant Markdown parser.

Basic usage:

print(markdownToHtml('# Hello world!'));

Project main goal is create processing library for Markdown.

Performance

As there are not many Markdown parsers written in Dart out there, parsing speed is compared with markdown package. Progit was used as a source of markdown files in different languages. mdown appears to be 3 times faster in VM, 11 times faster in Chrome, 2.2 times faster in Safari and 3.7 times faster in Firefox.

Run benchmarks yourself or see details.

mdown make extensive use of String.codeUnitAt instead of RegExp. So you can see noticeable gain for non-latin languages (up to ×38 in Chrome for Japan language).

Extensions

mdown supports some language extensions. You can specify enabled extensions using options parameter in markdownToHtml.

Options options = const Options(superscript: true);
String res = markdownToHtml('Hello world!\n===', options);

There three predefined sets of options:

  • Options.strict: all extensions are disabled
  • Options.commonmark: only smartPunctuation extension is enabled.
  • Options.defaults: smartPunctuation, strikeout, subscript, superscript, pipeTables, texMathDollars, rawTex are enabled.

To get correspondent parser/writer instance use static getter on class:

String res = markdownToHtml('Hello world!\n===', Options.strict);

If second parameter is not provided, Options.defaults is used.

Smart punctuation (Options.smartPunctuation)

Smart punctuation is automatic replacement of ..., ---, --, " and ' to "…", "—", "–" and curly versions of quote marks accordingly. It's only official extension to date.

NOTE: This extension uses Unicode chars. Make sure that your code supports it.

Extended attributes for fenced code (Options.fencedCodeAttributes)

Allows fenced code block to have arbitrary extended attributes.

``` {#someId .class1 .class2 key=value}
code
```

This will be rendered in HTML as

<pre id="someId" class="class1 class2" key="value"><code>code
</code></pre>

Extended attributes for headings (Options.headingAttributes)

Allows headings to have arbitrary extended attributes.

# Heading 1 {#someId}

Heading 2 {.someClass}
-------------------

This will be rendered in HTML as

<h1 id="someId">Heading 1</h1>
<h2 class="someClass">Heading 2</h2>

Extended attributes for inline code (Options.inlineCodeAttributes)

Adds extended attributes support to inline code.

`code`{#id .class key='value'}

Extended attributes for links and images. Both inline and reference links are supported.

![](image.jpg){width="800" height="600"}

[test][ref]

[ref]: http://test.com/ {#id}

This will be transformed into:

<p><img src="image.jpg" alt="" width="800" height="600" /></p>
<p><a href="http://test.com/" id="id">test</a></p>

Strikeout (Options.strikeout)

Strikeouts text (like this). Just wrap text with double tildes (~~).

Strikeouts text (~~like this~~).

Subscript (Options.subscript)

Support for subscript (H<sub>2</sub>O). Wrap text with tildes (~).

H~2~O

Subscript couldn't contain spaces. If you need to insert space into the subscript, escape space (\).

subscript~with\ spaces~

Superscript (Options.superscript)

Support for superscript (2<sup>2</sup>=4). Wrap text with carets (^).

2^2^=4

Superscript couldn't contain spaces. If you need to insert space into superscript, escape space (\).

superscript^with\ spaces^

Pipe tables (Options.pipeTables)

Allows to parse tables where cells are separated with vertical bars (|). Compatible with GitHub table syntax.

head | cells
-----|------
body | cells
more | cells

Also supports cells alignment.

:----|:-----:|----:
left aligned | center aligned | right aligned

TeX Math between dollars (Options.texMathDollars)

Anything between two $ characters will be treated as inline TeX math. The opening $ must have a non-space character immediately to its right, while the closing $ must have a non-space character immediately to its left, and must not be followed immediately by a digit. Thus, $20,000 and $30,000 won’t parse as math. If for some reason you need to enclose text in literal $ characters, backslash-escape them and they won’t be treated as math delimiters.

Anything between two $$ will be treated as display TeX math.

HTML writer generates markup for MathJax library. I.e. wraps content with \(...\) or \[...\] and additionally wraps it with <span class="math inline"> or <span class="math display">. If you need custom classes for span you can override them with Options.inlineTexMathClasses and Options.displayTexMathClasses.

TeX Math between backslashed () or [] (Options.texMathSingleBackslash)

Causes anything between \( and \) to be interpreted as inline TeX math and anything between \[ and \] to be interpreted as display TeX math.

NOTE 1: This extension breaks escaping of ( and [].

NOTE 2: This extension is disabled by default.

TeX Math between double backslashed () or [] (Options.texMathDoubleBackslash)

Causes anything between \\( and \\) to be interpreted as inline TeX math and anything between \\[ and \\] to be interpreted as display TeX math.

NOTE: This extension is disabled by default.

Raw TeX (Options.rawTex)

Allows to include raw TeX blocks into documents. Right now only environment blocks are supported. Everything between \begin{...} and \end{...} is treated as TeX and passed into resulting HTML as is.

Custom reference resolver

Custom reference resolver may be required when parsing document without implicitly defined references, for example, Dartdoc.

/**
 * Throws a [StateError] if ...
 * similar to [anotherMethod], but ...
 */

In that case, you could supply parser with the resolver, which should provide all missing links.

import 'package:mdown/mdown.dart';
import 'package:mdown/ast/standard_ast_factory.dart';

String library = "mdown";
String version = "0.11.0";
Target linkResolver(String normalizedReference, String reference) {
  if (reference.startsWith("new ")) {
    String className = reference.substring(4);
    return astFactory.target(
        "http://www.dartdocs.org/documentation/$library/$version/index.html#$library/$library.$className@id_$className-",
        null);
  } else {
    return null;
  }
}

String res = markdownToHtml('Hello world!\n===', new Options(linkResolver: linkResolver));

Use this package as a library

1. Depend on it

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


dependencies:
  mdown: "^0.12.0+2"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

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

3. Import it

Now in your Dart code, you can use:


      import 'package:mdown/mdown.dart';
  
Version Uploaded Documentation Archive
0.12.0+2 Jul 5, 2017 Go to the documentation of mdown 0.12.0+2 Download mdown 0.12.0+2 archive
0.12.0+1 Mar 17, 2017 Go to the documentation of mdown 0.12.0+1 Download mdown 0.12.0+1 archive
0.12.0 Jan 26, 2017 Go to the documentation of mdown 0.12.0 Download mdown 0.12.0 archive
0.11.0+2 Jan 18, 2017 Go to the documentation of mdown 0.11.0+2 Download mdown 0.11.0+2 archive
0.11.0+1 Jan 18, 2017 Go to the documentation of mdown 0.11.0+1 Download mdown 0.11.0+1 archive
0.11.0 Jan 18, 2017 Go to the documentation of mdown 0.11.0 Download mdown 0.11.0 archive

Analysis

We analyzed this package on Jun 19, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.63.0
  • pana: 0.11.3

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
45 / 100
Health:
Code health derived from static analysis. [more]
98 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
44 / 100
Overall score:
Weighted score of the above. [more]
60
Learn more about scoring.

Platforms

Detected platforms: unsure

Error(s) prevent platform classification:

Error(s) in lib/generators/embed_tests_generator.dart: Target of URI doesn't exist: 'package:analyzer/dart/element/element.dart'.

Suggestions

  • Fix platform conflicts.

    Error(s) prevent platform classification:

    Error(s) in lib/generators/embed_tests_generator.dart: Target of URI doesn't exist: 'package:analyzer/dart/element/element.dart'.

  • Running dartdoc failed.

    Make sure dartdoc runs without any issues.

  • Maintain CHANGELOG.md.

    Changelog entries help clients to follow the progress in your code.

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 26 errors 24 hints.

    Make sure that the imported libraries are not in conflict. Error(s) in lib/generators/embed_tests_generator.dart: Target of URI doesn't exist: 'package:analyzer/dart/element/element.dart'.

    Make sure that the imported libraries are not in conflict. Error(s) in lib/generators/embed_blns_tests_generator.dart: Target of URI doesn't exist: 'package:analyzer/dart/element/element.dart'.

    Similar analysis of the following files failed:

    • lib/generators/entities_generator.dart (error)
    • lib/mdown.dart (hint)
    • lib/src/ast/ast_factory.dart (hint)
    • lib/src/bit_set.dart (hint)
    • lib/src/parsers/blockquote_list.dart (hint)
    • lib/src/parsers/common.dart (hint)
    • lib/src/parsers/entity.dart (hint)
    • lib/src/parsers/fenced_code.dart (hint)
    • lib/src/parsers/html_block_7.dart (hint)
    • lib/src/parsers/link_image.dart (hint)
    • lib/src/parsers/link_reference.dart (hint)
    • lib/src/parsers/para_setext_heading.dart (hint)
    • lib/src/parsers/raw_tex.dart (hint)
    • lib/src/parsers/tex_math_dollars.dart (hint)
  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use mdown.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.21.0 <2.0.0
Dev dependencies
build_runner ^0.1.1
coverage ^0.8.0+2
source_gen >=0.5.2 <0.6.0
test ^0.12.17+2