Flutter용 Dart 기반의 마크다운 라이브러리로 앱 내에서 마크다운 콘텐츠를 직접 파싱하고 렌더링할 수 있게 해줍니다. 다양한 마크다운 구문을 지원하며, Android, iOS, Web, macOS, Windows, Linux 등 주요 플랫폼에 원활하게 통합됩니다. 문서, 블로그 게시물, 사용자 생성 콘텐츠와 같은 풍부한 형식의 텍스트 표시에 이상적입니다. 가볍고 모바일 및 웹 환경에서의 성능을 고려해 설계되었습니다.
사용 사례
Markdown 파일에서 동적 콘텐츠 렌더링
포맷이 적용된 사용자 생성 텍스트 표시
문서 또는 도움말 섹션 작성
미리보기 모드를 갖춘 리치 텍스트 에디터 만들기
앱에 블로그 스타일 콘텐츠 통합하기
주요 기능
표준 마크다운 문법을 지원합니다
크로스 플랫폼 호환성
경량이고 빠른 파싱
Flutter 위젯과의 간편한 통합
사용자 지정 가능한 스타일 옵션
적합한 대상
풍부한 텍스트 표시가 필요한 앱
문서 또는 지식 기반 기능
콘텐츠 중심 애플리케이션
UI 콘텐츠에 마크다운을 사용하는 개발자
다중 플랫폼을 대상으로 하는 프로젝트
고려 사항
고급 HTML 확장 기능에 대한 제한된 지원
내장된 구문 강조 없음
복잡한 레이아웃을 위해 사용자 정의 스타일링이 필요할 수 있습니다
매우 큰 마크다운 문서의 성능 영향
업데이트 및 수정은 외부 소스에 의존합니다
원본 README
연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.
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.