Package selection guidance compiled from public package information, community data, and project usage.
A Dart-based Markdown library for Flutter that enables parsing and rendering Markdown content directly in apps. It supports a wide range of Markdown syntax and integrates seamlessly across all major platforms, including Android, iOS, Web, macOS, Windows, and Linux. The package is ideal for displaying formatted text such as documentation, blog posts, or user-generated content with rich formatting. It's lightweight and designed for performance in both mobile and web environments.
Use cases
Rendering dynamic content from Markdown files
Displaying user-generated text with formatting
Building documentation or help sections
Creating rich text editors with preview modes
Integrating blog-style content in apps
Key features
Supports standard Markdown syntax
Cross-platform compatibility
Lightweight and fast parsing
Easy integration with Flutter widgets
Customizable styling options
Suitable for
Apps needing rich text display
Documentation or knowledge base features
Content-heavy applications
Developers using Markdown for UI content
Projects targeting multiple platforms
Considerations
Limited support for advanced HTML extensions
No built-in syntax highlighting
May require custom styling for complex layouts
Performance impact with very large Markdown documents
Depends on external source for updates and fixes
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
flutter_md - Markdown Parser and Renderer for Flutter
A high-performance, lightweight Markdown parser and renderer specifically designed for Flutter applications. Perfect for displaying formatted text from AI assistants like ChatGPT, Gemini, and other LLMs.
🌟 Features
🚀 High Performance: Hand-tuned single-pass parser with minimal allocations
🎨 Fully Customizable: Theme-based styling with complete control over appearance
📱 Flutter Native: Built from the ground up for Flutter with custom render objects
🔗 Interactive Elements: Clickable links with customizable tap handlers
✂️ Text Selection: Cross-block and cross-widget (chat) selection via a
controller that survives list disposal and streaming updates
🌊 Streaming Parser: StreamingMarkdownParser parses LLM token output
incrementally — completed blocks are frozen, only the live tail re-parses
🌐 Cross Platform: Works on all Flutter-supported platforms
📝 GitHub Flavored: Alerts (> [!NOTE]), task lists (- [x]), tables with
column alignment, thematic breaks, strikethrough, and more
🌈 Syntax Highlighting: Opt-in, dependency-free code-block highlighting —
65+ languages and GitHub light/dark themes; only the languages you import are
bundled (the rest tree-shake away)
🎯 AI-Optimized: Specifically designed for AI-generated content display
🔧 Extensible: Easy to extend with custom block and span renderers
✅ Well Tested: 370+ tests; parser and node model at ~100% line coverage
Emphasis follows CommonMark-inspired flanking rules, so stray markers
(5 * 6 = 30), intraword underscores (snake_case), and unterminated markers
(**oops) are left as literal text instead of leaking styles.
Inline math (opt-in)
Inline $...$ LaTeX math is disabled by default (so prices like $5 and
shell variables like $HOME are never altered). Enable it per parse or per
decoder:
// Per parse:final md = Markdown.fromString(r'The angle $\alpha$ and $x^2 + y^2$.',
inlineMath: true);
// Or a reusable decoder, optionally extending the command table:const decoder = MarkdownDecoder(
inlineMath: true,
mathReplacements: {...kMarkdownMathCommands, r'\R': 'ℝ'},
);
It converts LaTeX commands (\alpha, \rightarrow, ...) and super/subscripts
(x^2, H_2O, x^{10}), is code-span and code-block safe, and treats \$ as
a literal dollar. Write \$\alpha\$ to keep a literal $\alpha$.
- Unordered list item
- Another item
- Nested item
- Deep nested item
1. Ordered list item
2. Another numbered item
1. Nested numbered item
2. Another nested item
- [x] Completed task-list item
- [ ] Pending task-list item
Task-list state is exposed on MD$ListItem.checked (true/false/null) and
MD$ListItem.isTask, and rendered as a checkbox.
Blockquotes
> This is a blockquote
> It can span multiple lines
>
> And have multiple paragraphs
Alerts (Admonitions)
GitHub-style alerts are rendered from blockquotes with a type marker:
> [!NOTE]
> Highlights information that users should take into account.
> [!TIP]
> Optional information to help a user be more successful.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention.
> [!CAUTION]
> Negative potential consequences of an action.
Each alert becomes an MD$Alert block (MD$AlertType.note, .tip,
.important, .warning, .caution). Per-type accent colors are configurable
via MarkdownThemeData.alertColors / alertColorFor.
[Link text](https://example.com)

Images currently not displayed!
Horizontal Rules
Any of ---, ***, or ___ (optionally spaced, e.g. - - -) produce a rule:
---
---
---
🚀 Quick Start
Installation
Add this to your package's pubspec.yaml file:
dependencies:flutter_md:^x.x.x# Replace with the latest version
Then run:
flutter pub get
Upgrading from 0.0.x? See the
Migration guide: 0.0.x → 0.2.x. The upgrade
is almost entirely backward compatible — most apps need no code changes.
✂️ Text Selection
Selection is anchored on the immutable Markdown model, not on the render
objects, so it spans multiple blocks (heading → paragraph → list → table cell)
and multiple MarkdownWidgets (e.g. chat messages), and it survives widgets
being scrolled off-screen and disposed. Wrap a group of widgets in a
MarkdownSelectionScope, give each a stable documentId, and register the
models with the controller:
final controller = MarkdownSelectionController();
// Register the documents in reading order (a chat feeds this from its list).
controller.setDocuments([
for (final (i, m) in messages.indexed)
MarkdownDocumentRef(id: m.id, model: m.markdown, order: i),
]);
MarkdownSelectionScope(
controller: controller,
child: ListView.builder(
itemCount: messages.length,
itemBuilder: (context, i) => MarkdownWidget(
documentId: messages[i].id,
markdown: messages[i].markdown,
),
),
);
// Any time — even for messages scrolled off-screen:finalString text = controller.getText(); // default formatterfinalString md = controller.getText(constMarkdownMarkupFormatter()); // as MarkdownfinalMarkdownSelectedContent structured = controller.selectedContent();
Every block is selectable. Paragraphs, headings, quotes, code, alerts,
lists and tables — a drag can start or end inside a list item or table cell,
and copied text preserves the list \n / table \t separators.
Get the text your way.getText() uses the default
MarkdownPlainTextFormatter (configurable block/document separators). For
richer output pass the built-in MarkdownMarkupFormatter ("Copy as
Markdown"): it re-emits heading #s, nested list markers with task
checkboxes, blockquote/alert > prefixes, fenced code and pipe tables for
fully-selected blocks (partially-selected edges fall back to plain text). Or
implement your own MarkdownSelectionFormatter. selectedContent() returns
the structured per-document / per-block result each formatter consumes.
Streaming stays anchored. Call controller.putDocument(id, newModel) when
a message grows; the default MarkdownReconciliationPolicy.contentAnchored
keeps the selection (append fast-path, else relocate by content, else clamp).
One selection at a time. Share a MarkdownSelectionGroup between
controllers so selecting in one clears the others; call group.clearExternal()
when a plain SelectableText/SelectionArea starts its own selection.
Gestures. A mouse/trackpad/stylus drag selects; on touch a
long-press-then-drag selects (so a plain swipe still scrolls the list).
Native handles, magnifier & toolbar. On touch platforms the selection
shows draggable handles and a magnifier (they follow the content as it
scrolls, even across widgets); right-click (desktop) or long-press (mobile)
shows an adaptive Copy / Select-all toolbar.
Keyboard shortcuts. When the scope is focused: Ctrl/Cmd+C copies,
Ctrl/Cmd+A selects all, Shift+arrows extend (character / word / line /
document, plus vertical), Esc clears — using the ambient
DefaultTextEditingShortcuts.
Customizable like SelectableText.MarkdownSelectionScope takes
selectionColor, contextMenuBuilder, magnifierConfiguration,
selectionControls, focusNode, enabled and onSelectionChanged; its
public MarkdownSelectionScopeState exposes copySelection / selectAll /
clearSelection / showToolbar / contextMenuButtonItems /
contextMenuAnchors for a fully custom menu.
Opt-in & compatible. A MarkdownWidget with no documentId/controller is
inert — existing usage is unchanged.
See the runnable Selection and Chat tabs in example/.
🌊 Streaming (LLM output)
LLM replies arrive token by token. Re-parsing the whole accumulated buffer on
every token is O(N²) and janks long messages. StreamingMarkdownParser keeps
the accumulated source and only re-parses the still-growing tail: once a
block is provably complete (terminated by a blank line, and not inside an open
code fence) it is frozen and never parsed again.
Exact, never approximate. The result of add() / current is always
identical, block for block, to Markdown.fromString(everythingReceivedSoFar).
Blocks whose type still depends on input that hasn't arrived — an unterminated
code fence, a table header still missing its delimiter row, a list that may
continue — stay in the live tail and are re-evaluated, so they never freeze
into the wrong shape.
Same options as batch. Pass a configured decoder to match
Markdown.fromString:
StreamingMarkdownParser(decoder: const MarkdownDecoder(inlineMath: true))
(or .toMarkdown(decoder: ...)).
Fast. Replaying a whole message token-by-token is 3–14× faster than
the full-reparse approach, and the gap grows with message length
(benchmark/streaming_benchmark.dart).
Reusable.parser.reset() clears state for the next message;
parser.source is the raw text accumulated so far, parser.current the
parsed model without adding anything.
Pair it with selection: feed each grown model to controller.putDocument(id, md)
and the active selection stays anchored as the message streams in (see the
Chat tab in example/).
🌈 Syntax Highlighting
Fenced code blocks can be syntax-highlighted with a tree-shakeable,
dependency-free highlighter — 65+ languages and ready-made GitHub light/dark
themes. Highlighting is opt-in and off by default (code renders as plain
monospace): assign a SyntaxHighlighter to MarkdownThemeData.highlighter.
import'package:flutter_md/highlight.dart'; // engine + MarkdownHighlighterimport'package:flutter_md/highlight/dart.dart'; // one import per languageimport'package:flutter_md/highlight/sql.dart';
import'package:flutter_md/highlight/themes.dart'; // HighlightThemesfinal theme = MarkdownThemeData.mergeTheme(
Theme.of(context),
highlighter: MarkdownHighlighter(
// You assemble the map, so only these grammars are compiled in.
languages: {
'dart': HighlightDart.grammar,
'sql': HighlightSql.grammar,
},
theme: isDark ? HighlightThemes.githubDark : HighlightThemes.githubLight,
),
);
MarkdownWidget(markdown: doc, theme: theme);
Only the languages you import ship. Each language is its own library
exposing a single grammar, referenced through lazy thunks with no central
registry/Map/enum. Importing highlight/dart.dart never references any
other language, so unused grammars are removed by tree-shaking — a Dart-only
app adds ~0 beyond the engine, and all 65 languages together add ~62 KB
(gzipped) only if you deliberately bundle them all.
Selection- and copy-safe. The highlighter only partitions the source
into colored spans; the concatenated text is byte-identical, so cross-block
selection, offsets and "Copy as Markdown" stay aligned.
Themes. Use HighlightThemes.githubDark / githubLight, or implement
CodeHighlightTheme (a switch from token type → TextStyle) for your own
palette. Its background is applied to the code-block surface.
Demos & tooling.import 'package:flutter_md/highlight/all.dart'; exposes
allHighlightLanguages, a ready map of every grammar keyed by tag and alias
(js, ts, sh, …). It references everything, so unused languages can no
longer be tree-shaken away — use it for demos, not production.
Robust. Unknown languages fall back to plain text; a pattern Dart's regex
engine rejects disables just that one rule instead of breaking the language.
The grammars are generated by tool/highlight_codegen (see its README to
regenerate or add languages). See the runnable Highlight tab in example/.
Syntax grammars are adapted from Prism (MIT License).
MarkdownTheme(
data: MarkdownThemeData(
textStyle: TextStyle(fontSize: 16.0, color: Colors.black87),
h1Style: TextStyle(
fontSize: 24.0,
fontWeight: FontWeight.bold,
color: Colors.blue,
),
h2Style: TextStyle(
fontSize: 22.0,
fontWeight: FontWeight.bold,
color: Colors.blueGrey,
),
quoteStyle: TextStyle(
fontSize: 14.0,
fontStyle: FontStyle.italic,
color: Colors.grey[600],
),
// Customize link text styling (merged on top of linkColor)
linkStyle: constTextStyle(
decoration: TextDecoration.underline,
),
// Monospace face for inline `code` AND fenced blocks. Leave it unset to// get a family the host platform can actually resolve: `monospace` on// Android / Linux / web, Menlo on iOS + macOS, Consolas on Windows// (CoreText and DirectWrite do not know the CSS generic, so code would// otherwise render in the proportional body face there).
monospaceFontFamily: 'JetBrains Mono',
// Per-type accent colors for GitHub alert blocks
alertColors: const {
MD$AlertType.warning: Color(0xFF9A6700),
},
// Handle link taps
onLinkTap: (title, url) {
print('Tapped link: $title -> $url');
// Launch URL or navigate
},
// Filter blocks (e.g., hide code blocks)
blockFilter: (block) => block is! MD$Code,
// Filter spans (e.g., exclude images or certain styles)
spanFilter: (span) => !span.style.contains(MD$Style.image),
),
child: MarkdownWidget(
markdown: yourMarkdown,
),
)
Or you can use the MarkdownThemeData.mergeTheme(Theme.of(context)) factory to create a theme that inherits from the application's theme.
This approach allows you to easily support both light and dark themes, and keeps your markdown styling consistent with the rest of your application.
Custom Block Painters
For advanced customization, you can provide custom block painters:
MarkdownThemeData(
builder: (block, theme) {
if (block is MD$Code && block.language == 'dart') {
// Return custom painter for Dart code blocksreturnCustomDartCodePainter(block: block, theme: theme);
}
returnnull; // Use default painter
},
)
Performance Optimization
For large markdown documents or frequently changing content:
flutter_md is built for speed: a single-pass, lookup-table parser (regex-free
hot path with a plain-text fast path) and a custom render object that lays the
whole document into one cached ui.Picture instead of a deep tree of per-block
widgets.
Head-to-head against flutter_markdown and gpt_markdown on the same machine
(i7-13700K) with identical styles — full tables and methodology in
benchmark_compare/RESULTS.md:
Parsing — ~18× faster than the markdown package that backs
flutter_markdown (gpt_markdown has no standalone parser), sustaining
~60 MB/s on mixed documents.
Rendering (string → painted pixels) — ~6.6× faster than
flutter_markdown and ~15.6× faster than gpt_markdown on a large document
(1.2–1.6× on small chat bubbles).
Scrolling — 60 fps with zero dropped frames in profile mode, and the
lowest UI-thread frame-build cost of the three (99th-percentile frame build
1.6 ms vs 4.8 / 9.4 ms).
# In-repo parser micro-benchmarks:
dart run benchmark/parser_benchmark.dart # multi-scenario, vs. `markdown`
dart run benchmark/compare.dart --save # low-noise before/after tool# Head-to-head vs flutter_markdown & gpt_markdown (parser + render):cd benchmark_compare && flutter pub get
dart run benchmark/parser_benchmark.dart
flutter testtest/render_benchmark_test.dart
Contributions are welcome! Please feel free to submit a Pull Request.
For major changes, please open an issue first to discuss what you would like to change.
Development Setup
git clone https://github.com/DoctorinaAI/md.git md
cd md
flutter pub get
flutter test
Running the Example
cd example
flutter run
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Unlike other Markdown packages that rely on HTML rendering or web views, flutter_md is built specifically for Flutter using custom render objects. This provides:
Better Performance: No HTML parsing or web view overhead
Native Feel: Fully integrated with Flutter's rendering pipeline
Customization: Complete control over styling and behavior
Reliability: Consistent rendering across all platforms
Small Size: Minimal package size with no external dependencies
Perfect for chat applications, documentation viewers, note-taking apps, and any Flutter application that needs to display rich formatted text from AI assistants or user input.