From 5e4a634512f74766ee5732dbb33f1d4555b5cb0a Mon Sep 17 00:00:00 2001
From: JalonSolov <JalonSolov@gmail.com>
Date: Mon, 20 Apr 2026 13:08:51 -0400
Subject: [PATCH] x.markdown: add pure V markdown module (#26925)

* add pure V markdown module

* x.markdown: implement AI suggestions
---
 .gitignore                      |   37 +-
 vlib/x/markdown/README.md       |  288 +++++++
 vlib/x/markdown/extension.v     |  115 +++
 vlib/x/markdown/html.v          |  405 ++++++++++
 vlib/x/markdown/inline.v        |  877 +++++++++++++++++++++
 vlib/x/markdown/markdown.v      |  142 ++++
 vlib/x/markdown/markdown_test.v |  343 +++++++++
 vlib/x/markdown/node.v          |  144 ++++
 vlib/x/markdown/parser.v        | 1261 +++++++++++++++++++++++++++++++
 vlib/x/markdown/util.v          |  244 ++++++
 10 files changed, 3835 insertions(+), 21 deletions(-)
 create mode 100644 vlib/x/markdown/README.md
 create mode 100644 vlib/x/markdown/extension.v
 create mode 100644 vlib/x/markdown/html.v
 create mode 100644 vlib/x/markdown/inline.v
 create mode 100644 vlib/x/markdown/markdown.v
 create mode 100644 vlib/x/markdown/markdown_test.v
 create mode 100644 vlib/x/markdown/node.v
 create mode 100644 vlib/x/markdown/parser.v
 create mode 100644 vlib/x/markdown/util.v

diff --git a/.gitignore b/.gitignore
index 925ab8389..1a88525cd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,14 +1,13 @@
 # ignore sub-level untracked files and the v binary
 */**/*
+
 # unignore checker test files
 !vlib/v/checker/tests/*.vv
 !vlib/v/checker/tests/*.out
-v
-v.exe
-v2
-v2.exe
-vdbg
-vdbg.exe
+
+# unignore vlib/x/markdown
+!vlib/x/markdown/**
+
 !*/
 # Do not add !*.* here; it overrides local excludes from .git/info/exclude.
 *.exe
@@ -28,23 +27,20 @@ a.out
 .noprefix.vrepl_temp
 
 # ignore v build files
+# *.exe is already ignored above
+/v
+/v2
 /vc
 /v.c
 /v.*.c
 /v.c.out
 /v_old
-/v_old.exe
+/vdbg
 /vold
-/vold.exe
 /vnew
-/vnew.exe
 /vprod
 /vprod_gcc
 /vprod_clang
-/vprod.exe
-/vprod_gcc.exe
-/vprod_clang.exe
-/vprod_msvc.exe
 .vrepl_temp.v
 fns.txt
 .noprefix.vrepl_temp.v
@@ -68,11 +64,10 @@ cache/
 !GNUmakefile
 
 # ignore editor files
-.idea
-.project
-.classpath
-.c9
-.vs
+.project/
+.classpath/
+.c9/
+.vs/
 *.launch
 .settings/
 *.sublime-workspace
@@ -143,7 +138,7 @@ vls.log
 .idea/
 /*.iml
 
-#ignore generated files:
+# ignore generated files:
 wasm.v
 
 # ignore large GTK *.gir files
@@ -153,7 +148,7 @@ Gtk-4.0.gir
 vlib/builtin/js/*.js
 vlib/v/tests/*.js
 
-#ignore tags indexes, used by emacs/vim:
+# ignore tags indexes, used by emacs/vim:
 ETAGS
 TAGS
 tags
@@ -169,7 +164,7 @@ autofuzz.log
 .project.gf
 .aider*
 
-#ignore common file names for bugs/reproductions
+# ignore common file names for bugs/reproductions
 bug*
 issue*
 
diff --git a/vlib/x/markdown/README.md b/vlib/x/markdown/README.md
new file mode 100644
index 000000000..96ad43e4f
--- /dev/null
+++ b/vlib/x/markdown/README.md
@@ -0,0 +1,288 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+
+# vlib/x/markdown - Markdown Parser and HTML Renderer
+
+A CommonMark-compliant Markdown parser and HTML renderer for V, with support for GitHub Flavored Markdown (GFM) extensions. Designed for feature parity with [github.com/yuin/goldmark](https://github.com/yuin/goldmark).
+
+## Features
+
+### CommonMark Support
+- **Block-level elements**: headings (ATX and setext), paragraphs, blockquotes,
+  lists (bullet and ordered), code blocks (indented and fenced), HTML blocks,
+  thematic breaks
+- **Inline elements**: emphasis (*em* and **strong**), code spans, links
+  (inline and reference), images, autolinks, hard/soft line breaks, HTML
+  entities, raw HTML
+- **Link reference definitions** for DRY Markdown
+
+### GFM Extensions (via `.gfm()` helper or individual extensions)
+- **Tables**: `| col | col |` with alignment (`:--`, `:--:`, `--:`)
+- **Strikethrough**: `~~text~~`
+- **Task lists**: `- [ ] todo` and `- [x] done`
+- **Linkify**: bare URLs become links
+
+### Additional Extensions
+- **Footnotes**: `[^1]` references and `[^1]: footnote text` definitions
+- **Typographer**: smart punctuation (`--` → en-dash, `---` → em-dash,
+  `...` → ellipsis, smart quotes)
+- **Auto-heading IDs**: automatic `id` attributes on headings from text content
+- **Definition lists**: Pandoc-style (requires extension)
+
+## Quick Start
+
+### Basic Usage
+
+```v
+import x.markdown
+
+fn main() {
+	html := markdown.to_html('# Hello\n\nWorld')
+	println(html)
+	// Output: <h1>Hello</h1>\n<p>World</p>\n
+}
+```
+
+### With Extensions
+
+```v oksyntax
+mut md := markdown.new(Options{
+	extensions: markdown.gfm()
+})
+html := md.convert('| Name |\n|------|\n| Alice |')
+println(html) // Renders as HTML table
+```
+
+### Fine-Grained Configuration
+
+```v
+import x.markdown
+
+fn main() {
+	mut md := markdown.new(markdown.Options{
+		extensions:    [markdown.Extension(markdown.footnote()), markdown.typographer()]
+		parser_opts:   markdown.ParserOptions{
+			auto_heading_id: true
+		}
+		renderer_opts: markdown.RendererOptions{
+			unsafe_: true
+			xhtml:   true
+		}
+	})
+	source := '# Title'
+	html := md.convert(source)
+	println(html)
+}
+```
+
+### Parse to AST and Walk
+
+```v
+import x.markdown
+
+fn main() {
+	mut md := markdown.new(markdown.Options{})
+	source := '# Hello\n\n`x`'
+	doc := md.parse(source)
+	doc.walk(fn (node &markdown.Node) bool {
+		match node.kind {
+			.heading {
+				println('Heading level ${node.level}')
+			}
+			.code_span {
+				println('Code: ${node.literal}')
+			}
+			else {}
+		}
+
+		return true
+	})
+}
+```
+
+## API Overview
+
+### Top-Level Functions
+- `to_html(src: string) string` - Convert Markdown to HTML with default settings
+- `to_html_opts(src: string, opts: Options) string` - Convert with custom options
+- `parse_inline(src: string, opts: Options, ref_map: map) []&Node` - Parse inline content only
+
+### Main Structs
+
+#### `Markdown`
+The main processor. Create with `new()`, reuse across multiple calls to share link references.
+
+Methods:
+- `convert(src: string) string` - Parse and render to HTML in one call
+- `parse(src: string) &Node` - Parse to AST only
+
+#### `Options` (@[params])
+```v oksyntax
+pub struct Options {
+pub mut:
+	extensions    []Extension
+	parser_opts   ParserOptions
+	renderer_opts RendererOptions
+	// Extension feature flags (set by extensions)
+	tables          bool
+	strikethrough   bool
+	linkify         bool
+	task_list       bool
+	footnotes       bool
+	typographer     bool
+	definition_list bool
+}
+```
+
+#### `ParserOptions` (@[params])
+```v oksyntax
+pub struct ParserOptions {
+pub mut:
+	auto_heading_id bool // Generate id from heading text
+}
+```
+
+#### `RendererOptions` (@[params])
+```v oksyntax
+pub struct RendererOptions {
+pub mut:
+	unsafe_    bool // Allow raw HTML (default: false)
+	hard_wraps bool // Convert all \n to <br> (default: false)
+	xhtml      bool // Output XHTML self-closing tags (default: false)
+}
+```
+
+#### `Node`
+An AST node. Navigate with `.children`, inspect with `.kind`, `.literal`, `.level`, etc.
+
+Methods:
+- `text_content() string` - Extract plain text from this node and descendants
+- `walk(f: fn(&Node) bool) bool` - Traverse AST pre-order; return false from callback to stop
+
+### Extensions
+
+Available as functions returning extension structs:
+- `table()` - GFM tables
+- `strikethrough()` - GFM strikethrough
+- `linkify()` - Bare URL autolinks
+- `task_list()` - GFM task lists
+- `footnote()` - Footnote references and definitions
+- `typographer()` - Smart punctuation
+- `definition_list()` - Pandoc-style definition lists
+- `gfm()` - Convenience helper returning `[table(), strikethrough(), linkify(), task_list()]`
+
+## Examples
+
+### Simple Emphasis
+
+```v oksyntax
+assert markdown.to_html('*em*').contains('<em>em</em>')
+assert markdown.to_html('**strong**').contains('<strong>strong</strong>')
+```
+
+### Links and Images
+
+```v oksyntax
+// Inline link
+html := markdown.to_html('[click](https://example.com)')
+// Reference link
+html = markdown.to_html('[click][ref]\n\n[ref]: https://example.com')
+// Image
+html = markdown.to_html('![alt](image.png "title")')
+```
+
+### Code Blocks
+
+```v oksyntax
+// Indented code
+html := markdown.to_html('    code')
+// Fenced code
+html = markdown.to_html('```v\nfn main() {}\n```')
+```
+
+### Lists
+
+```v oksyntax
+// Bullet list
+html := markdown.to_html('- item 1\n- item 2')
+// Ordered list
+html = markdown.to_html('1. first\n2. second')
+// Task list (enable via extension or task_list option)
+html = markdown.to_html_opts('- [x] done', Options{ task_list: true })
+```
+
+### Tables (GFM)
+
+```v oksyntax
+src := '| Left | Center | Right |\n|:--|:--:|--:|\n| A | B | C |'
+html := markdown.to_html_opts(src, Options{ tables: true })
+```
+
+### Footnotes
+
+```v oksyntax
+src := 'Text[^1]\n\n[^1]: Footnote body.'
+html := markdown.to_html_opts(src, Options{ footnotes: true })
+// Renders with <sup> reference and footnote section at bottom
+```
+
+## Design Notes
+
+### Block Parsing
+- Reads source line-by-line, building a block-level AST
+- Handles lazy continuation lines for blockquotes and lists
+- Collects link reference definitions for inline resolution
+
+### Inline Parsing
+- Parses raw text from paragraph/heading/cell nodes using a simple state machine
+- Emphasis/strong uses a delimiter-run resolution pass aligned with CommonMark rules
+- Backticks, brackets, and HTML are handled specially
+
+### Rendering
+- Tree walk via `render_node()` dispatch on `NodeKind`
+- Inline nodes parsed on-demand during rendering
+- Link references cached in `Markdown` for reuse across multiple convert calls
+
+## Limitations and Known Issues
+
+- Definition list syntax is Pandoc-style; CommonMark does not define this
+
+**Status**: All core features (headings, emphasis, links, code, lists,
+blockquotes, task lists, tables, HTML escaping) work reliably without crashes.
+
+## Testing
+
+Run the test suite:
+
+```bash
+v -silent test vlib/x/markdown/markdown_test.v
+```
+
+Or write your own:
+
+```v oksyntax
+import x.markdown
+
+fn test_my_markdown() {
+	html := markdown.to_html('# Test')
+	assert html == '<h1>Test</h1>\n'
+}
+```
+
+## Contributing
+
+- Follow V style guidelines (use `v fmt -w` on edits)
+- Add tests for new features
+- Update documentation for public API changes
+- Keep CommonMark compliance as the baseline
+
+## License
+
+MIT, same as V.
+
+## References
+
+- [CommonMark Specification](https://spec.commonmark.org/)
+- [GitHub Flavored Markdown](https://github.github.com/gfm/)
+- [goldmark (Go implementation)](https://github.com/yuin/goldmark)
diff --git a/vlib/x/markdown/extension.v b/vlib/x/markdown/extension.v
new file mode 100644
index 000000000..aff85c4db
--- /dev/null
+++ b/vlib/x/markdown/extension.v
@@ -0,0 +1,115 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+module markdown
+
+// Extension is the interface implemented by markdown extensions.
+// An extension configures the Markdown processor by enabling parser and
+// renderer features.
+pub interface Extension {
+	// extend is called once when the extension is registered with a Markdown processor.
+	extend(mut m Markdown)
+}
+
+// TableExt adds GitHub Flavored Markdown table support (| col | col |).
+pub struct TableExt {}
+
+// extend implements Extension for TableExt.
+pub fn (_ TableExt) extend(mut m Markdown) {
+	m.opts.tables = true
+}
+
+// StrikethroughExt adds GFM strikethrough support (~~text~~).
+pub struct StrikethroughExt {}
+
+// extend implements Extension for StrikethroughExt.
+pub fn (_ StrikethroughExt) extend(mut m Markdown) {
+	m.opts.strikethrough = true
+}
+
+// LinkifyExt adds autolink support for bare URLs and email addresses.
+pub struct LinkifyExt {}
+
+// extend implements Extension for LinkifyExt.
+pub fn (_ LinkifyExt) extend(mut m Markdown) {
+	m.opts.linkify = true
+}
+
+// TaskListExt adds GFM task list item support (- [ ] / - [x]).
+pub struct TaskListExt {}
+
+// extend implements Extension for TaskListExt.
+pub fn (_ TaskListExt) extend(mut m Markdown) {
+	m.opts.task_list = true
+}
+
+// FootnoteExt adds footnote support ([^label] references and [^label]: definitions).
+pub struct FootnoteExt {}
+
+// extend implements Extension for FootnoteExt.
+pub fn (_ FootnoteExt) extend(mut m Markdown) {
+	m.opts.footnotes = true
+}
+
+// TypographerExt replaces ASCII punctuation sequences with Unicode typographic
+// equivalents: -- en dash, --- em dash, ... ellipsis, and smart quotes.
+pub struct TypographerExt {}
+
+// extend implements Extension for TypographerExt.
+pub fn (_ TypographerExt) extend(mut m Markdown) {
+	m.opts.typographer = true
+}
+
+// DefinitionListExt adds Pandoc-style definition list support.
+pub struct DefinitionListExt {}
+
+// extend implements Extension for DefinitionListExt.
+pub fn (_ DefinitionListExt) extend(mut m Markdown) {
+	m.opts.definition_list = true
+}
+
+// table returns a TableExt extension value.
+pub fn table() TableExt {
+	return TableExt{}
+}
+
+// strikethrough returns a StrikethroughExt extension value.
+pub fn strikethrough() StrikethroughExt {
+	return StrikethroughExt{}
+}
+
+// linkify returns a LinkifyExt extension value.
+pub fn linkify() LinkifyExt {
+	return LinkifyExt{}
+}
+
+// task_list returns a TaskListExt extension value.
+pub fn task_list() TaskListExt {
+	return TaskListExt{}
+}
+
+// footnote returns a FootnoteExt extension value.
+pub fn footnote() FootnoteExt {
+	return FootnoteExt{}
+}
+
+// typographer returns a TypographerExt extension value.
+pub fn typographer() TypographerExt {
+	return TypographerExt{}
+}
+
+// definition_list returns a DefinitionListExt extension value.
+pub fn definition_list() DefinitionListExt {
+	return DefinitionListExt{}
+}
+
+// gfm returns the core GitHub Flavored Markdown extensions:
+// TableExt, StrikethroughExt, LinkifyExt, and TaskListExt.
+pub fn gfm() []Extension {
+	return [
+		Extension(TableExt{}),
+		StrikethroughExt{},
+		LinkifyExt{},
+		TaskListExt{},
+	]
+}
diff --git a/vlib/x/markdown/html.v b/vlib/x/markdown/html.v
new file mode 100644
index 000000000..7f64d52a9
--- /dev/null
+++ b/vlib/x/markdown/html.v
@@ -0,0 +1,405 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+module markdown
+
+import strings
+
+// HTMLRenderer renders a parsed markdown AST to an HTML string.
+struct HTMLRenderer {
+	opts    Options
+	ref_map map[string]LinkRef
+mut:
+	sb strings.Builder
+	// footnote tracking
+	fn_order      []string         // ordered list of encountered fn labels
+	fn_nodes      map[string]&Node // label → footnote_def node
+	tight_list    bool             // whether we're inside a tight list
+	in_table_head bool
+}
+
+// render renders the document node to an HTML string.
+pub fn (mut r HTMLRenderer) render(doc &Node) string {
+	r.sb = strings.new_builder(1024)
+	// Pre-collect footnote definitions if extension is enabled.
+	if r.opts.footnotes {
+		for child in doc.children {
+			if child.kind == .footnote_def {
+				r.fn_nodes[child.fn_label] = child
+			}
+		}
+	}
+	r.render_children(doc)
+	// Append footnotes section if any refs were used.
+	if r.opts.footnotes && r.fn_order.len > 0 {
+		r.render_footnotes_section()
+	}
+	return r.sb.str()
+}
+
+// render_node dispatches rendering to the appropriate method.
+fn (mut r HTMLRenderer) render_node(node &Node) {
+	match node.kind {
+		.document { r.render_children(node) }
+		.heading { r.render_heading(node) }
+		.paragraph { r.render_paragraph(node) }
+		.blockquote { r.render_blockquote(node) }
+		.list { r.render_list(node) }
+		.list_item { r.render_list_item(node) }
+		.code_block { r.render_code_block(node) }
+		.fenced_code { r.render_fenced_code(node) }
+		.thematic_break { r.render_thematic_break() }
+		.html_block { r.render_html_block(node) }
+		.link_ref_def {} // already collected, nothing to render
+		.table { r.render_table(node) }
+		.table_head { r.render_table_section(node, 'thead') }
+		.table_body { r.render_table_section(node, 'tbody') }
+		.table_row { r.render_table_row(node) }
+		.table_cell { r.render_table_cell(node) }
+		.definition_list { r.render_definition_list(node) }
+		.definition_term { r.render_definition_term(node) }
+		.definition_desc { r.render_definition_desc(node) }
+		.footnote_def {} // rendered in the footnote section
+		// Inline nodes.
+		.text { r.render_text(node) }
+		.emphasis { r.render_emphasis(node) }
+		.strong { r.render_strong(node) }
+		.code_span { r.render_code_span(node) }
+		.link { r.render_link(node) }
+		.image { r.render_image(node) }
+		.autolink { r.render_autolink(node) }
+		.raw_html { r.render_raw_html(node) }
+		.hard_break { r.render_hard_break() }
+		.soft_break { r.render_soft_break() }
+		.strikethrough { r.render_strikethrough(node) }
+		.task_checkbox { r.render_task_checkbox(node) }
+		.footnote_ref { r.render_footnote_ref(node) }
+	}
+}
+
+// render_children renders all children of node.
+fn (mut r HTMLRenderer) render_children(node &Node) {
+	for child in node.children {
+		r.render_node(child)
+	}
+}
+
+// render_inline parses and renders inline content from a literal string.
+fn (mut r HTMLRenderer) render_inline(src string) {
+	nodes := parse_inline(src, r.opts, r.ref_map)
+	for node in nodes {
+		r.render_node(node)
+	}
+}
+
+// ---- Block elements ----
+
+fn (mut r HTMLRenderer) render_heading(node &Node) {
+	tag := 'h${node.level}'
+	if node.id.len > 0 {
+		r.sb.write_string('<${tag} id="${html_escape(node.id)}">')
+	} else {
+		r.sb.write_string('<${tag}>')
+	}
+	if node.children.len > 0 {
+		r.render_children(node)
+	} else {
+		r.render_inline(node.literal)
+	}
+	r.sb.write_string('</${tag}>\n')
+}
+
+fn (mut r HTMLRenderer) render_paragraph(node &Node) {
+	if r.tight_list {
+		// In a tight list, paragraph content is rendered directly without <p> tags.
+		if node.children.len > 0 {
+			r.render_children(node)
+		} else {
+			r.render_inline(node.literal)
+		}
+		return
+	}
+	r.sb.write_string('<p>')
+	if node.children.len > 0 {
+		r.render_children(node)
+	} else {
+		r.render_inline(node.literal)
+	}
+	r.sb.write_string('</p>\n')
+}
+
+fn (mut r HTMLRenderer) render_blockquote(node &Node) {
+	r.sb.write_string('<blockquote>\n')
+	r.render_children(node)
+	r.sb.write_string('</blockquote>\n')
+}
+
+fn (mut r HTMLRenderer) render_list(node &Node) {
+	tag := if node.is_ordered { 'ol' } else { 'ul' }
+	if node.is_ordered && node.list_start != 1 {
+		r.sb.write_string('<${tag} start="${node.list_start}">\n')
+	} else {
+		r.sb.write_string('<${tag}>\n')
+	}
+	prev_tight := r.tight_list
+	r.tight_list = node.is_tight
+	r.render_children(node)
+	r.tight_list = prev_tight
+	r.sb.write_string('</${tag}>\n')
+}
+
+fn (mut r HTMLRenderer) render_list_item(node &Node) {
+	// Check if this is a task list item (first child is task_checkbox).
+	if r.opts.task_list && node.children.len > 0 && node.children[0].kind == .task_checkbox {
+		chk := node.children[0]
+		checked_attr := if chk.checked { ' checked=""' } else { '' }
+		if r.opts.renderer_opts.xhtml {
+			r.sb.write_string('<li><input type="checkbox" disabled=""${checked_attr} /> ')
+		} else {
+			r.sb.write_string('<li><input type="checkbox" disabled=""${checked_attr}> ')
+		}
+		for i := 1; i < node.children.len; i++ {
+			r.render_node(node.children[i])
+		}
+		r.sb.write_string('</li>\n')
+		return
+	}
+	r.sb.write_string('<li>')
+	r.render_children(node)
+	r.sb.write_string('</li>\n')
+}
+
+fn (mut r HTMLRenderer) render_code_block(node &Node) {
+	r.sb.write_string('<pre><code>')
+	r.sb.write_string(html_escape(node.literal))
+	r.sb.write_string('</code></pre>\n')
+}
+
+fn (mut r HTMLRenderer) render_fenced_code(node &Node) {
+	if node.fence_info.len > 0 {
+		// Use only the first word of the info string as the language class.
+		lang := node.fence_info.split(' ')[0].split('\t')[0]
+		r.sb.write_string('<pre><code class="language-${html_escape(lang)}">')
+	} else {
+		r.sb.write_string('<pre><code>')
+	}
+	r.sb.write_string(html_escape(node.literal))
+	r.sb.write_string('</code></pre>\n')
+}
+
+fn (mut r HTMLRenderer) render_thematic_break() {
+	if r.opts.renderer_opts.xhtml {
+		r.sb.write_string('<hr />\n')
+	} else {
+		r.sb.write_string('<hr>\n')
+	}
+}
+
+fn (mut r HTMLRenderer) render_html_block(node &Node) {
+	if r.opts.renderer_opts.unsafe_ {
+		r.sb.write_string(node.literal)
+	} else {
+		r.sb.write_string('<!-- raw HTML omitted -->\n')
+	}
+}
+
+// ---- Table ----
+
+fn (mut r HTMLRenderer) render_table(node &Node) {
+	r.sb.write_string('<table>\n')
+	r.render_children(node)
+	r.sb.write_string('</table>\n')
+}
+
+fn (mut r HTMLRenderer) render_table_section(node &Node, tag string) {
+	prev_in_table_head := r.in_table_head
+	r.in_table_head = tag == 'thead'
+	r.sb.write_string('<${tag}>\n')
+	r.render_children(node)
+	r.sb.write_string('</${tag}>\n')
+	r.in_table_head = prev_in_table_head
+}
+
+fn (mut r HTMLRenderer) render_table_row(node &Node) {
+	// Determine cell tag based on parent kind (table_head uses th).
+	// We pass the context via a field or inspect the row context.
+	// Since we don't have parent pointer, check if this is a header row via the
+	// node's parent tracking. We'll check node.children[0].align as a proxy.
+	// Instead, use a simple flag: if any sibling is a table_head, use <th>.
+	// For simplicity, we use <td> always and let render_table_cell decide.
+	r.sb.write_string('<tr>\n')
+	r.render_children(node)
+	r.sb.write_string('</tr>\n')
+}
+
+fn (mut r HTMLRenderer) render_table_cell(node &Node) {
+	// We use a flag in the renderer to know if we're in the head.
+	// Simple approach: the cell tag is set by the surrounding context.
+	// We'll use <td> and trust the renderer state.
+	align_attr := match node.align {
+		.left { ' align="left"' }
+		.center { ' align="center"' }
+		.right { ' align="right"' }
+		else { '' }
+	}
+
+	cell_tag := if r.in_table_head { 'th' } else { 'td' }
+	r.sb.write_string('<${cell_tag}${align_attr}>')
+	r.render_inline(node.literal)
+	r.sb.write_string('</${cell_tag}>\n')
+}
+
+// ---- Definition list ----
+
+fn (mut r HTMLRenderer) render_definition_list(node &Node) {
+	r.sb.write_string('<dl>\n')
+	r.render_children(node)
+	r.sb.write_string('</dl>\n')
+}
+
+fn (mut r HTMLRenderer) render_definition_term(node &Node) {
+	r.sb.write_string('<dt>')
+	r.render_inline(node.literal)
+	r.sb.write_string('</dt>\n')
+	for child in node.children {
+		r.render_node(child)
+	}
+}
+
+fn (mut r HTMLRenderer) render_definition_desc(node &Node) {
+	r.sb.write_string('<dd>')
+	r.render_inline(node.literal)
+	r.sb.write_string('</dd>\n')
+}
+
+// ---- Footnotes ----
+
+fn (mut r HTMLRenderer) render_footnote_ref(node &Node) {
+	label := node.fn_label
+	// Assign an ordinal on first encounter.
+	mut idx := 0
+	for i, l in r.fn_order {
+		if l == label {
+			idx = i + 1
+			break
+		}
+	}
+	if idx == 0 {
+		r.fn_order << label
+		idx = r.fn_order.len
+	}
+	r.sb.write_string('<sup><a href="#fn-${html_escape(label)}" id="fnref-${html_escape(label)}">${idx}</a></sup>')
+}
+
+fn (mut r HTMLRenderer) render_footnotes_section() {
+	r.sb.write_string('<section class="footnotes">\n<ol>\n')
+	for label in r.fn_order {
+		fn_node := r.fn_nodes[label] or { continue }
+		r.sb.write_string('<li id="fn-${html_escape(label)}">')
+		r.render_inline(fn_node.literal)
+		r.sb.write_string(' <a href="#fnref-${html_escape(label)}">&#x21A9;</a></li>\n')
+	}
+	r.sb.write_string('</ol>\n</section>\n')
+}
+
+// ---- Inline elements ----
+
+fn (mut r HTMLRenderer) render_text(node &Node) {
+	content := if r.opts.typographer {
+		smart_punctuate(node.literal)
+	} else {
+		node.literal
+	}
+	r.sb.write_string(html_escape(content))
+}
+
+fn (mut r HTMLRenderer) render_emphasis(node &Node) {
+	r.sb.write_string('<em>')
+	r.render_children(node)
+	r.sb.write_string('</em>')
+}
+
+fn (mut r HTMLRenderer) render_strong(node &Node) {
+	r.sb.write_string('<strong>')
+	r.render_children(node)
+	r.sb.write_string('</strong>')
+}
+
+fn (mut r HTMLRenderer) render_code_span(node &Node) {
+	r.sb.write_string('<code>')
+	r.sb.write_string(html_escape(node.literal))
+	r.sb.write_string('</code>')
+}
+
+fn (mut r HTMLRenderer) render_link(node &Node) {
+	r.sb.write_string('<a href="${html_escape(url_encode(node.dest))}"')
+	if node.title.len > 0 {
+		r.sb.write_string(' title="${html_escape(node.title)}"')
+	}
+	r.sb.write_string('>')
+	r.render_children(node)
+	r.sb.write_string('</a>')
+}
+
+fn (mut r HTMLRenderer) render_image(node &Node) {
+	alt := node.text_content()
+	r.sb.write_string('<img src="${html_escape(url_encode(node.dest))}" alt="${html_escape(alt)}"')
+	if node.title.len > 0 {
+		r.sb.write_string(' title="${html_escape(node.title)}"')
+	}
+	if r.opts.renderer_opts.xhtml {
+		r.sb.write_string(' />')
+	} else {
+		r.sb.write_string('>')
+	}
+}
+
+fn (mut r HTMLRenderer) render_autolink(node &Node) {
+	r.sb.write_string('<a href="${html_escape(url_encode(node.dest))}">')
+	r.sb.write_string(html_escape(node.literal))
+	r.sb.write_string('</a>')
+}
+
+fn (mut r HTMLRenderer) render_raw_html(node &Node) {
+	if r.opts.renderer_opts.unsafe_ {
+		r.sb.write_string(node.literal)
+	} else {
+		r.sb.write_string('<!-- raw HTML omitted -->')
+	}
+}
+
+fn (mut r HTMLRenderer) render_hard_break() {
+	if r.opts.renderer_opts.xhtml {
+		r.sb.write_string('<br />\n')
+	} else {
+		r.sb.write_string('<br>\n')
+	}
+}
+
+fn (mut r HTMLRenderer) render_soft_break() {
+	if r.opts.renderer_opts.hard_wraps {
+		if r.opts.renderer_opts.xhtml {
+			r.sb.write_string('<br />\n')
+		} else {
+			r.sb.write_string('<br>\n')
+		}
+	} else {
+		r.sb.write_string('\n')
+	}
+}
+
+fn (mut r HTMLRenderer) render_strikethrough(node &Node) {
+	r.sb.write_string('<del>')
+	r.render_children(node)
+	r.sb.write_string('</del>')
+}
+
+fn (mut r HTMLRenderer) render_task_checkbox(node &Node) {
+	// Rendered inline in render_list_item; standalone fallback:
+	checked := if node.checked { ' checked=""' } else { '' }
+	if r.opts.renderer_opts.xhtml {
+		r.sb.write_string('<input type="checkbox" disabled=""${checked} />')
+	} else {
+		r.sb.write_string('<input type="checkbox" disabled=""${checked}>')
+	}
+}
diff --git a/vlib/x/markdown/inline.v b/vlib/x/markdown/inline.v
new file mode 100644
index 000000000..1b3ad44a9
--- /dev/null
+++ b/vlib/x/markdown/inline.v
@@ -0,0 +1,877 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+module markdown
+
+import encoding.html as ehtml
+
+// parse_inline parses src as inline content and returns a slice of inline nodes.
+pub fn parse_inline(src string, opts Options, ref_map map[string]LinkRef) []&Node {
+	mut p := InlineParser{
+		src:     src
+		opts:    opts
+		ref_map: ref_map
+	}
+	return p.parse()
+}
+
+// InlineParser parses inline markdown content.
+struct InlineParser {
+	opts    Options
+	ref_map map[string]LinkRef
+mut:
+	src string
+	pos int
+}
+
+struct EmphDelim {
+mut:
+	node_idx  int
+	ch        u8
+	length    int
+	orig_len  int
+	can_open  bool
+	can_close bool
+	active    bool = true
+}
+
+// parse parses the full inline source and returns a node slice.
+fn (mut p InlineParser) parse() []&Node {
+	mut result := []&Node{}
+	mut delims := []EmphDelim{}
+	for p.pos < p.src.len {
+		if p.src[p.pos] == `*` || p.src[p.pos] == `_` {
+			start := p.pos
+			ch := p.src[p.pos]
+			for p.pos < p.src.len && p.src[p.pos] == ch {
+				p.pos++
+			}
+			run := p.src[start..p.pos]
+			before := if start > 0 { p.src[start - 1] } else { u8(` `) }
+			after := if p.pos < p.src.len { p.src[p.pos] } else { u8(` `) }
+			can_open := can_open_emphasis(ch, before, after)
+			can_close := can_close_emphasis(ch, before, after)
+			result << text_node(run)
+			if can_open || can_close {
+				delims << EmphDelim{
+					node_idx:  result.len - 1
+					ch:        ch
+					length:    run.len
+					orig_len:  run.len
+					can_open:  can_open
+					can_close: can_close
+				}
+			}
+			continue
+		}
+		nodes := p.parse_one()
+		for n in nodes {
+			result << n
+		}
+	}
+	if delims.len > 0 {
+		resolve_emphasis(mut result, mut delims)
+		result = compact_empty_text_nodes(result)
+	}
+	return merge_text_nodes(result)
+}
+
+fn resolve_emphasis(mut nodes []&Node, mut delims []EmphDelim) {
+	mut i := 0
+	for i < delims.len {
+		if !delims[i].active || !delims[i].can_close || delims[i].length == 0 {
+			i++
+			continue
+		}
+		mut opener := i - 1
+		for opener >= 0 {
+			if !delims[opener].active || !delims[opener].can_open || delims[opener].length == 0 {
+				opener--
+				continue
+			}
+			if delims[opener].ch != delims[i].ch {
+				opener--
+				continue
+			}
+			if (delims[i].can_open || delims[opener].can_close)
+				&& (delims[opener].orig_len + delims[i].orig_len) % 3 == 0
+				&& (delims[opener].orig_len % 3 != 0 || delims[i].orig_len % 3 != 0) {
+				opener--
+				continue
+			}
+			if delims[opener].node_idx + 1 >= delims[i].node_idx {
+				opener--
+				continue
+			}
+			break
+		}
+		if opener < 0 {
+			i++
+			continue
+		}
+
+		use_len := if delims[opener].length >= 2 && delims[i].length >= 2 { 2 } else { 1 }
+		opener_idx := delims[opener].node_idx
+		closer_idx := delims[i].node_idx
+		if opener_idx < 0 || closer_idx < 0 || opener_idx >= nodes.len || closer_idx >= nodes.len
+			|| opener_idx >= closer_idx {
+			delims[i].active = false
+			i++
+			continue
+		}
+		if nodes[opener_idx].literal.len < use_len || nodes[closer_idx].literal.len < use_len {
+			delims[i].active = false
+			i++
+			continue
+		}
+
+		nodes[opener_idx].literal = nodes[opener_idx].literal[..nodes[opener_idx].literal.len - use_len]
+		nodes[closer_idx].literal = nodes[closer_idx].literal[use_len..]
+		delims[opener].length -= use_len
+		delims[i].length -= use_len
+
+		mut emph := new_node(if use_len == 2 { .strong } else { .emphasis })
+		for child in nodes[opener_idx + 1..closer_idx] {
+			emph.append_child(child)
+		}
+
+		n_inner := closer_idx - opener_idx - 1
+		if n_inner > 0 {
+			nodes.delete_many(opener_idx + 1, n_inner)
+			nodes.insert(opener_idx + 1, emph)
+		}
+
+		mut delta := n_inner - 1
+		if delta < 0 {
+			delta = 0
+		}
+		for j := 0; j < delims.len; j++ {
+			if !delims[j].active {
+				continue
+			}
+			if delims[j].node_idx > opener_idx && delims[j].node_idx < closer_idx {
+				delims[j].active = false
+				continue
+			}
+			if delta > 0 && delims[j].node_idx >= closer_idx {
+				delims[j].node_idx -= delta
+			}
+		}
+
+		if delims[opener].length == 0 {
+			delims[opener].can_open = false
+		}
+		if delims[i].length == 0 {
+			delims[i].can_close = false
+		}
+		i = opener + 1
+	}
+}
+
+fn compact_empty_text_nodes(nodes []&Node) []&Node {
+	mut out := []&Node{}
+	for n in nodes {
+		if n.kind == .text && n.literal.len == 0 {
+			continue
+		}
+		out << n
+	}
+	return out
+}
+
+// parse_one parses one or more inline elements at the current position.
+fn (mut p InlineParser) parse_one() []&Node {
+	if p.pos >= p.src.len {
+		return []
+	}
+	c := p.src[p.pos]
+	match c {
+		`\\` {
+			return [p.parse_backslash()]
+		}
+		96 { // backtick
+			if node := p.try_code_span() {
+				return [node]
+			}
+			p.pos++
+			return [text_node('`')]
+		}
+		`*`, `_` {
+			p.pos++
+			return [text_node(c.ascii_str())]
+		}
+		`~` {
+			if p.opts.strikethrough {
+				if node := p.try_strikethrough() {
+					return [node]
+				}
+			}
+			p.pos++
+			return [text_node('~')]
+		}
+		`[` {
+			if nodes := p.try_link_or_footnote() {
+				return nodes
+			}
+			p.pos++
+			return [text_node('[')]
+		}
+		`!` {
+			if p.pos + 1 < p.src.len && p.src[p.pos + 1] == `[` {
+				saved := p.pos
+				p.pos += 2
+				if nodes := p.try_image_after_bang() {
+					return nodes
+				}
+				p.pos = saved
+				p.pos++
+				return [text_node('!')]
+			}
+			p.pos++
+			return [text_node('!')]
+		}
+		`<` {
+			if node := p.try_autolink_or_html() {
+				return [node]
+			}
+			p.pos++
+			return [text_node('<')]
+		}
+		`&` {
+			if node := p.try_entity() {
+				return [node]
+			}
+			p.pos++
+			return [text_node('&')]
+		}
+		`\n` {
+			return [p.parse_newline()]
+		}
+		else {
+			if p.opts.linkify {
+				if node := p.try_linkify() {
+					return [node]
+				}
+			}
+			p.pos++
+			return [text_node(c.ascii_str())]
+		}
+	}
+}
+
+// text_node creates a text node with the given literal string.
+fn text_node(s string) &Node {
+	mut n := new_node(.text)
+	n.literal = s
+	return n
+}
+
+// merge_text_nodes merges consecutive text nodes into one.
+fn merge_text_nodes(nodes []&Node) []&Node {
+	if nodes.len <= 1 {
+		return nodes
+	}
+	mut result := []&Node{}
+	for node in nodes {
+		if result.len > 0 && result[result.len - 1].kind == .text && node.kind == .text {
+			result[result.len - 1].literal += node.literal
+		} else {
+			result << node
+		}
+	}
+	return result
+}
+
+// can_open_emphasis reports whether a delimiter run can open emphasis.
+fn can_open_emphasis(delim u8, before u8, after u8) bool {
+	left_flanking := !is_unicode_space(after) && (!is_ascii_punct(after) || is_unicode_space(before)
+		|| is_ascii_punct(before))
+	right_flanking := !is_unicode_space(before)
+		&& (!is_ascii_punct(before) || is_unicode_space(after)
+		|| is_ascii_punct(after))
+	if delim == `*` {
+		return left_flanking
+	}
+	if delim == `_` {
+		return left_flanking && (!right_flanking || is_ascii_punct(before))
+	}
+	return false
+}
+
+// can_close_emphasis reports whether a delimiter run can close emphasis.
+fn can_close_emphasis(delim u8, before u8, after u8) bool {
+	left_flanking := !is_unicode_space(after) && (!is_ascii_punct(after) || is_unicode_space(before)
+		|| is_ascii_punct(before))
+	right_flanking := !is_unicode_space(before)
+		&& (!is_ascii_punct(before) || is_unicode_space(after)
+		|| is_ascii_punct(after))
+	if delim == `*` {
+		return right_flanking
+	}
+	if delim == `_` {
+		return right_flanking && (!left_flanking || is_ascii_punct(after))
+	}
+	return false
+}
+
+// parse_backslash handles backslash escapes and hard line breaks.
+fn (mut p InlineParser) parse_backslash() &Node {
+	p.pos++ // consume '\'
+	if p.pos >= p.src.len {
+		return text_node('\\')
+	}
+	ch := p.src[p.pos]
+	if ch == `\n` {
+		p.pos++
+		return new_node(.hard_break)
+	}
+	if is_ascii_punct(ch) {
+		p.pos++
+		return text_node(ch.ascii_str())
+	}
+	return text_node('\\')
+}
+
+// try_code_span attempts to parse a backtick code span.
+fn (mut p InlineParser) try_code_span() ?&Node {
+	start := p.pos
+	mut n := 0
+	for p.pos < p.src.len && p.src[p.pos] == 96 {
+		n++
+		p.pos++
+	}
+	content_start := p.pos
+	mut search := content_start
+	for search < p.src.len {
+		if p.src[search] == 96 {
+			close_start := search
+			mut close_n := 0
+			for search < p.src.len && p.src[search] == 96 {
+				close_n++
+				search++
+			}
+			if close_n == n {
+				code_raw := p.src[content_start..close_start]
+				mut code := code_raw.replace('\n', ' ')
+				if code.len >= 2 && code[0] == ` ` && code[code.len - 1] == ` `
+					&& code.trim_space().len > 0 {
+					code = code[1..code.len - 1]
+				}
+				mut node := new_node(.code_span)
+				node.literal = code
+				p.pos = search
+				return node
+			}
+		} else {
+			search++
+		}
+	}
+	p.pos = start
+	return none
+}
+
+// try_emphasis attempts to parse *em*, **strong**, _em_, __strong__.
+fn (mut p InlineParser) try_emphasis(c u8) ?&Node {
+	start := p.pos
+	mut run := 0
+	for p.pos < p.src.len && p.src[p.pos] == c {
+		run++
+		p.pos++
+	}
+
+	// Prevent splitting an intraword __ run into a synthetic single-underscore opener.
+	if c == `_` && run == 1 && start > 1 && p.src[start - 1] == `_` {
+		before2 := p.src[start - 2]
+		after1 := if start + run < p.src.len { p.src[start + run] } else { u8(` `) }
+		if is_wordish(before2) && is_wordish(after1) {
+			p.pos = start
+			return none
+		}
+	}
+
+	before := if start > 0 { p.src[start - 1] } else { u8(` `) }
+	after := if start + run < p.src.len { p.src[start + run] } else { u8(` `) }
+	opener_can_open := can_open_emphasis(c, before, after)
+	opener_can_close := can_close_emphasis(c, before, after)
+
+	if !opener_can_open {
+		p.pos = start
+		return none
+	}
+
+	// Prefer em first for odd runs (e.g. ***foo*** -> <em><strong>foo</strong></em>).
+	if run % 2 == 1 {
+		p.pos = start + 1
+		if node := p.match_close_delim(c, 1, run, opener_can_close) {
+			return node
+		}
+		if run >= 2 {
+			p.pos = start + 2
+			if node := p.match_close_delim(c, 2, run, opener_can_close) {
+				return node
+			}
+		}
+	} else {
+		if run >= 2 {
+			p.pos = start + 2
+			if node := p.match_close_delim(c, 2, run, opener_can_close) {
+				return node
+			}
+		}
+		p.pos = start + 1
+		if node := p.match_close_delim(c, 1, run, opener_can_close) {
+			return node
+		}
+	}
+
+	p.pos = start
+	return none
+}
+
+// is_wordish reports whether c behaves like a word character for emphasis
+// boundary checks (includes non-ASCII bytes used in UTF-8 sequences).
+@[inline]
+fn is_wordish(c u8) bool {
+	return !is_unicode_space(c) && !is_ascii_punct(c)
+}
+
+// match_close_delim parses content after the opening delimiter run and finds
+// a matching closing delimiter of exactly `count` characters.
+fn (mut p InlineParser) match_close_delim(c u8, count int, opener_run int, opener_can_close bool) ?&Node {
+	content_start := p.pos
+	mut content_nodes := []&Node{}
+
+	for p.pos < p.src.len {
+		loop_start_pos := p.pos
+		ch := p.src[p.pos]
+		// Check for closing delimiter.
+		if ch == c {
+			close_pos := p.pos
+			mut close_run := 0
+			for p.pos < p.src.len && p.src[p.pos] == c {
+				close_run++
+				p.pos++
+			}
+			if close_run >= count {
+				// Verify right-flanking.
+				before_close := if close_pos > 0 { p.src[close_pos - 1] } else { u8(` `) }
+				after_close := if p.pos < p.src.len { p.src[p.pos] } else { u8(` `) }
+				closer_can_close := can_close_emphasis(c, before_close, after_close)
+				closer_can_open := can_open_emphasis(c, before_close, after_close)
+				if closer_can_close {
+					if count == 1 && opener_run == 1 && close_run > 1 && closer_can_open {
+						p.pos = close_pos
+					} else if count == 1 && opener_run > 1 && close_run > 1 && closer_can_open {
+						// Keep extra delimiters inside the emphasis span so nested
+						// strong parsing can consume them (e.g. foo***bar***baz).
+						inner_end := close_pos + (close_run - count)
+						if inner_end > content_start && inner_end <= p.src.len {
+							inner_nodes := parse_inline(p.src[content_start..inner_end], p.opts,
+								p.ref_map)
+							mut node := new_node(.emphasis)
+							for child in inner_nodes {
+								node.append_child(child)
+							}
+							p.pos = close_pos + close_run
+							return node
+						}
+					} else {
+						if opener_can_close && closer_can_open && (opener_run + close_run) % 3 == 0
+							&& (opener_run % 3 != 0 || close_run % 3 != 0) {
+							p.pos = close_pos
+						} else {
+							if content_nodes.len == 0 {
+								content_nodes << text_node(c.ascii_str())
+								p.pos = close_pos + 1
+								continue
+							}
+							// Rewind extra closing chars beyond `count`.
+							p.pos = close_pos + count
+							kind := if count == 2 { NodeKind.strong } else { NodeKind.emphasis }
+							mut node := new_node(kind)
+							for child in content_nodes {
+								node.append_child(child)
+							}
+							return node
+						}
+					}
+				}
+			}
+			p.pos = close_pos
+			if count == 1 && opener_run > 1 && opener_can_close {
+				content_nodes << text_node(c.ascii_str())
+				p.pos++
+				continue
+			}
+		}
+		if ch == `\n` {
+			// Newlines stop emphasis search.
+			break
+		}
+		inner := p.parse_one()
+		if p.pos <= loop_start_pos {
+			// Safety net: force progress to avoid recursive delimiter stalls.
+			content_nodes << text_node(p.src[loop_start_pos].ascii_str())
+			p.pos = loop_start_pos + 1
+			continue
+		}
+		content_nodes << inner
+	}
+	// Not found; reset.
+	p.pos = content_start
+	return none
+}
+
+// try_strikethrough parses ~~text~~.
+fn (mut p InlineParser) try_strikethrough() ?&Node {
+	if p.pos + 1 >= p.src.len || p.src[p.pos + 1] != `~` {
+		return none
+	}
+	p.pos += 2
+	close := p.src.index_after_('~~', p.pos)
+	if close < 0 {
+		p.pos -= 2
+		return none
+	}
+	inner := p.src[p.pos..close]
+	inner_nodes := parse_inline(inner, p.opts, p.ref_map)
+	mut node := new_node(.strikethrough)
+	for child in inner_nodes {
+		node.append_child(child)
+	}
+	p.pos = close + 2
+	return node
+}
+
+// try_link_or_footnote handles [ and attempts to parse a link or footnote ref.
+fn (mut p InlineParser) try_link_or_footnote() ?[]&Node {
+	saved := p.pos
+	p.pos++ // consume '['
+	// Footnote reference [^label].
+	if p.opts.footnotes && p.pos < p.src.len && p.src[p.pos] == `^` {
+		fn_start := p.pos + 1
+		fn_close := p.src.index_after_(']', fn_start)
+		if fn_close > fn_start {
+			label := p.src[fn_start..fn_close]
+			mut fn_ref := new_node(.footnote_ref)
+			fn_ref.fn_label = label
+			p.pos = fn_close + 1
+			return [fn_ref]
+		}
+	}
+	text_start := p.pos
+	close := find_bracket_close(p.src, p.pos)
+	if close < 0 {
+		p.pos = saved
+		return none
+	}
+	link_text := p.src[text_start..close]
+	p.pos = close + 1
+
+	// Inline link (url).
+	if p.pos < p.src.len && p.src[p.pos] == `(` {
+		dest, title, end := parse_inline_link_dest_from(p.src, p.pos + 1)
+		if end >= 0 {
+			inner_nodes := parse_inline(link_text, p.opts, p.ref_map)
+			mut node := new_node(.link)
+			node.dest = unescape_string(dest)
+			node.title = unescape_string(title)
+			for child in inner_nodes {
+				node.append_child(child)
+			}
+			p.pos = end + 1
+			return [node]
+		}
+	}
+	// Full reference [text][label].
+	if p.pos < p.src.len && p.src[p.pos] == `[` {
+		ref_start := p.pos + 1
+		ref_close := p.src.index_after_(']', ref_start)
+		if ref_close >= 0 {
+			raw_label := p.src[ref_start..ref_close]
+			label := normalize_label(if raw_label.len > 0 { raw_label } else { link_text })
+			if label in p.ref_map {
+				ref := p.ref_map[label]
+				mut node := new_node(.link)
+				node.dest = ref.dest
+				node.title = ref.title
+				node.label = label
+				inner_nodes := parse_inline(link_text, p.opts, p.ref_map)
+				for child in inner_nodes {
+					node.append_child(child)
+				}
+				p.pos = ref_close + 1
+				return [node]
+			}
+			if raw_label.len > 0 {
+				// Do not downgrade explicit [text][label] to shortcut [text].
+				p.pos = saved
+				return none
+			}
+		}
+	}
+	// Shortcut reference [label].
+	label := normalize_label(link_text)
+	if label in p.ref_map {
+		ref := p.ref_map[label]
+		mut node := new_node(.link)
+		node.dest = ref.dest
+		node.title = ref.title
+		node.label = label
+		inner_nodes := parse_inline(link_text, p.opts, p.ref_map)
+		for child in inner_nodes {
+			node.append_child(child)
+		}
+		return [node]
+	}
+	p.pos = saved
+	return none
+}
+
+// try_image_after_bang parses the [alt](url) part of an image after '![' was consumed.
+fn (mut p InlineParser) try_image_after_bang() ?[]&Node {
+	text_start := p.pos
+	close := find_bracket_close(p.src, p.pos)
+	if close < 0 {
+		return none
+	}
+	alt_text := p.src[text_start..close]
+	p.pos = close + 1
+
+	if p.pos < p.src.len && p.src[p.pos] == `(` {
+		dest, title, end := parse_inline_link_dest_from(p.src, p.pos + 1)
+		if end >= 0 {
+			mut node := new_node(.image)
+			node.dest = unescape_string(dest)
+			node.title = unescape_string(title)
+			inner_nodes := parse_inline(alt_text, p.opts, p.ref_map)
+			for child in inner_nodes {
+				node.append_child(child)
+			}
+			p.pos = end + 1
+			return [node]
+		}
+	}
+	if p.pos < p.src.len && p.src[p.pos] == `[` {
+		ref_start := p.pos + 1
+		ref_close := p.src.index_after_(']', ref_start)
+		if ref_close >= 0 {
+			raw_label := p.src[ref_start..ref_close]
+			label := normalize_label(if raw_label.len > 0 { raw_label } else { alt_text })
+			if label in p.ref_map {
+				ref := p.ref_map[label]
+				mut node := new_node(.image)
+				node.dest = ref.dest
+				node.title = ref.title
+				inner_nodes := parse_inline(alt_text, p.opts, p.ref_map)
+				for child in inner_nodes {
+					node.append_child(child)
+				}
+				p.pos = ref_close + 1
+				return [node]
+			}
+		}
+	}
+	return none
+}
+
+// find_bracket_close finds the ] matching the [ at start, handling nesting and escapes.
+fn find_bracket_close(s string, start int) int {
+	mut depth := 1
+	mut i := start
+	for i < s.len {
+		if s[i] == `\\` && i + 1 < s.len {
+			i += 2
+			continue
+		}
+		if s[i] == `[` {
+			depth++
+		} else if s[i] == `]` {
+			depth--
+			if depth == 0 {
+				return i
+			}
+		}
+		i++
+	}
+	return -1
+}
+
+// parse_inline_link_dest_from parses (url) or (url "title") starting at s[start]
+// (start is after the opening paren). Returns (dest, title, end_paren_pos) or ("","", -1).
+fn parse_inline_link_dest_from(s string, start int) (string, string, int) {
+	i := skip_ws(s, start)
+	if i >= s.len {
+		return '', '', -1
+	}
+	dest, after_dest := parse_link_dest(s[i..])
+	j := i + (s[i..].len - after_dest.len)
+	k := skip_ws(s, j)
+	if k < s.len && s[k] == `)` {
+		return dest, '', k
+	}
+	title, after_title := parse_link_title(s[k..])
+	l := k + (s[k..].len - after_title.len)
+	m := skip_ws(s, l)
+	if m < s.len && s[m] == `)` {
+		return dest, title, m
+	}
+	return '', '', -1
+}
+
+// skip_ws returns the position in s after skipping whitespace from start.
+fn skip_ws(s string, start int) int {
+	mut i := start
+	for i < s.len && (s[i] == ` ` || s[i] == `\t` || s[i] == `\n`) {
+		i++
+	}
+	return i
+}
+
+// try_autolink_or_html handles <...> for autolinks and raw HTML.
+fn (mut p InlineParser) try_autolink_or_html() ?&Node {
+	rest := p.src[p.pos..]
+	auto_end := try_autolink(rest)
+	if auto_end >= 0 {
+		content := rest[1..auto_end]
+		mut node := new_node(.autolink)
+		node.literal = content
+		if content.contains('@') && !content.contains('://') {
+			node.dest = 'mailto:' + content
+		} else {
+			node.dest = content
+		}
+		p.pos += auto_end + 1
+		return node
+	}
+	raw_end := try_raw_html_tag(rest)
+	if raw_end >= 0 {
+		mut node := new_node(.raw_html)
+		node.literal = rest[..raw_end + 1]
+		p.pos += raw_end + 1
+		return node
+	}
+	return none
+}
+
+// try_autolink matches an <autolink> returning the position of '>' or -1.
+fn try_autolink(s string) int {
+	if s.len < 3 || s[0] != `<` {
+		return -1
+	}
+	end := s.index_after_('>', 1)
+	if end < 0 {
+		return -1
+	}
+	inner := s[1..end]
+	if inner.contains(' ') || inner.contains('<') {
+		return -1
+	}
+	if inner.contains('://') {
+		return end
+	}
+	if inner.contains('@') && !inner.starts_with('@') {
+		return end
+	}
+	return -1
+}
+
+// try_raw_html_tag matches a raw HTML tag starting with '<' and returns the '>' position.
+fn try_raw_html_tag(s string) int {
+	if s.len < 3 || s[0] != `<` {
+		return -1
+	}
+	if s.starts_with('<!--') {
+		end := s.index_after_('-->', 4)
+		if end >= 0 {
+			return end + 2
+		}
+		return -1
+	}
+	if s.starts_with('<?') {
+		end := s.index_after_('?>', 2)
+		if end >= 0 {
+			return end + 1
+		}
+		return -1
+	}
+	low := s.to_lower()
+	if low.starts_with('<![cdata[') {
+		end := s.index_after_(']]>', 9)
+		if end >= 0 {
+			return end + 2
+		}
+		return -1
+	}
+	end := s.index_after_('>', 1)
+	if end < 0 {
+		return -1
+	}
+	inner := s[1..end]
+	if inner.len == 0 {
+		return -1
+	}
+	if !is_alpha(inner[0]) && inner[0] != `/` && inner[0] != `!` {
+		return -1
+	}
+	return end
+}
+
+// try_entity parses an HTML entity reference &name; or &#n; or &#xn'
+fn (mut p InlineParser) try_entity() ?&Node {
+	rest := p.src[p.pos..]
+	semi := rest.index(';') or { return none }
+	if semi > 32 || semi < 2 {
+		return none
+	}
+	candidate := rest[..semi + 1]
+	decoded := ehtml.unescape(candidate, all: true)
+	if decoded == candidate {
+		return none
+	}
+	p.pos += semi + 1
+	return text_node(decoded)
+}
+
+// parse_newline handles a newline character.
+fn (mut p InlineParser) parse_newline() &Node {
+	// Hard break if preceded by two or more spaces.
+	if p.pos >= 2 && p.src[p.pos - 1] == ` ` && p.src[p.pos - 2] == ` ` {
+		p.pos++
+		return new_node(.hard_break)
+	}
+	p.pos++
+	return new_node(.soft_break)
+}
+
+// try_linkify matches a bare URL (linkify extension).
+fn (mut p InlineParser) try_linkify() ?&Node {
+	rest := p.src[p.pos..]
+	for _, scheme in ['https://', 'http://', 'ftp://', 'mailto:'] {
+		if rest.starts_with(scheme) {
+			mut end := scheme.len
+			for end < rest.len {
+				ch := rest[end]
+				if ch == ` ` || ch == `<` || ch == `>` || ch == `"` || ch == `\n` || ch == `\t` {
+					break
+				}
+				end++
+			}
+			for end > scheme.len {
+				last := rest[end - 1]
+				if last == `.` || last == `,` || last == `;` || last == `!` || last == `?` {
+					end--
+				} else {
+					break
+				}
+			}
+			url := rest[..end]
+			mut node := new_node(.autolink)
+			node.literal = url
+			node.dest = url
+			p.pos += end
+			return node
+		}
+	}
+	return none
+}
diff --git a/vlib/x/markdown/markdown.v b/vlib/x/markdown/markdown.v
new file mode 100644
index 000000000..a8a5f4ba5
--- /dev/null
+++ b/vlib/x/markdown/markdown.v
@@ -0,0 +1,142 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+//
+// Module markdown provides CommonMark-compliant markdown parsing and HTML
+// rendering with support for GitHub Flavored Markdown and additional
+// extensions. It is designed for feature parity with github.com/yuin/goldmark.
+//
+// Basic usage:
+//
+//     import x.markdown
+//
+//     html := markdown.to_html('# Hello\n\nWorld')
+//
+// With GFM extensions:
+//
+//     md := markdown.new(extensions: markdown.gfm())
+//     html := md.convert('| a | b |\n|---|---|\n| 1 | 2 |')
+//
+// With fine-grained options:
+//
+//     md := markdown.new(
+//         extensions: [markdown.Extension(markdown.footnote()), markdown.typographer()],
+//         parser_opts: markdown.ParserOptions{ auto_heading_id: true },
+//         renderer_opts: markdown.RendererOptions{ unsafe_: true, xhtml: true },
+//     )
+//     html := md.convert(source)
+//
+// Parse to AST and walk:
+//
+//     doc := md.parse(source)
+//     doc.walk(fn (node &markdown.Node) bool {
+//         println(node.kind)
+//         return true
+//     })
+module markdown
+
+// ParserOptions configures parser behaviour.
+@[params]
+pub struct ParserOptions {
+pub mut:
+	// auto_heading_id generates an id attribute for every heading node
+	// derived from the heading text content (goldmark WithAutoHeadingID).
+	auto_heading_id bool
+}
+
+// RendererOptions configures HTML renderer behaviour.
+@[params]
+pub struct RendererOptions {
+pub mut:
+	// unsafe_ allows raw HTML from the source to be included in the output.
+	// When false (the default) raw HTML is replaced with an HTML comment.
+	unsafe_ bool
+	// hard_wraps converts every newline inside a paragraph to a <br> tag.
+	hard_wraps bool
+	// xhtml outputs XHTML-style self-closing tags (e.g. <br />).
+	xhtml bool
+}
+
+// Options configures a Markdown processor.
+// Extension flags in the mut section are normally set by calling new() with
+// an extensions slice; they can also be set directly.
+@[params]
+pub struct Options {
+pub mut:
+	// extensions is the list of extensions applied when new() is called.
+	extensions []Extension
+	// parser_opts configures the parser.
+	parser_opts ParserOptions
+	// renderer_opts configures the renderer.
+	renderer_opts RendererOptions
+	// --- feature flags set by extensions ---
+	tables          bool
+	strikethrough   bool
+	linkify         bool
+	task_list       bool
+	footnotes       bool
+	typographer     bool
+	definition_list bool
+}
+
+// LinkRef holds a collected link reference definition (url + optional title).
+struct LinkRef {
+	dest  string
+	title string
+}
+
+// Markdown is the main markdown processor.  Create one with new() and reuse it
+// across multiple convert/parse calls; link reference definitions are cached.
+pub struct Markdown {
+pub mut:
+	opts    Options
+	ref_map map[string]LinkRef
+}
+
+// new creates a Markdown processor with the given options.
+// All extensions in opts.extensions are applied immediately.
+pub fn new(opts Options) Markdown {
+	mut m := Markdown{
+		opts:    opts
+		ref_map: map[string]LinkRef{}
+	}
+	for ext in opts.extensions {
+		ext.extend(mut m)
+	}
+	return m
+}
+
+// to_html converts the markdown source to HTML using default settings
+// (CommonMark only, no extensions, raw HTML stripped).
+pub fn to_html(src string) string {
+	mut md := new(Options{})
+	return md.convert(src)
+}
+
+// to_html_opts converts the markdown source to HTML with the given options.
+pub fn to_html_opts(src string, opts Options) string {
+	mut md := new(opts)
+	return md.convert(src)
+}
+
+// convert parses the markdown source and renders it to an HTML string.
+pub fn (mut m Markdown) convert(src string) string {
+	doc := m.parse(src)
+	mut r := HTMLRenderer{
+		opts:    m.opts
+		ref_map: m.ref_map // Use the updated ref_map after parse()
+	}
+	return r.render(doc)
+}
+
+// parse parses the markdown source into an AST and returns the document root.
+// Link reference definitions collected during parsing are cached so that
+// subsequent parse/convert calls on the same Markdown instance share them.
+pub fn (mut m Markdown) parse(src string) &Node {
+	mut p := new_block_parser(src, m.opts, m.ref_map)
+	doc := p.parse()
+	for k, v in p.ref_map {
+		m.ref_map[k] = v
+	}
+	return doc
+}
diff --git a/vlib/x/markdown/markdown_test.v b/vlib/x/markdown/markdown_test.v
new file mode 100644
index 000000000..6293b3571
--- /dev/null
+++ b/vlib/x/markdown/markdown_test.v
@@ -0,0 +1,343 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+module markdown
+
+fn test_to_html_heading() {
+	assert to_html('# Hello') == '<h1>Hello</h1>\n'
+	assert to_html('## World') == '<h2>World</h2>\n'
+}
+
+fn test_to_html_paragraph() {
+	assert to_html('Hello world') == '<p>Hello world</p>\n'
+}
+
+fn test_to_html_thematic_break() {
+	assert to_html('---') == '<hr>\n'
+}
+
+fn test_to_html_emphasis() {
+	html := to_html('*em*')
+	assert html.contains('<em>')
+}
+
+fn test_to_html_strong() {
+	html := to_html('**bold**')
+	assert html.contains('<strong>')
+}
+
+fn test_to_html_code_span() {
+	html := to_html('`code`')
+	assert html.contains('<code>')
+	assert html.contains('code')
+}
+
+fn test_to_html_link() {
+	html := to_html('[link](https://example.com)')
+	assert html.contains('<a href="https://example.com">')
+	assert html.contains('link')
+}
+
+fn test_html_escape_in_text() {
+	html := to_html('A < B')
+	assert html.contains('&lt;')
+}
+
+fn test_named_entities_are_decoded_before_render() {
+	assert to_html('&copy;') == '<p>©</p>\n'
+	assert to_html('&amp;') == '<p>&amp;</p>\n'
+}
+
+fn test_unknown_named_entity_is_left_as_literal_text() {
+	assert to_html('&not_a_real_entity;') == '<p>&amp;not_a_real_entity;</p>\n'
+}
+
+fn test_numeric_entities_are_decoded() {
+	assert to_html('&#169; &#xA9;') == '<p>© ©</p>\n'
+}
+
+fn test_empty_input() {
+	assert to_html('') == ''
+}
+
+fn test_multiline_paragraph() {
+	html := to_html('line one\nline two')
+	assert html.contains('<p>')
+	assert html.contains('line one')
+}
+
+fn test_fenced_code() {
+	html := to_html('```go\nfn main() {}\n```')
+	assert html.contains('<code')
+	assert html.contains('fn main')
+}
+
+fn test_list() {
+	html := to_html('- item')
+	assert html.contains('<ul>')
+	assert html.contains('<li>')
+	assert html.contains('item')
+}
+
+fn test_ordered_list() {
+	html := to_html('1. first')
+	assert html.contains('<ol>')
+	assert html.contains('<li>')
+	assert html.contains('first')
+}
+
+fn test_ordered_list_marker_requires_whitespace_or_eol() {
+	assert to_html('1.test') == '<p>1.test</p>\n'
+	assert to_html('1)test') == '<p>1)test</p>\n'
+}
+
+fn test_ordered_list_marker_allows_space_tab_or_eol() {
+	assert to_html('1. item') == '<ol>\n<li>item</li>\n</ol>\n'
+	assert to_html('1)\titem') == '<ol>\n<li>item</li>\n</ol>\n'
+	assert to_html('1.') == '<ol>\n<li></li>\n</ol>\n'
+}
+
+fn test_blockquote() {
+	html := to_html('> quote')
+	assert html.contains('<blockquote>')
+	assert html.contains('quote')
+}
+
+fn test_list_multiple_items() {
+	html := to_html('- item 1\n- item 2')
+	assert html.contains('<ul>')
+	assert html.contains('item 1')
+	assert html.contains('item 2')
+}
+
+fn test_invalid_link_ref_def_does_not_create_reference() {
+	src := '[bad]: <https://example.com\n\n[bad]'
+	html := to_html(src)
+	assert !html.contains('<a href=')
+	assert html.contains('[bad]')
+}
+
+fn test_valid_link_ref_def_is_resolved() {
+	src := '[ok]: <https://example.com>\n\n[ok]'
+	html := to_html(src)
+	assert html.contains('<a href="https://example.com">ok</a>')
+}
+
+fn test_full_reference_does_not_fallback_to_shortcut_when_label_is_undefined() {
+	src := '[text]: https://example.com/text\n\n[text][missing]'
+	html := to_html(src)
+	assert html == '<p>[text][missing]</p>\n'
+}
+
+fn test_shortcut_reference_still_resolves_normally() {
+	src := '[text]: https://example.com/text\n\n[text]'
+	html := to_html(src)
+	assert html == '<p><a href="https://example.com/text">text</a></p>\n'
+}
+
+fn test_gfm_table_header_uses_th_cells() {
+	src := '| a | b |\n| --- | --- |\n| 1 | 2 |'
+	html := to_html_opts(src, Options{
+		extensions: gfm()
+	})
+	assert html.contains('<thead>')
+	assert html.contains('<th>a</th>')
+	assert html.contains('<th>b</th>')
+}
+
+fn test_emphasis_underscore_intraword_does_not_emphasize() {
+	assert to_html('foo_bar_baz') == '<p>foo_bar_baz</p>\n'
+	assert to_html('foo_bar_') == '<p>foo_bar_</p>\n'
+	assert to_html('_foo_bar') == '<p>_foo_bar</p>\n'
+}
+
+fn test_emphasis_star_delimiters_still_emphasize() {
+	assert to_html('a*b*c') == '<p>a<em>b</em>c</p>\n'
+}
+
+fn test_emphasis_triple_delimiters() {
+	assert to_html('***foo***') == '<p><em><strong>foo</strong></em></p>\n'
+	assert to_html('___foo___') == '<p><em><strong>foo</strong></em></p>\n'
+	assert to_html('foo***bar***baz') == '<p>foo<em><strong>bar</strong></em>baz</p>\n'
+}
+
+fn test_emphasis_nested_mixed_runs() {
+	assert to_html('**foo *bar***') == '<p><strong>foo <em>bar</em></strong></p>\n'
+	assert to_html('*foo **bar***') == '<p><em>foo <strong>bar</strong></em></p>\n'
+	assert to_html('*foo**bar**baz*') == '<p><em>foo<strong>bar</strong>baz</em></p>\n'
+	assert to_html('*foo **bar** baz*') == '<p><em>foo <strong>bar</strong> baz</em></p>\n'
+	assert to_html('**foo *bar* baz**') == '<p><strong>foo <em>bar</em> baz</strong></p>\n'
+}
+
+fn test_emphasis_multiple_of_three_resolution() {
+	assert to_html('***foo** bar*') == '<p><em><strong>foo</strong> bar</em></p>\n'
+	assert to_html('***foo* bar**') == '<p><strong><em>foo</em> bar</strong></p>\n'
+	assert to_html('***foo**bar*') == '<p><em><strong>foo</strong>bar</em></p>\n'
+}
+
+fn test_emphasis_underscore_punctuation_flanking() {
+	assert to_html('foo-_(bar)_') == '<p>foo-<em>(bar)</em></p>\n'
+	assert to_html('foo__bar__baz') == '<p>foo__bar__baz</p>\n'
+	assert to_html('foo__bar__') == '<p>foo__bar__</p>\n'
+	assert to_html('__foo__bar') == '<p>__foo__bar</p>\n'
+}
+
+fn test_setext_heading_leading_spaces() {
+	// CommonMark allows 0-3 leading spaces on the setext underline.
+	assert to_html('Foo\n   ===') == '<h1>Foo</h1>\n'
+	assert to_html('Foo\n  ---') == '<h2>Foo</h2>\n'
+	assert to_html('Foo\n ===') == '<h1>Foo</h1>\n'
+}
+
+fn test_emphasis_leftover_delimiters_are_literal() {
+	// Unmatched delimiters become literal text.
+	assert to_html('*a**b**') == '<p>*a<strong>b</strong></p>\n'
+	assert to_html('**a**b*') == '<p><strong>a</strong>b*</p>\n'
+	assert to_html('*foo bar') == '<p>*foo bar</p>\n'
+}
+
+fn test_emphasis_mixed_star_underscore() {
+	// * and _ delimiters do not pair with each other.
+	assert to_html('*foo _bar_ baz*') == '<p><em>foo <em>bar</em> baz</em></p>\n'
+	assert to_html('__foo *bar* baz__') == '<p><strong>foo <em>bar</em> baz</strong></p>\n'
+}
+
+fn test_link_ref_def_with_leading_spaces() {
+	// CommonMark allows 0-3 leading spaces before a link ref def.
+	assert to_html(' [foo]: https://example.com\n\n[foo]') == '<p><a href="https://example.com">foo</a></p>\n'
+	assert to_html('  [bar]: https://example.org\n\n[bar]') == '<p><a href="https://example.org">bar</a></p>\n'
+	assert to_html('   [baz]: https://v-lang.io\n\n[baz]') == '<p><a href="https://v-lang.io">baz</a></p>\n'
+}
+
+fn test_link_ref_def_with_four_leading_spaces_is_not_a_ref() {
+	// Four leading spaces start an indented code block, not a reference definition.
+	src := '    [foo]: https://example.com\n\n[foo]'
+	html := to_html(src)
+	assert !html.contains('<a href=')
+	assert html.contains('[foo]: https://example.com')
+}
+
+fn test_setext_heading_multiline_text() {
+	// Multi-line setext heading text should preserve soft breaks.
+	html := to_html('Foo\nbar\n===')
+	assert html == '<h1>Foo\nbar</h1>\n'
+}
+
+fn test_task_list() {
+	src := '- [ ] unchecked\n- [x] checked\n- [X] also checked'
+	html := to_html_opts(src, Options{
+		task_list: true
+	})
+	assert html.contains('<input type="checkbox" disabled="">')
+	assert html.contains('<input type="checkbox" disabled="" checked="">')
+	assert html.contains('unchecked')
+	assert html.contains('checked')
+}
+
+fn test_task_list_not_applied_without_extension() {
+	// Without the extension, task markers are rendered as plain text.
+	html := to_html('- [ ] item')
+	assert !html.contains('<input')
+	assert html.contains('[ ] item')
+}
+
+fn test_task_list_marker_requires_space_after_closing_bracket() {
+	// GFM task markers are [ ]/[x]/[X] followed by whitespace or end of item.
+	src := '- [x]ok\n- [ ]todo'
+	html := to_html_opts(src, Options{
+		task_list: true
+	})
+	assert !html.contains('<input')
+	assert html.contains('[x]ok')
+	assert html.contains('[ ]todo')
+}
+
+fn test_task_list_xhtml_checkbox_self_closing() {
+	html := to_html_opts('- [x] done', Options{
+		task_list:     true
+		renderer_opts: RendererOptions{
+			xhtml: true
+		}
+	})
+	assert html.contains('<input type="checkbox" disabled="" checked="" />')
+}
+
+fn test_footnote_definition_inside_list_item_is_preserved() {
+	src := '- item[^note]\n\n  [^note]: footnote in list\n\noutside[^note]'
+	html := to_html_opts(src, Options{
+		footnotes: true
+	})
+	assert html.contains('item<sup><a href="#fn-note" id="fnref-note">1</a></sup>')
+	assert html.contains('outside<sup><a href="#fn-note" id="fnref-note">1</a></sup>')
+	assert html.contains('<li id="fn-note">footnote in list')
+	assert html.contains('<a href="#fnref-note">&#x21A9;</a></li>')
+}
+
+fn test_footnote_definition_inside_blockquote_is_preserved() {
+	src := '> quote[^q]\n>\n> [^q]: footnote in quote'
+	html := to_html_opts(src, Options{
+		footnotes: true
+	})
+	assert html.contains('quote<sup><a href="#fn-q" id="fnref-q">1</a></sup>')
+	assert html.contains('<li id="fn-q">footnote in quote')
+	assert html.contains('<a href="#fnref-q">&#x21A9;</a></li>')
+}
+
+fn test_link_ref_def_multiline_title() {
+	// CommonMark allows the title on the next line when the destination is alone.
+	src := '[foo]: /url\n"a title"\n\n[foo]'
+	html := to_html(src)
+	assert html.contains('<a href="/url"')
+	assert html.contains('title="a title"')
+	assert html.contains('>foo</a>')
+}
+
+fn test_link_ref_def_multiline_title_single_quotes() {
+	src := "[bar]: /path\n'my title'\n\n[bar]"
+	html := to_html(src)
+	assert html.contains('<a href="/path"')
+	assert html.contains('title="my title"')
+}
+
+fn test_link_ref_def_multiline_no_title_next_line_is_content() {
+	// If the next line is not a title, it becomes normal content.
+	src := '[baz]: /url\n\nsome text\n\n[baz]'
+	html := to_html(src)
+	assert html.contains('<a href="/url">baz</a>')
+	assert html.contains('some text')
+}
+
+fn test_gfm_helper_sets_core_extension_flags() {
+	md := new(Options{
+		extensions: gfm()
+	})
+	assert md.opts.tables
+	assert md.opts.strikethrough
+	assert md.opts.linkify
+	assert md.opts.task_list
+}
+
+fn test_individual_extension_helpers_set_flags() {
+	md_footnote := new(Options{
+		extensions: [Extension(footnote())]
+	})
+	assert md_footnote.opts.footnotes
+
+	md_typographer := new(Options{
+		extensions: [Extension(typographer())]
+	})
+	assert md_typographer.opts.typographer
+
+	md_definition_list := new(Options{
+		extensions: [Extension(definition_list())]
+	})
+	assert md_definition_list.opts.definition_list
+}
+
+fn test_emphasis_goldmark_parity_edge_cases() {
+	assert to_html('_a* __*_* b b') == '<p><em>a* __*</em>* b b</p>\n'
+	assert to_html('* bb _ *__*a* a_') == '<ul>\n<li>bb _ *__<em>a</em> a_</li>\n</ul>\n'
+	assert to_html('baa _ a*aba**_ba') == '<p>baa _ a*aba**_ba</p>\n'
+	assert to_html('_a_*_b**_aba*') == '<p><em>a</em><em>_b**_aba</em></p>\n'
+	assert to_html('x_ ***b*ab*bb_a*a a') == '<p>x_ <em><em><em>b</em>ab</em>bb_a</em>a a</p>\n'
+}
diff --git a/vlib/x/markdown/node.v b/vlib/x/markdown/node.v
new file mode 100644
index 000000000..720c90e1b
--- /dev/null
+++ b/vlib/x/markdown/node.v
@@ -0,0 +1,144 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+module markdown
+
+import strings
+
+// NodeKind identifies what kind of AST node a Node represents.
+pub enum NodeKind {
+	// ------- document root -------
+	document
+	// ------- block elements -------
+	heading
+	paragraph
+	blockquote
+	list
+	list_item
+	code_block
+	fenced_code
+	thematic_break
+	html_block
+	link_ref_def
+	// GFM block extensions
+	table
+	table_head
+	table_body
+	table_row
+	table_cell
+	// Definition list (Pandoc-style)
+	definition_list
+	definition_term
+	definition_desc
+	// Footnote definition block
+	footnote_def
+	// ------- inline elements -------
+	text
+	emphasis
+	strong
+	code_span
+	link
+	image
+	autolink
+	raw_html
+	hard_break
+	soft_break
+	// GFM inline extensions
+	strikethrough
+	// Footnote reference inline
+	footnote_ref
+	// Task list checkbox (inline, first child of a list_item)
+	task_checkbox
+}
+
+// Alignment is the text alignment of a table cell column.
+pub enum Alignment {
+	none_
+	left
+	center
+	right
+}
+
+// Node is a node in the parsed markdown AST.
+// A document is a tree of Nodes with .document as the root.
+@[heap]
+pub struct Node {
+pub mut:
+	kind NodeKind
+	// ----- block-level fields -----
+	// heading: 1–6
+	level int
+	// list: true when there are no blank lines between items
+	is_tight bool
+	// list: true for ordered (1. 2. 3.), false for bullet (- * +)
+	is_ordered bool
+	// list: starting number of an ordered list
+	list_start int = 1
+	// fenced_code: the info string after the opening fence (e.g. "go")
+	fence_info string
+	// ----- inline-level fields -----
+	// text / code_span / raw_html / html_block: literal string content
+	literal string
+	// link / image: URL destination
+	dest string
+	// link / image: optional title
+	title string
+	// link: reference label (for reference-style links)
+	label string
+	// task_checkbox: true when the checkbox is checked ([x])
+	checked bool
+	// table_cell: column alignment
+	align Alignment
+	// heading: optional explicit or auto-generated id attribute
+	id string
+	// footnote_ref / footnote_def: footnote label
+	fn_label string
+	// footnote_def: 1-based ordinal assigned during rendering
+	fn_index int
+	// ----- tree structure -----
+	children []&Node
+}
+
+// new_node allocates and returns a new Node of the given kind.
+pub fn new_node(kind NodeKind) &Node {
+	return &Node{
+		kind: kind
+	}
+}
+
+// append_child appends child as the last child of n.
+pub fn (mut n Node) append_child(child &Node) {
+	n.children << child
+}
+
+// text_content returns the plain-text content of this node and all descendants,
+// concatenated in document order.
+pub fn (n &Node) text_content() string {
+	match n.kind {
+		.text, .code_span, .raw_html {
+			return n.literal
+		}
+		else {
+			mut sb := strings.new_builder(64)
+			for child in n.children {
+				sb.write_string(child.text_content())
+			}
+			return sb.str()
+		}
+	}
+}
+
+// walk traverses n and all its descendants in pre-order (root before children).
+// The callback f receives each node; return false from f to stop traversal early.
+// walk itself returns false if traversal was stopped, true otherwise.
+pub fn (n &Node) walk(f fn (&Node) bool) bool {
+	if !f(n) {
+		return false
+	}
+	for child in n.children {
+		if !child.walk(f) {
+			return false
+		}
+	}
+	return true
+}
diff --git a/vlib/x/markdown/parser.v b/vlib/x/markdown/parser.v
new file mode 100644
index 000000000..43127ea75
--- /dev/null
+++ b/vlib/x/markdown/parser.v
@@ -0,0 +1,1261 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+module markdown
+
+import strings
+
+// BlockParser parses markdown block structure line by line into an AST.
+// After block parsing, inline content is parsed for every leaf node.
+struct BlockParser {
+	opts Options
+mut:
+	lines   []string
+	pos     int
+	ref_map map[string]LinkRef
+	fn_defs map[string]&Node
+}
+
+// new_block_parser creates a BlockParser for the given source.
+fn new_block_parser(src string, opts Options, ref_map map[string]LinkRef) BlockParser {
+	normalized := src.replace('\r\n', '\n').replace('\r', '\n')
+	lines := normalized.split('\n')
+	mut refs := map[string]LinkRef{}
+	for k, v in ref_map {
+		refs[k] = v
+	}
+	return BlockParser{
+		opts:    opts
+		lines:   lines
+		ref_map: refs
+		fn_defs: map[string]&Node{}
+	}
+}
+
+// nested_block_parser creates a nested parser that inherits the current options
+// and reference definitions.
+fn (p &BlockParser) nested_block_parser(lines []string) BlockParser {
+	mut refs := map[string]LinkRef{}
+	for k, v in p.ref_map {
+		refs[k] = v
+	}
+	return BlockParser{
+		opts:    p.opts
+		lines:   lines
+		ref_map: refs
+		fn_defs: map[string]&Node{}
+	}
+}
+
+// merge_nested_state propagates nested parser state back to the parent parser.
+fn (mut p BlockParser) merge_nested_state(inner BlockParser) {
+	for k, v in inner.ref_map {
+		p.ref_map[k] = v
+	}
+	if p.opts.footnotes {
+		for k, v in inner.fn_defs {
+			if k !in p.fn_defs {
+				p.fn_defs[k] = v
+			}
+		}
+	}
+}
+
+// parse parses the full document and returns the AST root node.
+fn (mut p BlockParser) parse() &Node {
+	mut doc := new_node(.document)
+	p.parse_blocks(mut doc, 0)
+	// Attach collected footnote definitions as children of the document.
+	if p.opts.footnotes {
+		for _, fn_node in p.fn_defs {
+			doc.append_child(fn_node)
+		}
+	}
+	return doc
+}
+
+// parse_blocks fills parent with block-level children parsed from p.lines[p.pos..].
+// indent is the minimum leading-space indent already consumed by a container.
+fn (mut p BlockParser) parse_blocks(mut parent Node, indent int) {
+	for p.pos < p.lines.len {
+		line_raw := p.lines[p.pos]
+		line := expand_tabs(line_raw)
+		trimmed := line.trim_left(' \t')
+
+		// --- blank line ---
+		if is_blank(line) {
+			p.pos++
+			continue
+		}
+
+		stripped := trim_indent(line, indent)
+		sp := leading_spaces(stripped)
+		content := trim_indent(stripped, sp)
+
+		// --- thematic break (---, ***, ___) ---
+		if is_thematic_break(stripped) {
+			node := new_node(.thematic_break)
+			parent.append_child(node)
+			p.pos++
+			continue
+		}
+
+		// --- ATX heading (# ... ######) ---
+		if heading := p.try_atx_heading(stripped) {
+			parent.append_child(heading)
+			p.pos++
+			continue
+		}
+
+		// --- fenced code block (``` or ~~~) ---
+		if fenced := p.try_fenced_code(stripped, indent) {
+			parent.append_child(fenced)
+			continue
+		}
+
+		// --- HTML block ---
+		if html_blk := p.try_html_block(stripped, indent) {
+			parent.append_child(html_blk)
+			continue
+		}
+
+		// --- link reference definition ---
+		// CommonMark allows 0-3 leading spaces after container indentation.
+		if sp <= 3 && p.try_link_ref_def(content) {
+			continue
+		}
+
+		// --- footnote definition (if footnotes extension enabled) ---
+		if p.opts.footnotes {
+			if p.try_footnote_def(stripped, indent) {
+				continue
+			}
+		}
+
+		// --- blockquote (>) ---
+		if stripped.starts_with('>') {
+			bq := p.parse_blockquote(indent)
+			parent.append_child(bq)
+			continue
+		}
+
+		// --- indented code block (4 spaces) ---
+		if sp >= 4 && !is_blank(stripped) {
+			cb := p.parse_indented_code(indent)
+			parent.append_child(cb)
+			continue
+		}
+
+		// --- list (bullet or ordered) ---
+		if is_list_marker(stripped) {
+			lst := p.parse_list(indent)
+			parent.append_child(lst)
+			continue
+		}
+
+		// --- GFM table (if tables extension enabled) ---
+		if p.opts.tables {
+			if tbl := p.try_table(indent) {
+				parent.append_child(tbl)
+				continue
+			}
+		}
+
+		// --- definition list (if extension enabled) ---
+		if p.opts.definition_list {
+			if dl := p.try_definition_list(indent) {
+				parent.append_child(dl)
+				continue
+			}
+		}
+
+		// --- paragraph (including setext headings) ---
+		para := p.parse_paragraph(indent)
+		if para.kind == .heading || para.kind == .paragraph {
+			parent.append_child(para)
+		}
+		_ = trimmed
+		_ = content
+	}
+}
+
+// ---- Thematic break ----
+
+// is_thematic_break returns true if line is a valid thematic break
+// (three or more -, *, or _ with optional spaces).
+fn is_thematic_break(line string) bool {
+	trimmed := line.trim_space()
+	if trimmed.len < 3 {
+		return false
+	}
+	mut c := trimmed[0]
+	if c != `-` && c != `*` && c != `_` {
+		return false
+	}
+	mut count := 0
+	for i := 0; i < trimmed.len; i++ {
+		ch := trimmed[i]
+		if ch == c {
+			count++
+		} else if ch != ` ` && ch != `\t` {
+			return false
+		}
+	}
+	return count >= 3
+}
+
+// ---- ATX headings ----
+
+// try_atx_heading attempts to parse an ATX heading from line.
+// Returns the heading node on success.
+fn (mut p BlockParser) try_atx_heading(line string) ?&Node {
+	if line.len == 0 || line[0] != `#` {
+		return none
+	}
+	mut level := 0
+	for level < line.len && line[level] == `#` {
+		level++
+	}
+	if level > 6 {
+		return none
+	}
+	if level < line.len && line[level] != ` ` && line[level] != `\t` {
+		return none
+	}
+	mut content := line[level..].trim_space()
+	// Strip trailing # sequence.
+	for content.ends_with('#') {
+		stripped := content.trim_right('#')
+		if stripped.len == 0 || stripped.ends_with(' ') || stripped.ends_with('\t') {
+			content = stripped.trim_right(' \t')
+			break
+		}
+		break
+	}
+	mut node := new_node(.heading)
+	node.level = level
+	node.literal = content
+	if p.opts.parser_opts.auto_heading_id {
+		node.id = heading_id_from_text(content)
+	}
+	return node
+}
+
+// ---- Fenced code blocks ----
+
+// try_fenced_code attempts to parse a fenced code block starting at p.pos.
+fn (mut p BlockParser) try_fenced_code(line string, indent int) ?&Node {
+	fence_char, fence_len := detect_fence(line)
+	if fence_len < 3 {
+		return none
+	}
+	info := line[fence_len..].trim_space()
+	// info string must not contain a backtick when using backtick fence.
+	if fence_char == 96 && info.contains('`') {
+		return none
+	}
+	p.pos++
+	mut code_lines := []string{}
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped := trim_indent(raw, indent)
+		// Check for closing fence.
+		close_char, close_len := detect_fence(stripped)
+		if close_char == fence_char && close_len >= fence_len {
+			rest := stripped[close_len..].trim_space()
+			if rest.len == 0 {
+				p.pos++
+				break
+			}
+		}
+		code_lines << trim_indent(raw, indent)
+		p.pos++
+	}
+	mut node := new_node(.fenced_code)
+	node.fence_info = info
+	node.literal = code_lines.join('\n') + '\n'
+	return node
+}
+
+// detect_fence returns (fence_char, fence_length) if line starts with a valid
+// code-fence sequence, or (0, 0) if not.
+fn detect_fence(line string) (u8, int) {
+	if line.len < 3 {
+		return 0, 0
+	}
+	c := line[0]
+	if c != 96 && c != `~` {
+		return 0, 0
+	}
+	mut n := 0
+	for n < line.len && line[n] == c {
+		n++
+	}
+	if n >= 3 {
+		return c, n
+	}
+	return 0, 0
+}
+
+// ---- Indented code block ----
+
+// parse_indented_code collects lines that are indented by at least (indent+4)
+// spaces (or blank) into an indented code block.
+fn (mut p BlockParser) parse_indented_code(indent int) &Node {
+	mut lines := []string{}
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		if is_blank(raw) {
+			// Blank line may be included, but only if followed by more indented code.
+			lines << ''
+			p.pos++
+			continue
+		}
+		stripped := trim_indent(raw, indent)
+		sp := leading_spaces(stripped)
+		if sp < 4 {
+			break
+		}
+		lines << trim_indent(stripped, 4)
+		p.pos++
+	}
+	// Trim trailing blank lines.
+	for lines.len > 0 && lines[lines.len - 1] == '' {
+		lines = unsafe { lines[..lines.len - 1] }
+	}
+	mut node := new_node(.code_block)
+	node.literal = lines.join('\n') + '\n'
+	return node
+}
+
+// ---- HTML blocks ----
+
+// block_level_tags lists HTML tags that start an HTML block (type 6).
+const block_level_tags = ['address', 'article', 'aside', 'base', 'basefont', 'blockquote', 'body',
+	'caption', 'center', 'col', 'colgroup', 'dd', 'details', 'dialog', 'dir', 'div', 'dl', 'dt',
+	'fieldset', 'figcaption', 'figure', 'footer', 'form', 'frame', 'frameset', 'h1', 'h2', 'h3',
+	'h4', 'h5', 'h6', 'head', 'header', 'hr', 'html', 'iframe', 'legend', 'li', 'link', 'main',
+	'menu', 'menuitem', 'meta', 'nav', 'noframes', 'ol', 'optgroup', 'option', 'p', 'param', 'search',
+	'section', 'summary', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'title', 'tr', 'track',
+	'ul']
+
+// try_html_block attempts to parse an HTML block starting at p.pos.
+fn (mut p BlockParser) try_html_block(line string, indent int) ?&Node {
+	html_type := detect_html_block_type(line)
+	if html_type == 0 {
+		return none
+	}
+	mut raw_lines := []string{}
+	raw_lines << p.lines[p.pos]
+	p.pos++
+	// Types 1-5 end at specific end patterns; type 6-7 end at blank line.
+	for p.pos < p.lines.len {
+		raw := p.lines[p.pos]
+		expanded := expand_tabs(raw)
+		stripped := trim_indent(expanded, indent)
+		match html_type {
+			1 {
+				raw_lines << raw
+				p.pos++
+				low := stripped.to_lower()
+				if low.contains('</script>') || low.contains('</pre>') || low.contains('</style>')
+					|| low.contains('</textarea>') {
+					break
+				}
+			}
+			2 {
+				raw_lines << raw
+				p.pos++
+				if stripped.contains('-->') {
+					break
+				}
+			}
+			3 {
+				raw_lines << raw
+				p.pos++
+				if stripped.contains('?>') {
+					break
+				}
+			}
+			4 {
+				raw_lines << raw
+				p.pos++
+				if stripped.contains('>') {
+					break
+				}
+			}
+			5 {
+				raw_lines << raw
+				p.pos++
+				if stripped.contains(']]>') {
+					break
+				}
+			}
+			6, 7 {
+				if is_blank(stripped) {
+					break
+				}
+				raw_lines << raw
+				p.pos++
+			}
+			else {}
+		}
+	}
+	mut node := new_node(.html_block)
+	node.literal = raw_lines.join('\n') + '\n'
+	return node
+}
+
+// detect_html_block_type returns the HTML block type (1-7) or 0 if the line
+// does not start an HTML block.
+fn detect_html_block_type(line string) int {
+	stripped := line.trim_left(' \t')
+	if stripped.len == 0 || stripped[0] != `<` {
+		return 0
+	}
+	low := stripped.to_lower()
+	// Type 2: HTML comment
+	if low.starts_with('<!--') {
+		return 2
+	}
+	// Type 3: processing instruction
+	if low.starts_with('<?') {
+		return 3
+	}
+	// Type 5: CDATA
+	if low.starts_with('<![cdata[') {
+		return 5
+	}
+	// Type 4: <!X
+	if low.len > 2 && low[1] == `!` && low[2] >= `a` && low[2] <= `z` {
+		return 4
+	}
+	// Type 1: script/pre/style/textarea
+	for _, tag in ['<script', '<pre', '<style', '<textarea'] {
+		if low.starts_with(tag) {
+			rest := low[tag.len..]
+			if rest.len == 0 || rest[0] == ` ` || rest[0] == `\t` || rest[0] == `>`
+				|| rest[0] == `\n` {
+				return 1
+			}
+		}
+	}
+	// Type 6: block-level tag
+	tag_name := extract_tag_name(low[1..])
+	if tag_name.len > 0 {
+		for bt in block_level_tags {
+			if tag_name == bt {
+				return 6
+			}
+		}
+	}
+	// Type 7: complete open/close tag not in type 6
+	if is_complete_html_tag(stripped) {
+		return 7
+	}
+	return 0
+}
+
+// extract_tag_name extracts the tag name from the beginning of s.
+fn extract_tag_name(s string) string {
+	mut end := 0
+	for end < s.len && (is_alnum(s[end]) || s[end] == `-`) {
+		end++
+	}
+	return s[..end].to_lower()
+}
+
+// is_complete_html_tag returns true if s looks like a complete open or close tag.
+fn is_complete_html_tag(s string) bool {
+	if s.len < 3 {
+		return false
+	}
+	// Must start with < and end with >
+	if s[0] != `<` {
+		return false
+	}
+	end := s.index('>') or { return false }
+	return end == s.len - 1 || s[end + 1..].trim_space().len == 0
+}
+
+// ---- Link reference definitions ----
+
+// try_link_ref_def attempts to parse a link reference definition at p.pos.
+// CommonMark allows the title to appear on the next line when the destination
+// is alone on the first line.  Returns true and advances p.pos if successful.
+fn (mut p BlockParser) try_link_ref_def(line string) bool {
+	if !line.starts_with('[') {
+		return false
+	}
+	// Find closing bracket.
+	mut i := 1
+	for i < line.len && line[i] != `]` {
+		if line[i] == `\\` {
+			i++
+		}
+		i++
+	}
+	if i >= line.len || line[i] != `]` || i + 1 >= line.len || line[i + 1] != `:` {
+		return false
+	}
+	label := normalize_label(line[1..i])
+	rest := line[i + 2..].trim_left(' \t')
+	if label.len == 0 {
+		return false
+	}
+	// Parse destination.
+	dest, after_dest := parse_link_dest(rest)
+	if after_dest == rest {
+		return false
+	}
+	// Parse optional title.  The title may appear on the same line or, if the
+	// destination is the only content on the first line, on the very next line.
+	mut title := ''
+	mut extra_lines := 0 // number of additional lines consumed for the title
+	title_str := after_dest.trim_left(' \t')
+	if title_str.len > 0 {
+		// Title (or unwanted content) is on the same line as the destination.
+		parsed_title, title_rest := parse_link_title(title_str)
+		if title_rest == title_str {
+			// Not a valid title; reject the whole definition.
+			return false
+		}
+		if title_rest.trim_space().len > 0 {
+			// Trailing content after the title – invalid.
+			return false
+		}
+		title = parsed_title
+	} else {
+		// Destination was alone on its line; look for a title on the next line.
+		next_idx := p.pos + 1
+		if next_idx < p.lines.len {
+			next_line := expand_tabs(p.lines[next_idx]).trim_left(' \t')
+			if next_line.len > 0 {
+				parsed_title, title_rest := parse_link_title(next_line)
+				if title_rest != next_line && title_rest.trim_space().len == 0 {
+					// Valid title on the next line; consume it.
+					title = parsed_title
+					extra_lines = 1
+				}
+				// If the next line starts with something that is not a title
+				// delimiter, we simply leave `title` empty and do not consume
+				// that line (it will be parsed as the next block).
+			}
+		}
+	}
+	if label !in p.ref_map {
+		p.ref_map[label] = LinkRef{
+			dest:  dest
+			title: title
+		}
+	}
+	p.pos += 1 + extra_lines
+	return true
+}
+
+// parse_link_dest parses a link destination from s and returns (dest, rest).
+fn parse_link_dest(s string) (string, string) {
+	if s.len == 0 {
+		return '', s
+	}
+	if s[0] == `<` {
+		// Angle-bracket form: <url>
+		end := s.index_after_('>', 1)
+		if end < 0 {
+			return '', s
+		}
+		return s[1..end], s[end + 1..]
+	}
+	// Regular form: no spaces, no control characters, balanced parentheses.
+	mut parens := 0
+	mut i := 0
+	for i < s.len {
+		c := s[i]
+		if c == ` ` || c == `\t` || c == `\n` {
+			break
+		}
+		if c == `(` {
+			parens++
+		} else if c == `)` {
+			if parens == 0 {
+				break
+			}
+			parens--
+		} else if c == `\\` && i + 1 < s.len {
+			i += 2
+			continue
+		}
+		i++
+	}
+	if i == 0 {
+		return '', s
+	}
+	if parens != 0 {
+		return '', s
+	}
+	return s[..i], s[i..]
+}
+
+// parse_link_title parses an optional link title from s and returns (title, rest).
+// Returns empty string if no valid title is found.
+fn parse_link_title(s string) (string, string) {
+	if s.len == 0 {
+		return '', s
+	}
+	open := s[0]
+	mut close := u8(0)
+	match open {
+		`"` { close = `"` }
+		`'` { close = `'` }
+		`(` { close = `)` }
+		else { return '', s }
+	}
+
+	mut i := 1
+	for i < s.len {
+		c := s[i]
+		if c == close {
+			return unescape_string(s[1..i]), s[i + 1..]
+		}
+		if c == `\\` && i + 1 < s.len {
+			i += 2
+			continue
+		}
+		i++
+	}
+	return '', s
+}
+
+// ---- Blockquote ----
+
+// parse_blockquote parses a blockquote block and returns a blockquote node.
+fn (mut p BlockParser) parse_blockquote(indent int) &Node {
+	mut bq_lines := []string{}
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped := trim_indent(raw, indent)
+		if is_blank(stripped) {
+			// Lazy continuation stops at blank.
+			p.pos++
+			break
+		}
+		if stripped.starts_with('> ') {
+			bq_lines << stripped[2..]
+			p.pos++
+		} else if stripped.starts_with('>') {
+			bq_lines << stripped[1..]
+			p.pos++
+		} else {
+			// Lazy continuation line.
+			bq_lines << stripped
+			p.pos++
+		}
+	}
+	mut node := new_node(.blockquote)
+	// Recursively parse the blockquote content.
+	mut inner := p.nested_block_parser(bq_lines)
+	inner.parse_blocks(mut node, 0)
+	p.merge_nested_state(inner)
+	return node
+}
+
+// ---- Lists ----
+
+// ListMarker holds parsed list marker information.
+struct ListMarker {
+	is_ordered  bool
+	bullet_char u8
+	start       int
+	indent      int // total indent of content after marker
+}
+
+// is_list_marker returns true if line starts with a bullet or ordered list marker.
+fn is_list_marker(line string) bool {
+	if line.len == 0 {
+		return false
+	}
+	_, ok := parse_list_marker(line)
+	return ok
+}
+
+// parse_list_marker parses a list marker from the beginning of line.
+fn parse_list_marker(line string) (ListMarker, bool) {
+	sp := leading_spaces(line)
+	rest := line[sp..]
+	if rest.len == 0 {
+		return ListMarker{}, false
+	}
+	// Bullet list: -, *, +
+	if rest[0] == `-` || rest[0] == `*` || rest[0] == `+` {
+		if rest.len < 2 || (rest[1] != ` ` && rest[1] != `\t`) {
+			// Only a bare marker with no space is not valid (except empty item for -)
+			if rest.len == 1 {
+				return ListMarker{
+					is_ordered:  false
+					bullet_char: rest[0]
+					indent:      sp + 2
+				}, true
+			}
+			return ListMarker{}, false
+		}
+		content_indent := sp + 1 + (if rest.len > 1 && rest[1] == `\t` { 3 } else { 1 })
+		return ListMarker{
+			is_ordered:  false
+			bullet_char: rest[0]
+			indent:      content_indent
+		}, true
+	}
+	// Ordered list: 1. or 1)
+	mut num_end := 0
+	for num_end < rest.len && is_digit(rest[num_end]) {
+		num_end++
+	}
+	if num_end > 0 && num_end < rest.len && (rest[num_end] == `.` || rest[num_end] == `)`) {
+		marker_end := num_end + 1
+		if marker_end < rest.len && rest[marker_end] != ` ` && rest[marker_end] != `\t` {
+			return ListMarker{}, false
+		}
+		num_str := rest[..num_end]
+		start := num_str.int()
+		mut content_indent := sp + marker_end + 1
+		if marker_end < rest.len && rest[marker_end] == `\t` {
+			content_indent = sp + marker_end + (4 - ((sp + marker_end) % 4))
+		}
+		return ListMarker{
+			is_ordered:  true
+			start:       start
+			bullet_char: rest[num_end]
+			indent:      content_indent
+		}, true
+	}
+	return ListMarker{}, false
+}
+
+// parse_list parses a list (bullet or ordered) and returns a list node.
+fn (mut p BlockParser) parse_list(indent int) &Node {
+	// Determine list type from the first item's marker.
+	if p.pos >= p.lines.len {
+		return new_node(.list)
+	}
+
+	first_raw := expand_tabs(p.lines[p.pos])
+	first_line := trim_indent(first_raw, indent)
+	marker, ok := parse_list_marker(first_line)
+	if !ok {
+		return new_node(.list)
+	}
+
+	mut list := new_node(.list)
+	list.is_ordered = marker.is_ordered
+	list.list_start = if marker.is_ordered { marker.start } else { 1 }
+	list.is_tight = true
+
+	mut had_blank := false
+
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped := trim_indent(raw, indent)
+
+		if is_blank(stripped) {
+			had_blank = true
+			p.pos++
+			continue
+		}
+
+		cur_marker, marker_ok := parse_list_marker(stripped)
+		if !marker_ok {
+			break
+		}
+		// Different list type → stop.
+		if cur_marker.is_ordered != marker.is_ordered {
+			break
+		}
+		if !cur_marker.is_ordered && cur_marker.bullet_char != marker.bullet_char {
+			break
+		}
+
+		if had_blank {
+			list.is_tight = false
+		}
+		had_blank = false
+
+		item := p.parse_list_item(indent)
+		list.append_child(item)
+	}
+
+	return list
+}
+
+// parse_list_item parses a single list item and returns a list_item node.
+fn (mut p BlockParser) parse_list_item(base_indent int) &Node {
+	if p.pos >= p.lines.len {
+		return new_node(.list_item)
+	}
+
+	mut item := new_node(.list_item)
+
+	// Get first line of the item
+	first_raw := expand_tabs(p.lines[p.pos])
+	first_stripped := trim_indent(first_raw, base_indent)
+
+	// Extract content after marker
+	marker_line := first_stripped
+	mut marker_idx := 0
+
+	// Find where marker ends in stripped line
+	if marker_line.len > 0
+		&& (marker_line[0] == `-` || marker_line[0] == `*` || marker_line[0] == `+`) {
+		// Bullet marker: skip marker and whitespace
+		marker_idx = 1
+		for marker_idx < marker_line.len
+			&& (marker_line[marker_idx] == ` ` || marker_line[marker_idx] == `\t`) {
+			marker_idx++
+		}
+	} else {
+		// Ordered marker: skip number and . or )
+		for marker_idx < marker_line.len && is_digit(marker_line[marker_idx]) {
+			marker_idx++
+		}
+		if marker_idx < marker_line.len
+			&& (marker_line[marker_idx] == `.` || marker_line[marker_idx] == `)`) {
+			marker_idx++
+		}
+		// Skip whitespace after marker
+		for marker_idx < marker_line.len
+			&& (marker_line[marker_idx] == ` ` || marker_line[marker_idx] == `\t`) {
+			marker_idx++
+		}
+	}
+
+	// Get content after marker
+	first_content := if marker_idx < marker_line.len {
+		marker_line[marker_idx..]
+	} else {
+		''
+	}
+
+	// Detect task list checkbox: [ ] or [x] or [X] at the start of content.
+	mut task_checked := false
+	mut has_task := false
+	mut task_content_start := 0
+	if p.opts.task_list && first_content.len >= 3 && first_content[0] == `[` {
+		if (first_content[1] == ` ` || first_content[1] == `x` || first_content[1] == `X`)
+			&& first_content[2] == `]` {
+			if first_content.len == 3 || first_content[3] == ` ` || first_content[3] == `\t` {
+				has_task = true
+				task_checked = first_content[1] != ` `
+				// Skip the checkbox and one optional following whitespace char.
+				task_content_start = if first_content.len > 3 { 4 } else { 3 }
+			}
+		}
+	}
+	actual_first_content := if has_task {
+		first_content[task_content_start..]
+	} else {
+		first_content
+	}
+
+	// Collect lines belonging to this item
+	mut item_lines := [actual_first_content]
+	p.pos++
+
+	// Content indent is where subsequent lines must be indented to
+	first_leading := leading_spaces(first_stripped)
+	content_indent := first_leading + marker_idx
+
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped_base := trim_indent(raw, base_indent)
+
+		if is_blank(stripped_base) {
+			item_lines << ''
+			p.pos++
+			continue
+		}
+
+		sp := leading_spaces(stripped_base)
+
+		// If line has enough indent, include it
+		if sp >= content_indent {
+			// Remove the content indent
+			item_lines << trim_indent(stripped_base, content_indent)
+			p.pos++
+			continue
+		}
+
+		// If line starts a new list item at base indent level, stop
+		if sp < 2 {
+			_, mk := parse_list_marker(stripped_base)
+			if mk {
+				break
+			}
+		}
+
+		// Check if it might be a sub-block (less indented but meaningful)
+		if is_thematic_break(stripped_base) || stripped_base.starts_with('#') {
+			break
+		}
+
+		item_lines << stripped_base
+		p.pos++
+	}
+
+	// Trim trailing blank lines
+	for item_lines.len > 0 && item_lines[item_lines.len - 1] == '' {
+		item_lines = unsafe { item_lines[..item_lines.len - 1] }
+	}
+
+	// Recursively parse the item's content with fresh parser
+	mut inner := p.nested_block_parser(item_lines)
+	inner.parse_blocks(mut item, 0)
+
+	// Merge back any new link references and footnote definitions.
+	p.merge_nested_state(inner)
+
+	// Prepend task checkbox node if detected (must be first child).
+	if has_task {
+		mut chk := new_node(.task_checkbox)
+		chk.checked = task_checked
+		mut new_children := [chk]
+		for child in item.children {
+			new_children << child
+		}
+		item.children = new_children
+	}
+
+	return item
+}
+
+// ---- Tables (GFM) ----
+
+// try_table attempts to parse a GFM table starting at p.pos.
+// A table requires a header row, an alignment row (|---|), then data rows.
+fn (mut p BlockParser) try_table(indent int) ?&Node {
+	if p.pos + 1 >= p.lines.len {
+		return none
+	}
+	header_raw := expand_tabs(p.lines[p.pos])
+	header_line := trim_indent(header_raw, indent)
+	sep_raw := expand_tabs(p.lines[p.pos + 1])
+	sep_line := trim_indent(sep_raw, indent)
+
+	if !is_table_separator(sep_line) {
+		return none
+	}
+	if !header_line.contains('|') {
+		return none
+	}
+
+	aligns := parse_table_alignments(sep_line)
+	if aligns.len == 0 {
+		return none
+	}
+
+	mut tbl := new_node(.table)
+
+	// Header row.
+	mut head := new_node(.table_head)
+	header_row := parse_table_row(header_line, aligns)
+	head.append_child(header_row)
+	tbl.append_child(head)
+
+	p.pos += 2
+
+	// Body rows.
+	mut body := new_node(.table_body)
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped := trim_indent(raw, indent)
+		if is_blank(stripped) || !stripped.contains('|') {
+			break
+		}
+		body.append_child(parse_table_row(stripped, aligns))
+		p.pos++
+	}
+	if body.children.len > 0 {
+		tbl.append_child(body)
+	}
+	return tbl
+}
+
+// is_table_separator returns true if line is a table alignment separator row.
+fn is_table_separator(line string) bool {
+	trimmed := line.trim('| \t')
+	if trimmed.len == 0 {
+		return false
+	}
+	cells := split_table_cells(line)
+	if cells.len == 0 {
+		return false
+	}
+	for cell in cells {
+		c := cell.trim_space()
+		if c.len == 0 {
+			continue
+		}
+		inner := if c.starts_with(':') && c.ends_with(':') {
+			c[1..c.len - 1]
+		} else if c.starts_with(':') {
+			c[1..]
+		} else if c.ends_with(':') {
+			c[..c.len - 1]
+		} else {
+			c
+		}
+		for ch in inner.bytes() {
+			if ch != `-` {
+				return false
+			}
+		}
+		if inner.len == 0 {
+			return false
+		}
+	}
+	return true
+}
+
+// parse_table_alignments returns the alignment for each column from a separator line.
+fn parse_table_alignments(line string) []Alignment {
+	cells := split_table_cells(line)
+	mut aligns := []Alignment{}
+	for cell in cells {
+		c := cell.trim_space()
+		if c.len == 0 {
+			continue
+		}
+		left := c.starts_with(':')
+		right := c.ends_with(':')
+		if left && right {
+			aligns << .center
+		} else if left {
+			aligns << .left
+		} else if right {
+			aligns << .right
+		} else {
+			aligns << .none_
+		}
+	}
+	return aligns
+}
+
+// parse_table_row parses a table row line into a table_row node.
+fn parse_table_row(line string, aligns []Alignment) &Node {
+	cells := split_table_cells(line)
+	mut row := new_node(.table_row)
+	for i, cell_text in cells {
+		mut cell := new_node(.table_cell)
+		cell.align = if i < aligns.len { aligns[i] } else { .none_ }
+		cell.literal = cell_text.trim_space()
+		row.append_child(cell)
+	}
+	return row
+}
+
+// split_table_cells splits a table row line by pipe characters.
+fn split_table_cells(line string) []string {
+	trimmed := line.trim_space()
+	// Strip leading/trailing pipe.
+	inner := if trimmed.starts_with('|') && trimmed.ends_with('|') && trimmed.len > 1 {
+		trimmed[1..trimmed.len - 1]
+	} else if trimmed.starts_with('|') {
+		trimmed[1..]
+	} else if trimmed.ends_with('|') {
+		trimmed[..trimmed.len - 1]
+	} else {
+		trimmed
+	}
+	mut cells := []string{}
+	mut current := strings.new_builder(32)
+	for i := 0; i < inner.len; i++ {
+		if inner[i] == `\\` && i + 1 < inner.len && inner[i + 1] == `|` {
+			current.write_u8(`|`)
+			i++
+		} else if inner[i] == `|` {
+			cells << current.str()
+			current = strings.new_builder(32)
+		} else {
+			current.write_u8(inner[i])
+		}
+	}
+	last := current.str()
+	cells << last
+	return cells
+}
+
+// ---- Definition list ----
+
+// try_definition_list attempts to parse a definition list starting at p.pos.
+fn (mut p BlockParser) try_definition_list(indent int) ?&Node {
+	if p.pos + 1 >= p.lines.len {
+		return none
+	}
+	next_raw := expand_tabs(p.lines[p.pos + 1])
+	next_stripped := trim_indent(next_raw, indent)
+	if !next_stripped.starts_with(':') {
+		return none
+	}
+	mut dl := new_node(.definition_list)
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped := trim_indent(raw, indent)
+		if is_blank(stripped) {
+			p.pos++
+			break
+		}
+		// Collect term line.
+		mut term := new_node(.definition_term)
+		term.literal = stripped
+		p.pos++
+		// Collect one or more definitions (:).
+		for p.pos < p.lines.len {
+			def_raw := expand_tabs(p.lines[p.pos])
+			def_stripped := trim_indent(def_raw, indent)
+			if def_stripped.starts_with(':') {
+				mut desc := new_node(.definition_desc)
+				desc.literal = def_stripped[1..].trim_left(' \t')
+				term.append_child(desc)
+				p.pos++
+			} else {
+				break
+			}
+		}
+		dl.append_child(term)
+	}
+	if dl.children.len == 0 {
+		return none
+	}
+	return dl
+}
+
+// ---- Footnote definitions ----
+
+// try_footnote_def attempts to parse a footnote definition starting at p.pos.
+fn (mut p BlockParser) try_footnote_def(line string, indent int) bool {
+	if !line.starts_with('[^') {
+		return false
+	}
+	end := line.index_after_(']', 2)
+	if end < 0 || end + 1 >= line.len || line[end + 1] != `:` {
+		return false
+	}
+	label := line[2..end]
+	if label.len == 0 {
+		return false
+	}
+	content := line[end + 2..].trim_left(' \t')
+	mut fn_node := new_node(.footnote_def)
+	fn_node.fn_label = label
+	fn_node.literal = content
+	p.pos++
+	// Collect continuation lines (indented by at least 4 spaces).
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped := trim_indent(raw, indent)
+		if is_blank(stripped) || leading_spaces(stripped) >= 4 {
+			fn_node.literal += '\n' + stripped.trim_left('    ')
+			p.pos++
+		} else {
+			break
+		}
+	}
+	if label !in p.fn_defs {
+		p.fn_defs[label] = fn_node
+	}
+	return true
+}
+
+// ---- Paragraph / Setext heading ----
+
+// parse_paragraph parses a paragraph block, upgrading it to a setext heading
+// if the immediately following line is a setext underline (=== or ---).
+fn (mut p BlockParser) parse_paragraph(indent int) &Node {
+	mut para_lines := []string{}
+	for p.pos < p.lines.len {
+		raw := expand_tabs(p.lines[p.pos])
+		stripped := trim_indent(raw, indent)
+
+		if is_blank(stripped) {
+			p.pos++
+			break
+		}
+		// Check for setext underline on the next line while para_lines is non-empty.
+		if para_lines.len > 0 {
+			if is_setext_underline(stripped) {
+				level := if stripped.trim_left(' \t')[0] == `=` { 1 } else { 2 }
+				content := para_lines.join('\n').trim_space()
+				mut node := new_node(.heading)
+				node.level = level
+				node.literal = content
+				if p.opts.parser_opts.auto_heading_id {
+					node.id = heading_id_from_text(content)
+				}
+				p.pos++
+				return node
+			}
+		}
+		// Other block starters interrupt a paragraph.
+		if para_lines.len > 0 {
+			if is_thematic_break(stripped) || stripped.starts_with('#') || stripped.starts_with('>')
+				|| stripped.starts_with('```') || stripped.starts_with('~~~') {
+				break
+			}
+			if is_list_marker(stripped) {
+				break
+			}
+		}
+		para_lines << stripped
+		p.pos++
+	}
+	mut node := new_node(.paragraph)
+	node.literal = para_lines.join('\n').trim_space()
+	return node
+}
+
+// is_setext_underline returns true if line is a setext heading underline
+// (0-3 leading spaces, then one or more = or - with optional trailing spaces).
+fn is_setext_underline(line string) bool {
+	if line.len == 0 {
+		return false
+	}
+	// Allow up to 3 leading spaces (CommonMark spec rule 80).
+	mut start := 0
+	for start < 3 && start < line.len && line[start] == ` ` {
+		start++
+	}
+	if start >= line.len {
+		return false
+	}
+	c := line[start]
+	if c != `=` && c != `-` {
+		return false
+	}
+	for i := start; i < line.len; i++ {
+		if line[i] != c && line[i] != ` ` && line[i] != `\t` {
+			return false
+		}
+	}
+	return true
+}
+
+// ---- Inline parsing kick-off ----
+// After block parsing, leaf node .literal fields contain raw inline text.
+// The inline parser is invoked lazily by the HTML renderer.
+
+// unescape_string decodes CommonMark backslash escapes in s.
+fn unescape_string(s string) string {
+	if !s.contains('\\') {
+		return s
+	}
+	mut out := strings.new_builder(s.len)
+	mut i := 0
+	for i < s.len {
+		if s[i] == `\\` && i + 1 < s.len && is_ascii_punct(s[i + 1]) {
+			out.write_u8(s[i + 1])
+			i += 2
+		} else {
+			out.write_u8(s[i])
+			i++
+		}
+	}
+	return out.str()
+}
diff --git a/vlib/x/markdown/util.v b/vlib/x/markdown/util.v
new file mode 100644
index 000000000..402e56d3c
--- /dev/null
+++ b/vlib/x/markdown/util.v
@@ -0,0 +1,244 @@
+// Copyright 2026 The V Language. All rights reserved.
+// Use of this source code is governed by an MIT license
+// that can be found in the LICENSE file.
+module markdown
+
+import strings
+
+// html_escape replaces HTML special characters in s with their entity equivalents.
+fn html_escape(s string) string {
+	if s.index_any('&<>"') == -1 {
+		return s
+	}
+	mut sb := strings.new_builder(s.len + 8)
+	for i := 0; i < s.len; i++ {
+		match s[i] {
+			`&` { sb.write_string('&amp;') }
+			`<` { sb.write_string('&lt;') }
+			`>` { sb.write_string('&gt;') }
+			`"` { sb.write_string('&quot;') }
+			else { sb.write_u8(s[i]) }
+		}
+	}
+	return sb.str()
+}
+
+// url_safe_chars contains URL characters that do not need percent-encoding.
+const url_safe_chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.~:/?#[]@!$&()*+,;=%'
+
+// url_encode percent-encodes characters in a URL that need encoding,
+// while leaving valid URL characters (including already-encoded sequences) intact.
+fn url_encode(s string) string {
+	mut sb := strings.new_builder(s.len)
+	for i := 0; i < s.len; i++ {
+		c := s[i]
+		if url_safe_chars.index_u8(c) >= 0 {
+			sb.write_u8(c)
+		} else {
+			sb.write_string('%${c:02X}')
+		}
+	}
+	return sb.str()
+}
+
+// normalize_label normalises a link reference label per CommonMark spec:
+// strip leading/trailing Unicode whitespace, collapse internal whitespace runs
+// to a single space, and fold to lower case.
+fn normalize_label(s string) string {
+	mut out := strings.new_builder(s.len)
+	mut in_space := true // start true so we trim leading space
+	for i := 0; i < s.len; i++ {
+		c := s[i]
+		if c == ` ` || c == `\t` || c == `\n` || c == `\r` {
+			if !in_space {
+				out.write_u8(` `)
+				in_space = true
+			}
+		} else {
+			out.write_u8(ascii_lower(c))
+			in_space = false
+		}
+	}
+	result := out.str()
+	// Trim potential trailing space.
+	if result.ends_with(' ') {
+		return result[..result.len - 1]
+	}
+	return result
+}
+
+// ascii_lower converts an ASCII upper-case letter to lower case.
+@[inline]
+fn ascii_lower(c u8) u8 {
+	if c >= `A` && c <= `Z` {
+		return c + 32
+	}
+	return c
+}
+
+// is_unicode_space returns true for CommonMark Unicode whitespace.
+@[inline]
+fn is_unicode_space(c u8) bool {
+	return c == ` ` || c == `\t` || c == `\n` || c == `\r` || c == 0x0c || c == 0x0b
+}
+
+// is_ascii_punct returns true if c is an ASCII punctuation character.
+@[inline]
+fn is_ascii_punct(c u8) bool {
+	return (c >= `!` && c <= `/`) || (c >= `:` && c <= `@`) || (c >= `[` && c <= 96)
+		|| (c >= `{` && c <= `~`)
+}
+
+// is_digit returns true if c is an ASCII decimal digit.
+@[inline]
+fn is_digit(c u8) bool {
+	return c >= `0` && c <= `9`
+}
+
+// is_alpha returns true if c is an ASCII letter.
+@[inline]
+fn is_alpha(c u8) bool {
+	return (c >= `a` && c <= `z`) || (c >= `A` && c <= `Z`)
+}
+
+// is_alnum returns true if c is an ASCII letter or digit.
+@[inline]
+fn is_alnum(c u8) bool {
+	return is_alpha(c) || is_digit(c)
+}
+
+// heading_id_from_text generates a slug-style id attribute from plain text,
+// matching goldmark's AutoHeadingID output.
+fn heading_id_from_text(text string) string {
+	mut sb := strings.new_builder(text.len)
+	mut prev_dash := true // start true so we trim leading dashes
+	for i := 0; i < text.len; i++ {
+		c := text[i]
+		if is_alnum(c) {
+			sb.write_u8(ascii_lower(c))
+			prev_dash = false
+		} else if c == `-` || is_unicode_space(c) || c == `_` {
+			if !prev_dash {
+				sb.write_u8(`-`)
+				prev_dash = true
+			}
+		}
+		// other characters (punctuation) are dropped
+	}
+	s := sb.str()
+	// Trim trailing dash.
+	return s.trim_right('-')
+}
+
+// count_leading counts how many consecutive occurrences of c appear at the
+// start of s.
+@[inline]
+fn count_leading(s string, c u8) int {
+	mut n := 0
+	for n < s.len && s[n] == c {
+		n++
+	}
+	return n
+}
+
+// expand_tabs converts leading tabs in s to spaces (tab stop = 4 columns).
+fn expand_tabs(s string) string {
+	if !s.contains('\t') {
+		return s
+	}
+	mut sb := strings.new_builder(s.len)
+	mut col := 0
+	for i := 0; i < s.len; i++ {
+		if s[i] == `\t` {
+			spaces := 4 - (col % 4)
+			for _ in 0 .. spaces {
+				sb.write_u8(` `)
+			}
+			col += spaces
+		} else {
+			sb.write_u8(s[i])
+			col++
+		}
+	}
+	return sb.str()
+}
+
+// trim_indent removes up to n leading spaces from s.
+@[inline]
+fn trim_indent(s string, n int) string {
+	mut i := 0
+	for i < n && i < s.len && s[i] == ` ` {
+		i++
+	}
+	return s[i..]
+}
+
+// is_blank returns true if s contains only whitespace.
+@[inline]
+fn is_blank(s string) bool {
+	for i := 0; i < s.len; i++ {
+		if s[i] != ` ` && s[i] != `\t` {
+			return false
+		}
+	}
+	return true
+}
+
+// leading_spaces returns the number of leading spaces (not tabs) in s.
+@[inline]
+fn leading_spaces(s string) int {
+	mut n := 0
+	for n < s.len && s[n] == ` ` {
+		n++
+	}
+	return n
+}
+
+// smart_punctuate applies typographic substitutions to s:
+//   -- → en dash, --- → em dash, ... → ellipsis, smart quotes.
+fn smart_punctuate(s string) string {
+	mut out := strings.new_builder(s.len)
+	i := 0
+	mut j := i
+	src := s.bytes()
+	for j < src.len {
+		c := src[j]
+		if c == `-` {
+			if j + 2 < src.len && src[j + 1] == `-` && src[j + 2] == `-` {
+				out.write_string('\u2014') // em dash
+				j += 3
+				continue
+			} else if j + 1 < src.len && src[j + 1] == `-` {
+				out.write_string('\u2013') // en dash
+				j += 2
+				continue
+			}
+		} else if c == `.` {
+			if j + 2 < src.len && src[j + 1] == `.` && src[j + 2] == `.` {
+				out.write_string('\u2026') // ellipsis
+				j += 3
+				continue
+			}
+		} else if c == `'` {
+			// Simple heuristic: opening after space/start, closing otherwise.
+			if j == 0 || is_unicode_space(src[j - 1]) || is_ascii_punct(src[j - 1]) {
+				out.write_string('\u2018') // left single quote
+			} else {
+				out.write_string('\u2019') // right single quote
+			}
+			j++
+			continue
+		} else if c == `"` {
+			if j == 0 || is_unicode_space(src[j - 1]) || is_ascii_punct(src[j - 1]) {
+				out.write_string('\u201C') // left double quote
+			} else {
+				out.write_string('\u201D') // right double quote
+			}
+			j++
+			continue
+		}
+		out.write_u8(c)
+		j++
+	}
+	return out.str()
+}
-- 
2.39.5