Dart Markdown Parser #

A pure Dart markdown parser with AST-based architecture. No Flutter dependency - works in CLI tools, server-side applications, and web projects.

Extracted from flutter_smooth_markdown to provide a platform-agnostic markdown parsing solution.

Features #

• ✅ Pure Dart - No Flutter dependency, works everywhere Dart runs
• ✅ AST-based - Clean separation between parsing and rendering
• ✅ CommonMark - Full support for standard markdown syntax
• ✅ GitHub Flavored Markdown (GFM) - Tables, task lists, strikethrough
• ✅ Extended Syntax - Math formulas, footnotes, details/summary blocks
• ✅ Plugin System - Extensible with custom syntax parsers
• ✅ High Performance - LRU caching and optimized parsing
• ✅ Well Tested - 170+ tests with comprehensive coverage

Installation #

Add to your pubspec.yaml:

dependencies:
  dart_markdown_parser: ^0.1.0

Usage #

Basic Parsing #

import 'package:dart_markdown_parser/dart_markdown_parser.dart';

void main() {
  final parser = MarkdownParser();
  final nodes = parser.parse('# Hello **World**');

  for (final node in nodes) {
    print(node.toJson());
  }
}

Using Plugins #

final registry = ParserPluginRegistry();
registry.register(const MentionPlugin());
registry.register(const HashtagPlugin());
registry.register(const EmojiPlugin());

final parser = MarkdownParser(plugins: registry);
final nodes = parser.parse('Hello @user! Check out #dart :smile:');

Supported Markdown Syntax #

Block Elements:

• Headers (H1-H6): # Header
• Paragraphs
• Code blocks: ```language
• Lists (ordered/unordered): - item or 1. item
• Task lists: - [ ] todo or - [x] done
• Blockquotes: > quote
• Tables: | col1 | col2 |
• Horizontal rules: ---
• Math blocks: $$ formula $$
• Details/Summary: <details><summary>...</summary></details>
• Footnotes: [^1]: definition

Inline Elements:

• Bold: **text** or __text__
• Italic: *text* or _text_
• Inline code: `code`
• Links: [text](url)
• Images: ![alt](url)
• Strikethrough: ~~text~~
• Inline math: $formula$
• Footnote references: [^1]

Plugin-based Syntax:

• Mentions: @username
• Hashtags: #topic
• Emojis: :smile:
• Admonitions: !!! note blocks
• Thinking blocks: <thinking>...</thinking>
• Artifacts: <artifact>...</artifact>
• Tool calls: <tool_use>...</tool_use>

AST Structure #

All parsed content is represented as MarkdownNode objects:

abstract class MarkdownNode {
  String get type;
  Map<String, dynamic> toJson();
  MarkdownNode copyWith();
}

Available Node Types:

• TextNode - Plain text
• HeaderNode - Headers (H1-H6)
• ParagraphNode - Paragraphs
• CodeBlockNode - Code blocks
• ListNode / ListItemNode - Lists
• BlockquoteNode - Blockquotes
• TableNode / TableRowNode - Tables
• BoldNode / ItalicNode / StrikethroughNode - Text formatting
• LinkNode / ImageNode - Links and images
• InlineCodeNode - Inline code
• InlineMathNode / BlockMathNode - Math formulas
• FootnoteReferenceNode / FootnoteDefinitionNode - Footnotes
• DetailsNode - Collapsible blocks
• And more...

Creating Custom Plugins #

Extend the parser with custom syntax:

class CustomPlugin extends InlineParserPlugin {
  @override
  String get id => 'custom';

  @override
  int get priority => 100;

  @override
  String? get triggerChar => '@';

  @override
  bool canParse(String text, int offset) {
    // Check if this position can be parsed
    return text.startsWith('@custom', offset);
  }

  @override
  ParseResult? parse(String text, int offset) {
    // Parse and return custom node
    return ParseResult(
      node: CustomNode(...),
      consumedLength: 7,
    );
  }
}

// Register the plugin
final registry = ParserPluginRegistry();
registry.register(CustomPlugin());

Performance #

The parser includes built-in LRU caching for improved performance:

import 'package:dart_markdown_parser/dart_markdown_parser.dart';

final cache = ParseCache(maxSize: 100);
final parser = MarkdownParser();

// Parse with caching
final nodes = cache.get(markdownText, () => parser.parse(markdownText));

Examples #

See the example directory for comprehensive usage examples including:

• Basic parsing
• Plugin usage
• Table parsing
• Math formula parsing
• Custom node handling

Run the example:

dart run example/dart_markdown_parser_example.dart

Testing #

Run all tests:

dart test

The package includes 170+ tests covering:

• Block parsing
• Inline parsing
• Plugin system
• AST node operations
• Edge cases

Related Projects #

• flutter_smooth_markdown - Flutter renderer for this parser
• markdown - Alternative Dart markdown parser

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

MIT License - see LICENSE file for details.

Credits #

Extracted from flutter_smooth_markdown by JackCaow.