{"id":50195247,"url":"https://github.com/yaroslav/inkmark","last_synced_at":"2026-05-26T15:39:52.372Z","repository":{"id":353077133,"uuid":"1217288862","full_name":"yaroslav/inkmark","owner":"yaroslav","description":"A very fast, feature-packed, AI-first Markdown (CommonMark/GFM) gem for Ruby, based on pulldown-cmark (Rust).","archived":false,"fork":false,"pushed_at":"2026-05-17T09:38:32.000Z","size":1032,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-17T11:39:45.478Z","etag":null,"topics":["ai","chunking","commonmark","commonmark-parsing","llm","markdown","markdown-language","markdown-parser","markdown-to-html","pulldown-cmark","rag","ruby","rubyonrails","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yaroslav.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T18:29:52.000Z","updated_at":"2026-05-17T09:38:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yaroslav/inkmark","commit_stats":null,"previous_names":["yaroslav/inkmark"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/yaroslav/inkmark","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaroslav%2Finkmark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaroslav%2Finkmark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaroslav%2Finkmark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaroslav%2Finkmark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yaroslav","download_url":"https://codeload.github.com/yaroslav/inkmark/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaroslav%2Finkmark/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33528086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chunking","commonmark","commonmark-parsing","llm","markdown","markdown-language","markdown-parser","markdown-to-html","pulldown-cmark","rag","ruby","rubyonrails","rust"],"created_at":"2026-05-25T17:00:40.039Z","updated_at":"2026-05-26T15:39:52.355Z","avatar_url":"https://github.com/yaroslav.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Inkmark\n\nA very fast, feature-packed, AI-first Markdown gem for Ruby.\n\n[![GitHub Release](https://img.shields.io/github/v/release/yaroslav/inkmark)](https://github.com/yaroslav/inkmark/releases)\n[![Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/inkmark)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/yaroslav/inkmark/refs/heads/main/assets/images/inky.png\" width=\"400\" height=\"400\" alt=\"Inky\"\u003e\n\u003c/div\u003e\n\n- **Very fast**. Up to 1.3× faster than redcarpet _(not CommonMark-conformant)_, about 3×–9× faster than other Ruby Markdown gems with native extensions. Built with Rust, based on [pulldown-cmark](https://github.com/pulldown-cmark/pulldown-cmark), uses SIMD.\n- **No surprises**. CommonMark + GitHub Flavored Markdown conformance.\n- **\"Batteries included\" approach**. Build lots of useful features, make them easy to use and as fast as possible.\n- **Easy to use**. As simple as a one-method API. Pass options inline as a hash, set them one by one, or set default options for the entire application.\n- **Feature-packed**. Server-side syntax highlighting with themes, frontmatter support, table of contents in Markdown and HTML, plain text export, extraction of headings/links/images, statistics (character and word count, likely document language, blocks count), lazy image loading attributes, emoji shortcodes, autolinks, heading IDs with Unicode-transliterated slugs, wikilinks, footnotes, tables, task lists, smart punctuation, hard wraps, \"nofollow/noopener\" on external links.\n- **AI-first**. Two chunking primitives: heading-based with breadcrumbs and per-chunk character/word counts, and sliding-window with overlap for size-bounded chunks where headings are absent or uneven. Block-aware or word-aware truncation for context-window budgeting. Markdown-to-Markdown pipeline. Plain-text extraction for embedding models. Structured extraction of headings, images, links, code blocks—each carrying byte ranges back into the source.\n- **Security conscious**. Raw HTML denied by default. Hostname and URL-scheme allowlists for both links and images. GFM tagfilter for dangerous tags. A Rust-backed gem.\n- **Easy extension API**. Hook any element with a Ruby block—no subclassing, no intermediate AST, no HTML post-processing. Rewrite URLs, swap code blocks for your own renderer, drop subtrees, or just walk the document for analysis. Handlers fire inside the single-pass parser, so extension costs essentially nothing beyond the render itself—and far less than regexing over output HTML.\n\n**See the introductory post for background and motivation**:\n\n**[Inkmark: a very fast, feature-packed, AI-first Markdown gem for Ruby\n](https://yaroslav.io/posts/inkmark-fast-ai-first-markdown)**\n\n## Contents\n\n- [Installation](#installation)\n- [Quick start](#quick-start)\n- [Presets](#presets)\n- [Options](#options)\n- [Raw HTML](#raw-html)\n- [Host allowlists](#host-allowlists)\n- [URL scheme filtering](#url-scheme-filtering)\n- [Statistics and extraction](#statistics-and-extraction)\n- [Chunks extraction (for RAG)](#chunks-extraction-for-rag)\n- [Truncation](#truncation)\n- [Plain-text extraction](#plain-text-extraction)\n- [Markdown-to-Markdown pipeline](#markdown-to-markdown-pipeline)\n- [Event handlers](#event-handlers)\n- [Benchmarks](#benchmarks)\n- [Contributing](#contributing)\n- [Acknowledgements](#acknowledgements)\n- [License](#license)\n\n## Installation\n\n    bundle add inkmark\n\nOr in your `Gemfile`:\n\n```ruby\ngem \"inkmark\"\n```\n\nRuby 3.3+ is supported.\n\nThe gem comes precompiled, a compiler toolchain is _not_ required for installation.\n\n## Quick start\n\n```ruby\nrequire \"inkmark\"\n\n# Class-method shortcut\nInkmark.to_html(\"**hello**\")\n# =\u003e \"\u003cp\u003e\u003cstrong\u003ehello\u003c/strong\u003e\u003c/p\u003e\\n\"\n\n# Instance form\nInkmark.new(\"# Hello\").to_html\n\n# With options\nInkmark.to_html(\"hi \u003cem\u003ethere\u003c/em\u003e\", options: { raw_html: true })\n\n# Mutable options via accessor\ng = Inkmark.new(\"# Table\\n\\n| a | b |\\n|---|---|\\n| 1 | 2 |\")\ng.options.tables = false\ng.to_html  # tables render as paragraphs now\n```\n\n## Presets\n\nInkmark ships presets as opinionated shortcuts for common\nrendering profiles. Pass one via `preset:` in the options hash; every\nother option in the hash overrides the preset's values (deep-merging\nfor nested element-policy hashes). You can—and are recommended to!—override preset options as you see fit.\n\n- **`:recommended`**: a curated profile for modern web content. On\n  top of GFM, enables smart punctuation, auto heading IDs, lazy-loading\n  images with an `http`/`https` scheme allowlist, autolinks,\n  `rel=\"nofollow noopener\"` on external links, a scheme allowlist for\n  link destinations, emoji shortcodes, syntax highlighting, hard wraps,\n  and frontmatter parsing.\n\n  **This is a good starting point for most apps**. Still, you are expected to\n  override individual options to match your specific needs (e.g. adding statistics and table of contents, tightening link/image allowlists to your own hostnames, turning off features you don't want).\n\n- **`:trusted`**: `:recommended` plus raw HTML pass-through.\n  **Dangerous.** Intended only for content you fully trust: internal,\n  team-authored. With raw HTML on, Inkmark does no sanitization beyond\n  the narrow GFM tagfilter (turn it off at your own risk); the caller is\n  responsible for output safety. Do not apply this preset to anything a user can influence, directly or indirectly.\n\n- **`:gfm`**: the bare default. CommonMark plus the core GFM extensions\n  (tables, strikethrough, tasklists, footnotes, tagfilter). Strict,\n  conservative, and matches the render profile of every other major\n  GFM engine. Everything else is off.\n\n- **`:commonmark`**: the minimum. Strict CommonMark. No GFM extensions, no\n  typographics, nothing opinionated.\n\n```ruby\n# Recommended profile\nInkmark.to_html(md, options: { preset: :recommended })\n\n# Recommended profile with stats and table of contents\nInkmark.to_html(md, options: { preset: :recommended, statistics: true, toc: true })\n\n# Recommended profile, but disable smart punctuation\nInkmark.to_html(md, options: { preset: :recommended, smart_punctuation: false })\n\n# Just GFM (the default)\nInkmark.to_html(md)\nInkmark.to_html(md, options: { preset: :gfm })     # equivalent\n\n# Recommended profile with a tightened link-host allowlist\nInkmark.to_html(md, options: {\n  preset: :recommended,\n  links:  { allowed_hosts: [\"*.example.com\"] }\n})\n\n# Trusted content (raw HTML passes through—use with care)\nInkmark.to_html(internal_doc, options: { preset: :trusted })\n```\n\n## Options\n\nGFM extensions are on by default; raw HTML rendering is off by default.\nPass a hash to `Inkmark.to_html` / `Inkmark.new`, or mutate an `Inkmark::Options`\ninstance via its accessors.\n\n| Key | Default | Description |\n|---|---|---|\n| `gfm` | `true` | GFM conformance mode + tables, strikethrough, tasklists, and footnotes. |\n| `gfm_tag_filter` | `true` | GFM \"Disallowed Raw HTML\" extension. When `gfm` and `raw_html` are both true, protects you from several predefined tags (`title`, `textarea`, `style`, `xmp`, `iframe`, `noembed`, `noframes`, `script`, `plaintext`). No effect when `raw_html: false`. |\n| `tables` | `true` | GFM pipe tables with optional column alignment markers (`:---`, `:---:`, `---:`). |\n| `strikethrough` | `true` | `~~text~~` renders as `\u003cdel\u003etext\u003c/del\u003e`. |\n| `tasklists` | `true` | `- [ ]` and `- [x]` render as disabled checkboxes. |\n| `footnotes` | `true` | `text[^1]` + `[^1]: body` renders as superscript links and footnote block. |\n| `raw_html` | `false` | Pass raw HTML through unescaped. Off by default for untrusted-input safety. **When enabled, the caller is fully responsible for sanitizing the output—see the [Raw HTML](#raw-html) section.** |\n| `smart_punctuation` | `false` | Convert `\"...\"` → `\"...\"`, `...` → `…`, `--` → `–`, `---` → `—`. |\n| `headings` | `{ attributes: false, ids: false }` | Heading-related policy. `:attributes` enables `# Heading {#id .klass}` Markdown inline attribute syntax; `:ids` auto-generates `id=\"slug\"` on every heading from its text, with automatic Unicode transliteration of non-English headings (duplicates get a counter suffix; user-supplied ids from `:attributes` win). Deep-merges over defaults—pass only the sub-keys you care about. |\n| `images` | `{ lazy: false, allowed_hosts: nil, allowed_schemes: nil }` | Image-related policy. `:lazy` adds `loading=\"lazy\" decoding=\"async\"` to every `\u003cimg\u003e`. `:allowed_hosts` is a glob allowlist for `\u003cimg src\u003e` hostnames (see examples; non-matching images drop to alt text). `:allowed_schemes` is a URL-scheme allowlist—typical: `[\"http\", \"https\"]` to block `data:` image URIs. Both allowlists default to `nil` (no filtering); `[]` deny-all-external. Deep-merges. |\n| `links` | `{ autolink: false, nofollow: false, allowed_hosts: nil, allowed_schemes: nil }` | Link-related policy. `:autolink` auto-links bare URLs and emails with correct boundary detection. `:nofollow` adds `rel=\"nofollow noopener\"` to external `\u003ca\u003e` tags. `:allowed_hosts` / `:allowed_schemes` are glob / scheme allowlists for `\u003ca href\u003e` (relative/anchor/mailto URLs are never filtered). Non-matching links unwrap to plain text. Deep-merges. |\n| `emoji_shortcodes` | `false` | Replace gemoji-style `:shortcode:` sequences with their emoji character (`:rocket:` → 🚀). Unknown codes and codes inside code blocks are preserved. |\n| `syntax_highlight` | `false` | Server-side syntax highlighting for fenced code blocks with a language tag. Uses the `syntect` Rust crate with CSS class output. Batteries included: pair with CSS from `Inkmark.highlight_css` for the theme stylesheet. |\n| `hard_wrap` | `false` | Treat every single newline as a hard line break (`\u003cbr /\u003e`). By default a bare `\\n` is a soft break rendered as a space. Enable for one-sentence-per-line content or when migrating from renderers that default to hard wraps. |\n| `toc` | `false` | Collect a table of contents from headings. Accepts `true` / `false` for simple enable/disable, or a Hash like `toc: { depth: 3 }` to limit which heading levels appear in the rendered TOC (h1–h3 in that example; default is no limit). Enables `Inkmark#toc` which returns a `Inkmark::Toc` value object (`#to_markdown` / `#to_html` / `#to_s`). Implicitly enables `headings: { ids: true }`. Also populates a lightweight `Inkmark#statistics` with `heading_count`. Depth affects only the rendered TOC; `heading_count`, `extracts[:headings]`, and `chunks_by_heading` still see every heading. |\n| `statistics` | `false` | Collect scalar document statistics during parsing: language detection, character/word counts, and `*_count` fields for headings, code blocks, images, links, and footnote definitions. See examples. For structured arrays of records, use `extract`. Implies `toc` and `headings: { ids: true }`. |\n| `extract` | `nil` | Hash opting into structured extraction of specific element kinds. Keys: `:images`, `:links`, `:code_blocks`, `:headings`, `:footnote_definitions`—each `true`/`false`. When set, `Inkmark#extracts` returns a Hash keyed by the requested kinds, each with an Array of record Hashes including a `:byte_range`. `extract: { headings: true }` and `toc: true` trigger each other—one heading walk powers both surfaces. |\n| `math` | `false` | Recognize `$inline$` and `$$display$$` math blocks. |\n| `definition_list` | `false` | `term\\n: definition` renders as `\u003cdl\u003e`. |\n| `superscript` | `false` | `^text^` renders as `\u003csup\u003e`. |\n| `subscript` | `false` | `~text~` renders as `\u003csub\u003e`. Conflicts with strikethrough—enable only one. |\n| `wikilinks` | `false` | `[[Page]]` and `[[Page\\|label]]` render as links. |\n| `frontmatter` | `false` | Frontmatter (YAML metadata at the start of the document). Parsed and exposed via `Inkmark#frontmatter`; the block is stripped from rendered output. |\n\nOptions can be supplied in several ways:\n\n```ruby\n# As a hash at construction\nInkmark.to_html(md, options: { math: true, tables: false })\n\n# Via mutable accessor\ng = Inkmark.new(md)\ng.options.math = true\ng.options.tables = false\ng.to_html\n\n# Process-level defaults, to set in your application initializer\nInkmark.default_options.math = true\nInkmark.new(md).to_html  # picks up the default\n```\n\nUnknown option keys raise `ArgumentError` immediately, including via the\nhash form—typos fail loudly:\n\n```ruby\nInkmark.new(\"x\", options: { taples: true })\n# =\u003e ArgumentError: unknown Inkmark option: :taples\n```\n\n## Raw HTML\n\nRaw HTML is suppressed by default. This is safe-by-default for rendering untrusted Markdown:\n\n```ruby\nInkmark.to_html(\"\u003cscript\u003ealert(1)\u003c/script\u003e\")\n# =\u003e \"\u003cp\u003e\u0026lt;script\u0026gt;alert(1)\u0026lt;/script\u0026gt;\u003c/p\u003e\\n\"\n```\n\nEnable pass-through with `raw_html: true`; _only do this for trusted\ninput_:\n\n```ruby\nInkmark.to_html(\"\u003cem\u003ekeep me\u003c/em\u003e\", options: { raw_html: true })\n# =\u003e \"\u003cp\u003e\u003cem\u003ekeep me\u003c/em\u003e\u003c/p\u003e\\n\"\n```\n\n\u003e **Your responsibility.** With `raw_html: true` you are fully\n\u003e responsible for every `\u003ctag\u003e` that reaches the HTML output. Inkmark does not\n\u003e sanitize raw HTML beyond the narrow GFM tagfilter described below—it will\n\u003e happily emit `\u003cimg onerror=\"…\"\u003e`, `\u003ca href=\"javascript:…\"\u003e`, `\u003cstyle\u003e`\n\u003e contents, and any other attack surface the source contains. Always pipe the\n\u003e output through a dedicated sanitizer (like [Loofah][] or\n\u003e [rails-html-sanitizer][]) before rendering untrusted content in a page.\n\n[Loofah]: https://github.com/flavorjones/loofah\n[rails-html-sanitizer]: https://github.com/rails/rails-html-sanitizer\n\nEven with `raw_html: true`, the **GFM tagfilter** stays on by\ndefault and escapes nine unsafe tag names—`title`, `textarea`, `style`, `xmp`,\n`iframe`, `noembed`, `noframes`, `script`, `plaintext`. This is required for GFM conformance. Opt out with `gfm_tag_filter: false` (or `gfm: false`) if you need raw pass-through of those tags—trusted input only. The tagfilter is a narrow spec-compliance pass, **not** a sanitizer—the responsibility note above still applies in full.\n\n```ruby\nInkmark.to_html(\"\u003cscript\u003ealert(1)\u003c/script\u003e\", options: { raw_html: true })\n# =\u003e \"\u003cp\u003e\u0026lt;script\u003ealert(1)\u0026lt;/script\u003e\u003c/p\u003e\\n\"\n```\n\n## Host allowlists\n\nRestrict which hostnames can appear in links and images by passing glob\npatterns. Disallowed links have their `\u003ca\u003e` tags stripped (the link text\nstays); disallowed images drop to their alt text (or disappear when alt\nis empty). Relative URLs, anchors, `mailto:`, and other non-web schemes\npass through unchanged—only `http://` / `https://` URLs are matched.\n\n```ruby\nInkmark.to_html(md, options: {\n  links:  { allowed_hosts: [\"example.com\", \"*.example.com\"] },\n  images: { allowed_hosts: [\"{cdn,static,img}.example.com\"] }\n})\n```\n\nPatterns use glob syntax (same engine as `.gitignore`), **not regex**:\n\n- `example.com`: exact host only\n- `*.example.com`: any subdomain (matches `cdn.example.com`, `a.b.example.com`; does **not** match bare `example.com`)\n- `{cdn,static}.example.com`: brace alternation for multiple explicit hosts\n- `*.{example,trusted}.com`: combine wildcards and alternation\n\nHostnames are matched case-insensitively and ports are ignored. An empty\narray `[]` blocks every external link or image while still allowing\nrelative URLs.\n\n## URL scheme filtering\n\nFor rendering untrusted Markdown, opt in to scheme allowlists to block\n`javascript:`, `data:`, and other dangerous URL schemes in links and\nimages:\n\n```ruby\nInkmark.to_html(md, options: {\n  links:  { allowed_schemes: [\"http\", \"https\", \"mailto\"] },\n  images: { allowed_schemes: [\"http\", \"https\"] }\n})\n```\n\nDisallowed links are unwrapped (text stays, `\u003ca\u003e` tags drop); disallowed\nimages drop to alt text. Relative paths, anchors, and protocol-relative\nURLs pass through—no scheme to check.\n\n```ruby\nopts = { links: { allowed_schemes: [\"http\", \"https\"] } }\n\nInkmark.to_html(\"[click](javascript:alert(1))\", options: opts)\n# =\u003e \"\u003cp\u003eclick\u003c/p\u003e\\n\"\n\nInkmark.to_html(\"![pic](data:image/svg+xml,\u003csvg/onload=evil()\u003e)\",\n               options: { images: { allowed_schemes: [\"http\", \"https\"] } })\n# =\u003e \"\u003cp\u003epic\u003c/p\u003e\\n\"   # dropped to alt text\n```\n\n**Scope:** scheme filtering applies to Markdown-emitted links and images\n(`[text](url)` / `![alt](url)`). Raw HTML `\u003ca href\u003e` / `\u003cimg src\u003e` inside\n`raw_html: true` content is *not* filtered—for that case use a\ndownstream HTML sanitizer like Loofah.\n\n**Default:** filtering is off. Full CommonMark autolink conformance is\npreserved (including uncommon schemes like `irc:` and `ftp:`). Add the\nfilter explicitly when rendering untrusted input.\n\n## Statistics and extraction\n\nInkmark collects document metadata as a side effect of the single render pass.\nTwo independent options control what's exposed:\n\n- **`statistics: true`** populates `Inkmark#statistics` with scalar counts and\n  language detection—nothing you have to iterate.\n- **`extract: { kind: true, ... }`** populates `Inkmark#extracts` with structured\n  arrays of records. Opt into only the kinds you need; unasked-for arrays are\n  never allocated.\n\n```ruby\nmd = Inkmark.new(source, options: {\n  statistics: true,\n  extract: {\n    images:               true,\n    links:                true,\n    code_blocks:          true,\n    headings:             true,\n    footnote_definitions: true\n  }\n})\nmd.to_html\n\nmd.statistics\n# =\u003e {\n#      heading_count:             2,\n#      likely_language:           \"eng\",\n#      language_confidence:       0.93,\n#      character_count:           142,\n#      word_count:                28,\n#      code_block_count:          1,\n#      image_count:               1,\n#      link_count:                2,\n#      footnote_definition_count: 1,\n#    }\n\nmd.extracts[:code_blocks]\n# =\u003e [{ lang: \"ruby\", source: \"puts \\\"hello\\\"\\n\", byte_range: 78...101 }]\n\nmd.extracts[:headings]\n# =\u003e [\n#      { level: 1, text: \"Hello World\",  id: \"hello-world\",  byte_range: 0...14 },\n#      { level: 2, text: \"Code Example\", id: \"code-example\", byte_range: 68...83 }\n#    ]\n```\n\n### Extract record shapes\n\n| Kind                      | Fields                                         |\n|---------------------------|------------------------------------------------|\n| `:images`                 | `src`, `alt`, `title`, `byte_range`            |\n| `:links`                  | `href`, `text`, `title`, `byte_range`          |\n| `:code_blocks`            | `lang`, `source`, `byte_range`                 |\n| `:headings`               | `level`, `text`, `id`, `byte_range`            |\n| `:footnote_definitions`   | `label`, `text`, `byte_range`                  |\n\n`byte_range` is an exclusive `Range` (`start...end`) pointing into the original\nsource string—slice with `source.byteslice(r.begin, r.size)` to recover the\nraw Markdown. `source` on `:code_blocks` is pulldown-cmark's pre-filter code\ncontent, so enabling `syntax_highlight: true` does not mutate it.\n\n### Mutual trigger: `toc` ↔ `extract[:headings]`\n\nOne heading walk powers both the TOC renderer and the heading extract, so the\ntwo options trigger each other. Enabling either gives you access to both\n`Inkmark#toc` (with `#to_markdown` / `#to_html`) and `Inkmark#extracts[:headings]`.\n\n```ruby\nInkmark.new(source, options: { toc: true }).extracts[:headings]\n# =\u003e [{ level: 1, text: \"Hello World\", id: \"hello-world\", byte_range: 0...14 }, ...]\n```\n\n## Chunks extraction (for RAG)\n\n`Inkmark.chunks_by_heading` splits a document by heading into an ordered\nArray of section Hashes. Each section's `:content` is **filter-applied\nMarkdown**—emoji expanded, URLs autolinked, allowlists applied—serialized\nback through pulldown-cmark. Designed as the first stage of a\nchunk → embed → retrieve pipeline.\n\n```ruby\nsections = Inkmark.chunks_by_heading(readme)\nsections.each do |s|\n  puts \"#{'#' * s[:level]} #{s[:heading]} (#{s[:id]})\"\n  puts s[:content]\nend\n```\n\nEach entry:\n\n```ruby\n{\n  heading:    \"From source\",           # String, or nil for the preamble\n  level:      3,                       # 1-6, or 0 for the preamble\n  id:         \"from-source\",           # slug, or nil for the preamble\n  breadcrumb: [\"Docs\", \"Installation\"], # ancestor heading texts, root to parent\n  content:    \"Run `bundle install`...\\n\"  # filter-applied Markdown\n}\n```\n\nSections are **hierarchical**: a `##` section's `:content` includes any\nnested `###` subsections, which also appear as their own entries. Content\nbefore the first heading (if any) becomes a preamble entry with\n`heading: nil` and `level: 0`.\n\n`:breadcrumb` carries the ancestor heading texts from root to immediate\nparent. Root-level sections and the preamble have an empty array. Skipped\nlevels are omitted, so an `###` directly under an `#` has `breadcrumb:\n[\"Top\"]`, not `[\"Top\", nil]`. RAG pipelines typically prepend the\nbreadcrumb to each chunk before embedding—it gives the vector model a\ncheap signal about the chunk's place in the document.\n\nEnable `statistics: true` to add `:character_count` and `:word_count` to\nevery section entry. Counts reflect the section's filter-applied text\ncontent including any code-block bodies (code is content for embedding\npurposes, not just prose). Numbers across sections won't sum to the\ndocument total because sections overlap hierarchically—a parent section's\ncount includes its nested subsections.\n\n```ruby\nInkmark.chunks_by_heading(doc, options: {statistics: true})\n# =\u003e [\n#   { heading: \"Installation\", level: 2, id: \"installation\",\n#     breadcrumb: [\"Intro\"],\n#     character_count: 180, word_count: 32,\n#     content: \"...\" },\n#   ...\n# ]\n```\n\n```ruby\nInkmark.chunks_by_heading(readme).each do |s|\n  next if s[:heading].nil?  # skip preamble\n  context = (s[:breadcrumb] + [s[:heading]]).join(\" \u003e \")\n  embed_and_store(\"#{context}\\n\\n#{s[:content]}\", metadata: {id: s[:id]})\nend\n```\n\n### Picking specific sections\n\n`chunks_by_heading` always returns the full array. Use plain `Enumerable`\nto slice it however you need:\n\n```ruby\nsections = Inkmark.chunks_by_heading(readme)\n\n# Find one by heading text\nsections.find { |s| s[:heading] == \"Installation\" }\n\n# Filter by regexp\nsections.select { |s| s[:heading]\u0026.match?(/install|usage/i) }\n\n# All top-level headings only\nsections.select { |s| s[:level] == 1 }\n\n# Skip the preamble\nsections.reject { |s| s[:heading].nil? }\n```\n\nNo filter kwarg on the method—`.select` / `.find` / `.reject` already\ncover every filtering shape, and you can compose conditions freely\n(heading AND level, or heading NOT in a blocklist, etc.). The preamble\nis a regular entry with `heading: nil` and falls out of Regexp/String\nfilters naturally (`nil == \"Foo\"` is false; `nil\u0026.match?(x)` is nil).\n\n### RAG pipeline caveat: HTML-emitting filters\n\n**Disable `syntax_highlight`, `images: { lazy: true }`, and `links: { nofollow: true }`\nwhen chunking for RAG.** These filters embed raw `\u003cpre\u003e…`, `\u003cimg loading=…\u003e`,\nand `\u003ca rel=…\u003e` HTML into the serialized Markdown; the HTML noise hurts\nembedding quality for downstream semantic search.\n\n```ruby\nsections = Inkmark.chunks_by_heading(doc, options: {\n  emoji_shortcodes: true,    # keep—improves semantic signal\n  links: {\n    autolink:        true,                # keep—proper anchor Markdown\n    allowed_schemes: %w[http https mailto], # keep—safe URLs\n    nofollow:        false                 # off—would embed \u003ca rel=...\u003e HTML\n  },\n  images: { lazy: false },   # off—would embed \u003cimg loading=...\u003e HTML\n  syntax_highlight: false    # off—would embed \u003cpre\u003e\u003cspan...\u003e HTML\n})\n```\n\n### Scope\n\n`chunks_by_heading` is a **structural chunking primitive**, not a\ncomplete RAG chunker. It splits a document along heading boundaries.\nFor documents without headings—or when you need a strict size\nbudget regardless of document structure—reach for\n[`chunks_by_size`](#sliding-window-chunking) below.\n\nInkmark does not ship token-based budgeting (there is no embedded\ntokenizer). Use `character_count` / `word_count` or your own tokenizer\nto approximate. Prepending document titles or parent-heading\nbreadcrumbs to each chunk is a few lines of Ruby on top of the array\nthis method returns.\n\n### Sliding-window chunking\n\n`Inkmark.chunks_by_size` splits a document into fixed-size chunks with\noptional overlap, walking the filter-applied Markdown sequentially. Use\nthis when headings are absent or uneven, or when you need a strict\nsize budget for embedding input.\n\n```ruby\n# Char-budgeted windows with overlap\nInkmark.chunks_by_size(doc, chars: 500, overlap: 50)\n\n# Word budget, word-boundary cuts\nInkmark.chunks_by_size(doc, words: 120, overlap: 15, at: :word)\n\n# Dual budget: cut at whichever is reached first\nInkmark.chunks_by_size(doc, chars: 1000, words: 200)\n```\n\nEach window:\n\n```ruby\n{\n  index:   0,         # 0-based sequence position\n  content: \"...\"      # filter-applied Markdown slice\n  # character_count, word_count added when options: { statistics: true }\n}\n```\n\n**Boundary modes.** `at: :block` (default) cuts only between top-level\nMarkdown blocks—output stays valid Markdown, and a single block that\nexceeds the budget is emitted as its own window rather than silently\ndropped. `at: :word` serializes the full filtered Markdown and cuts at\nthe last Unicode word boundary that fits—tighter fit but may split\nopen constructs.\n\n**Overlap.** Measured in chars. Each new window begins with the\ntrailing `overlap` chars of the previous window, so adjacent chunks\nshare context—useful when an embedding model's attention benefits\nfrom neighbor overlap. Must be less than `chars:` when both are set.\n\n**Validation.** `chars` or `words` required (at least one). Both must\nbe positive. `overlap` defaults to 0, must be non-negative, and must be\nless than `chars` when `chars` is set. Invalid combinations raise\n`ArgumentError` at the Ruby boundary—silent clamping would mask\nbugs like swapped args.\n\n#### Heading vs size: which to use\n\n`chunks_by_heading` for docs where headings encode meaningful\nstructure (articles, specs, READMEs). Each chunk carries heading,\nlevel, id, and breadcrumb metadata—retrieval benefits from that\ncontext.\n\n`chunks_by_size` for unstructured or uneven-heading docs, or when a\nhard size ceiling matters more than document structure. No structural\nmetadata; windows are just positioned slices.\n\nYou can compose them for a hybrid \"heading-based, but size-capped\"\npattern:\n\n```ruby\nInkmark.chunks_by_heading(doc).flat_map do |c|\n  if c[:content].size \u003e 2000\n    Inkmark.chunks_by_size(c[:content], chars: 500, overlap: 50)\n  else\n    [c]\n  end\nend\n```\n\n## Truncation\n\n`Inkmark.truncate_markdown` caps a document at a character and/or word\nbudget, cutting at either a Markdown block boundary (valid structure) or\na Unicode word boundary (tighter fit, may split an open construct).\nDesigned for LLM context-window budgeting and RAG chunk normalization.\n\n```ruby\n# Block-boundary cut: last complete block that fits, output is valid Markdown\nInkmark.truncate_markdown(doc, chars: 4000, at: :block)\n\n# Word-boundary cut: last word that fits, output may split open constructs\nInkmark.truncate_markdown(doc, chars: 4000, at: :word)\n\n# Dual budget: cut at whichever limit is hit first\nInkmark.truncate_markdown(doc, chars: 4000, words: 500, at: :word)\n\n# Suppress the marker\nInkmark.truncate_markdown(doc, chars: 4000, at: :block, marker: nil)\n\n# Custom marker\nInkmark.truncate_markdown(doc, chars: 4000, at: :block, marker: \"[…]\")\n```\n\nDefault marker is `\"…\"`. When appended, it counts toward the\nbudget—`chars: 4000` always yields output ≤ 4000 codepoints.\n\n**Behavior:**\n\n- **Source fits the budget**: returned unchanged (no marker).\n- **First block alone exceeds the budget** (block mode): empty string.\n  Honest to \"no block fits\"; fall through to word-mode truncation if you\n  want a best-effort cut.\n- **Marker too large for the budget**: raises `ArgumentError`.\n- **Filter pipeline**: `emoji_shortcodes`, `links: { autolink: true }`, host/scheme\n  allowlists etc. run before truncation, so the measured output matches\n  what downstream tools consume.\n\n### Per-section truncation\n\n`chunks_by_heading` accepts a `truncate:` kwarg that applies the same\ncontract to every section's `:content` independently:\n\n```ruby\nInkmark.chunks_by_heading(doc, truncate: {chars: 500, at: :block})\n```\n\nEach section's content is cut to the 500-char budget; metadata\n(`:heading`, `:level`, `:id`, `:breadcrumb`) stays intact. When\n`statistics: true` is also set, `:character_count` / `:word_count` are\nrecomputed against the truncated content.\n\n```ruby\nInkmark.chunks_by_heading(doc,\n  options: {statistics: true},\n  truncate: {chars: 500, at: :block, marker: \"…\"}\n)\n# =\u003e each entry: { heading:, level:, id:, breadcrumb:,\n#                  character_count:, word_count:, content: (≤ 500 chars) }\n```\n\nBecause sections are hierarchical (a parent section's `:content`\nincludes nested subsections), applying the same budget to every entry\nmeans each chunk stands alone as a self-contained, budget-capped unit.\n\n## Plain-text extraction\n\n`Inkmark#to_plain_text` strips all Markdown syntax and returns inline content as\nplain text. Designed for embedding models, token counting, LLM input, and any\ndownstream consumer that treats Markdown formatting as noise.\n\n```ruby\nInkmark.to_plain_text(\"**bold** and [a link](https://example.com)\")\n# =\u003e \"bold and a link (https://example.com)\\n\"\n\ng = Inkmark.new(source, options: { emoji_shortcodes: true, links: { autolink: true } })\ng.to_plain_text\n```\n\nThe same event-level filters (emoji replacement, autolink, host/scheme\nallowlists, etc.) run before plain-text serialization, so preprocessing passes\napply consistently across `to_html`, `to_markdown`, and `to_plain_text`.\n\n### Output grammar\n\n| Element | Plain-text form |\n|---|---|\n| `**bold**`, `*italic*`, `~~strike~~` | inner text only |\n| `` `code` `` | inner text (no backticks) |\n| `[text](url)` | `text (url)` |\n| `\u003chttps://x.com\u003e` (autolink) | `https://x.com` (collapses when text == url) |\n| `![alt](src)` | `alt (src)` |\n| `# Heading` | plain text with blank line above/below |\n| `\u003e quote` | every line prefixed with `\u003e ` (email-style; nests) |\n| `- item` / `1. item` | `- ` / `1. ` bullets; 2-space indent per nesting |\n| `- [x] task` | `- task` (checkbox dropped) |\n| tables | header row `\\t`-joined, blank line, body rows `\\t`-joined |\n| ``` ```code``` ``` | raw content, blank line above/below |\n| `---` | `---` surrounded by blank lines |\n| `[^foo]` | `[foo]` |\n| `[^foo]: body` | appended at document end as `[foo]: body` |\n| soft break | space |\n| hard break | `\\n` |\n| raw HTML | stripped by default; passes through when `raw_html: true` |\n\nBlank lines inside a blockquote emit a bare `\u003e` marker (matching email quoting\nconventions; no trailing whitespace).\n\n## Markdown-to-Markdown pipeline\n\n`Inkmark#to_markdown` runs the same event-level filter pipeline as `to_html` and\nserializes the result back to Markdown text. Use it as a preprocessing step in\npipelines that consume Markdown: LLM prompts, secondary renderers, content\nstorage, or any stage that needs clean Markdown rather than HTML.\n\n```ruby\n# Class-method shortcut\nInkmark.to_markdown(\"**bold** :rocket:\", options: { emoji_shortcodes: true })\n# =\u003e \"**bold** 🚀\"\n\n# Instance form—the same options object drives both outputs\ng = Inkmark.new(source, options: {\n  emoji_shortcodes: true,\n  links: { allowed_hosts: [\"trusted.com\", \"*.trusted.com\"] }\n})\ng.to_markdown   # filtered Markdown for pipeline\ng.to_html       # rendered HTML for display\n```\n\n### Choosing filters for a Markdown pipeline\n\nInkmark's filters fall into two groups depending on what they emit:\n\n**Markdown-native filters** transform the event stream without producing HTML.\nTheir output is standard Markdown and is safe to pass to any downstream\nconsumer:\n\n| Filter | Effect in `to_markdown` |\n|---|---|\n| `emoji_shortcodes` | `:rocket:` → `🚀` in the output text |\n| `links: { autolink: true }` | bare `https://x.com` → `[https://x.com](https://x.com)` |\n| `links: { allowed_hosts:, allowed_schemes: }` | disallowed links unwrapped to plain text |\n| `images: { allowed_hosts:, allowed_schemes: }` | disallowed images dropped to alt text |\n| `smart_punctuation` | `\"...\"` → `\"…\"` etc. (text-only transformation) |\n\n**HTML-emitting filters** synthesize raw `\u003c...\u003e` markup. When these are active\nand you call `to_markdown`, that markup is embedded verbatim in the output. Raw\nHTML blocks are valid CommonMark, but they may break or confuse downstream\nconsumers—especially LLMs and renderers that do not expect HTML inside\nMarkdown:\n\n| Filter | What ends up in the Markdown |\n|---|---|\n| `syntax_highlight` | fenced code blocks become `\u003cpre\u003e\u003ccode\u003e\u003cspan class=...\u003e` HTML |\n| `images: { lazy: true }` | images become `\u003cimg loading=\"lazy\" decoding=\"async\" ...\u003e` HTML |\n| `links: { nofollow: true }` | links become `\u003ca rel=\"nofollow noopener\" ...\u003e` HTML |\n\n**Recommendation:** disable HTML-emitting filters when calling `to_markdown`.\nThey are designed for final HTML output and produce hard-to-process markup in a\nMarkdown pipeline:\n\n```ruby\nInkmark.to_markdown(source, options: {\n  # Markdown-native—safe to enable\n  emoji_shortcodes: true,\n  links:  { allowed_schemes: %w[http https mailto], nofollow: false },\n  images: { lazy: false },\n\n  # HTML-emitting—turn off for clean Markdown output\n  syntax_highlight: false,         # would embed \u003cpre\u003e\u003cspan...\u003e blocks\n})\n```\n\n## Event handlers\n\nRegister handlers with `#on` to inspect or transform document elements as they\nare parsed. Handlers fire **post-order**—children before parents—so when a\n`:table` handler runs, its rows and cells are already available. Returns `self`\nfor chaining.\n\n```ruby\nmd = Inkmark.new(source)\n\nmd.on(:heading) { |h| ... }\n  .on(:image)   { |img| ... }\n  .on(:link)    { |l| ... }\n```\n\nTwo entry points trigger handlers:\n\n- **`#walk`**—fires handlers without producing HTML. Use it for analysis:\n  collecting specific elements, validating content, extracting structured data.\n  For built-in heading/link/image/word-count collection, see `statistics: true`.\n- **`#to_html`**—fires handlers then renders. Mutations made inside a handler\n  change what ends up in the HTML.\n\n### Collecting data with `#walk`\n\n```ruby\n# Check that every image has alt text\nmd = Inkmark.new(source)\nmissing_alt = []\nmd.on(:image) { |img| missing_alt \u003c\u003c img.dest if img.text.empty? }\nmd.walk\nraise \"Images missing alt text: #{missing_alt.join(', ')}\" if missing_alt.any?\n```\n\n```ruby\n# Collect every fenced code block language used in the document\nlanguages = Set.new\nmd.on(:code_block) { |c| languages \u003c\u003c c.lang if c.lang \u0026\u0026 !c.lang.empty? }\nmd.walk\n```\n\n```ruby\n# Validate that no link points to a deprecated domain\ndeprecated = /old-docs\\.example\\.com/\nmd.on(:link) { |l| warn \"Deprecated link: #{l.dest}\" if l.dest =~ deprecated }\nmd.walk\n```\n\n### Rewriting output with `#to_html`\n\n#### Image CDN rewriting\n\nSet `dest=` to redirect images to a CDN. The change is reflected in the\nrendered `\u003cimg src\u003e`:\n\n```ruby\nmd = Inkmark.new(source)\nmd.on(:image) do |img|\n  img.dest = \"https://cdn.example.net/#{File.basename(img.dest)}\"\nend\nhtml = md.to_html\n```\n\n#### Rewriting link destinations\n\n```ruby\nmd.on(:link) do |l|\n  if l.dest.start_with?(\"http\")\n    l.html = %(\u003ca href=\"#{l.dest}\" target=\"_blank\" rel=\"noopener\"\u003e#{l.text}\u003c/a\u003e)\n  end\nend\n```\n\n#### Shifting heading levels\n\nBump every heading down one level so the document fits inside a layout that\nreserves `\u003ch1\u003e` for the page title:\n\n```ruby\nmd = Inkmark.new(source)\nmd.on(:heading) { |h| h.level = [h.level + 1, 6].min }\nhtml = md.to_html\n```\n\n#### Custom code block rendering\n\nIntercept fenced code blocks by language tag. Setting `html=` skips Inkmark's\ndefault `\u003cpre\u003e\u003ccode\u003e` output—and the `syntax_highlight` filter, even if\nenabled:\n\n```ruby\nmd = Inkmark.new(source)\nmd.on(:code_block) do |c|\n  case c.lang\n  when \"mermaid\"\n    c.html = %(\u003cdiv class=\"mermaid\"\u003e#{c.text}\u003c/div\u003e\\n)\n  when \"math\"\n    c.html = %(\u003cdiv class=\"math\"\u003e\\\\[#{c.text}\\\\]\u003c/div\u003e\\n)\n  end\nend\nhtml = md.to_html\n```\n\n#### Custom directives in paragraphs\n\nMatch a special directive syntax and replace the paragraph with a component:\n\n```ruby\n# Markdown:\n#   @available_since rails=7.1 ruby=3.2\n#\nmd.on(:paragraph) do |p|\n  next unless p.text =~ /\\A@available_since\\s+(.+)\\z/\n  attrs = $1.scan(/(\\w+)=(\\S+)/).map { |k, v| %( #{k}=\"#{v}\") }.join\n  p.html = %(\u003cAvailableSince#{attrs} /\u003e\\n)\nend\n```\n\n#### Replacing with Markdown\n\nUse `markdown=` when the replacement is itself Markdown rather than raw HTML.\nThe replacement is parsed with the same options as the main document—emoji\nexpansion, heading IDs, raw HTML suppression—and is subject to the same\npost-render filters (`syntax_highlight`, allowlists, `images: { lazy: true }`, `links: { nofollow: true }`).\nHandlers do **not** fire on elements within the replacement.\n`html=` takes priority when both are set on the same event.\n\n```ruby\nmd = Inkmark.new(source)\nmd.on(:paragraph) do |p|\n  if p.text.start_with?(\"@note \")\n    body = p.text.sub(/\\A@note /, \"\")\n    p.markdown = \"\u003e **Note:** #{body}\"\n  end\nend\nhtml = md.to_html\n```\n\n#### Suppressing elements\n\nCall `delete` on any event to omit it from the output. Children are suppressed\nalong with their parent:\n\n```ruby\nmd.on(:image)   { |img| img.delete }                                  # all images\nmd.on(:heading) { |h|   h.delete if h.text.start_with?(\"INTERNAL:\") } # by content\n```\n\n#### Inline code annotation\n\n`:code` fires for inline backtick spans. Use it to add links or decoration:\n\n```ruby\nmd.on(:code) do |c|\n  if c.text =~ /\\A[A-Z][A-Za-z]+#\\w+\\z/    # e.g. String#split\n    c.html = %(\u003ca href=\"/api/#{c.text.tr('#', '/')}\"\u003e\u003ccode\u003e#{c.text}\u003c/code\u003e\u003c/a\u003e)\n  end\nend\n```\n\n### Children and tree context\n\nContainer elements expose their child events (lazy, cached):\n\n```ruby\nmd.on(:table) do |t|\n  rows = t.children_of(:table_row)\n  rows.each_with_index do |row, i|\n    cells = row.children_of(:table_cell).map(\u0026:text)\n    puts \"Row #{i}: #{cells.join(' | ')}\"\n  end\nend\n```\n\nUse `parent_kind` and `ancestor_kinds` for context-sensitive decisions:\n\n```ruby\n# Skip decorative images that are already inside a link\nmd.on(:image) { |img| img.delete if img.ancestor_kinds.include?(:link) }\n\n# Only process top-level paragraphs\nmd.on(:paragraph) do |p|\n  next unless p.parent_kind.nil?\n  # ... only top-level paragraphs reach here\nend\n```\n\n`depth` gives the nesting level (0 = top-level block):\n\n```ruby\nmd.on(:blockquote) { |b| puts \"blockquote at depth #{b.depth}\" }\nmd.on(:paragraph)  { |p| puts \"paragraph at depth #{p.depth}\" }\n# A paragraph inside a blockquote has depth 1.\n```\n\n### Source byte ranges\n\n`byte_range` is an exclusive Ruby Range (`start...end`) that lets you slice the\noriginal source to recover the raw Markdown for any element:\n\n```ruby\nsource = File.read(\"post.md\")\nmd = Inkmark.new(source)\nmd.on(:heading) do |h|\n  puts \"#{h.byte_range}: #{source.byteslice(h.byte_range).inspect}\"\nend\nmd.walk\n```\n\nPopulated for all container kinds and the leaf kinds `:code`, `:rule`,\n`:inline_math`, `:display_math`. Returns `nil` for `:text`, `:soft_break`,\nand `:hard_break`. Also `nil` for `:link` when `links: { autolink: true }` is enabled\n(the autolink filter inserts new link events that would shift the offset queue).\n\n### Event object reference\n\nEvery handler receives an `Inkmark::Event` with these fields and methods:\n\n| Field / method | Type | Description |\n|---|---|---|\n| `kind` | `Symbol` | Element kind, e.g. `:heading`, `:image` |\n| `text` | `String` | Plain text of all descendant text nodes |\n| `depth` | `Integer` | Nesting depth; 0 = top-level block |\n| `parent_kind` | `Symbol, nil` | Kind of the immediate parent, or `nil` at root |\n| `ancestor_kinds` | `Array\u003cSymbol\u003e` | Ancestor kinds, nearest first |\n| `byte_range` | `Range, nil` | Byte offsets in the original source string |\n| `children` | `Array\u003cEvent\u003e` | Direct child events (containers only) |\n| `children_of(kind)` | `Array\u003cEvent\u003e` | Children filtered by kind |\n| `delete` |—| Suppress this element from output |\n| `deleted?` | `Boolean` | True if `delete` was called |\n| `html=` | `String, nil` | Replace output with a raw HTML string |\n| `markdown=` | `String, nil` | Replace output by re-rendering a Markdown string |\n| `dest=` | `String, nil` | Rewrite URL on `:link` / `:image` |\n| `title=` | `String, nil` | Rewrite title attribute on `:link` / `:image` |\n| `level=` | `Integer, nil` | Change heading level (1–6) on `:heading` |\n| `id=` | `String, nil` | Change `id` attribute on `:heading` |\n\n#### Per-kind field availability\n\n**Container kinds**: handler fires after all children are processed:\n\n| Kind | Readable | Mutable |\n|---|---|---|\n| `:heading` | `text`, `level`, `id` | `level=`, `id=`, `html=`, `markdown=` |\n| `:paragraph` | `text` | `html=`, `markdown=` |\n| `:blockquote` | `text` | `html=`, `markdown=` |\n| `:list` |—| `html=`, `markdown=` |\n| `:ordered_list` |—| `html=`, `markdown=` |\n| `:list_item` | `text` | `html=`, `markdown=` |\n| `:code_block` | `text` (alias `source`), `lang` | `html=`, `markdown=` |\n| `:table` |—| `html=`, `markdown=` |\n| `:table_head` |—| `html=`, `markdown=` |\n| `:table_row` | `text` | `html=`, `markdown=` |\n| `:table_cell` | `text` | `html=`, `markdown=` |\n| `:emphasis` | `text` | `html=`, `markdown=` |\n| `:strong` | `text` | `html=`, `markdown=` |\n| `:strikethrough` | `text` | `html=`, `markdown=` |\n| `:link` | `text`, `dest`, `title` | `dest=`, `title=`, `html=`, `markdown=` |\n| `:image` | `text` (alt), `dest`, `title` | `dest=`, `title=`, `html=`, `markdown=` |\n| `:footnote_definition` | `text` | `html=`, `markdown=` |\n\n**Leaf kinds**: no children; handler fires on the event itself:\n\n| Kind | Readable | Mutable |\n|---|---|---|\n| `:code` | `text` | `html=` |\n| `:text` | `text` | `html=` |\n| `:html` | `text` | `html=` |\n| `:rule` |—| `html=` |\n| `:soft_break` |—| `html=` |\n| `:hard_break` |—| `html=` |\n| `:footnote_reference` | `text` | `html=` |\n\nAll kinds expose `depth`, `parent_kind`, `ancestor_kinds`, `byte_range`,\n`children`, `children_of`, `delete`, `deleted?`.\n\n`:code_block` `text` and `source` are identical—`source` is an alias for\nreadability when treating the field as raw source code.\n\n### Filter interaction\n\nEnrichment filters run **before** handlers. Handlers always see:\n\n- Emoji already resolved (`emoji_shortcodes: true`)—`h.text` contains `\"🚀\"`,\n  not `\":rocket:\"`\n- Bare URLs already autolinked (`links: { autolink: true }`)—they appear as `:link` events\n- Heading `id` already set (`headings: { ids: true }`)—`h.id` is populated\n\nPost-render filters (`syntax_highlight`, allowlists, `images: { lazy: true }`,\n`links: { nofollow: true }`) run **after** handlers:\n\n- `:code_block` events are still `:code_block`, not opaque HTML, even when\n  `syntax_highlight: true`—setting `html=` on a code block overrides the\n  highlighter\n- Handler-set `dest=` values pass through host and scheme allowlists\n\n## Benchmarks\n\nInkmark ships a benchmark harness comparing it against `kramdown`,\n`commonmarker`, `redcarpet`, `markly`, and `rdiscount` on a sweep of real\nMarkdown inputs.\n\nMeasuring apples to apples: every adapter is tuned for **feature parity** with\nInkmark's defaults—CommonMark + core GFM (tables, strikethrough, tasklists,\nfootnotes, tagfilter), no typographics, no autolink, no syntax highlighting,\nno heading-id slugging.\n\nRun locally:\n\n```bash\nbundle config set with benchmark\nbundle install\nbundle exec rake benchmark\n```\n\n### Assets\n\n| Asset | Size | What it exercises |\n|---|---:|---|\n| `commonmark-spec` | 201.3 KB | CommonMark spec—code-block-heavy, edge-case-heavy |\n| `commonmarker-readme` | 17.0 KB | Real-world commonmarker README—options tables, fenced code |\n| `redcarpet-readme` | 14.0 KB | Real-world redcarpet README—prose + code samples |\n| `redcarpet-benchmark` | 8.0 KB | Classic redcarpet bench corpus—heavy emphasis / inline parsing |\n| `large-4k` | 3.7 KB | dotenv README—mixed prose, code blocks, tables |\n| `medium-1k` | 1.0 KB | Faraday README header—images, badges, inline links |\n| `small-512b` | 0.5 KB | Short README section with headings and bullet lists |\n| `tiny-256b` | 0.3 KB | 3-line CommonMark snippet—parser setup/overhead-bound |\n\nSee `benchmarks/NOTICE` for attribution on the vendored test inputs.\n\n### Results\n\nNumbers below are from AWS EC2 `c7a.large` (AMD EPYC), Ruby 4.0.2 with YJIT on.\nEach engine uses its idiomatic \"hot path\"—Inkmark relies on its cached default\noptions, Redcarpet reuses one pre-built `Markdown` object. Iterations per\nsecond, higher is better.\n\n**`commonmark-spec` (201.3 KB)**\n```\ninkmark:        1,172 i/s\nredcarpet:        908 i/s -  1.29x slower\nmarkly:           453 i/s -  2.59x slower\ncommonmarker:     345 i/s -  3.40x slower\nrdiscount:        212 i/s -  5.53x slower\nkramdown:          26 i/s - 45.08x slower\n```\n\n**`commonmarker-readme` (16.9 KB)**\n```\ninkmark:       16,658 i/s\nredcarpet:     12,988 i/s -   1.28x slower\ncommonmarker:   4,268 i/s -   3.90x slower\nmarkly:         3,974 i/s -   4.19x slower\nrdiscount:      2,676 i/s -   6.22x slower\nkramdown:         113 i/s - 147.42x slower\n```\n\n**`redcarpet-readme` (14.0 KB)**\n```\ninkmark:       17,343 i/s\nredcarpet:     13,587 i/s -  1.28x slower\nmarkly:         5,455 i/s -  3.18x slower\ncommonmarker:   4,890 i/s -  3.55x slower\nrdiscount:      3,336 i/s -  5.20x slower\nkramdown:         208 i/s - 83.38x slower\n```\n\n**`redcarpet-benchmark` (8.0 KB)**\n```\ninkmark:       27,634 i/s\nredcarpet:     23,777 i/s -  1.16x slower\nmarkly:         9,346 i/s -  2.96x slower\ncommonmarker:   7,805 i/s -  3.54x slower\nrdiscount:      6,201 i/s -  4.46x slower\nkramdown:         367 i/s - 75.30x slower\n```\n\n**`large-4k` (3.7 KB)**\n```\ninkmark:       64,051 i/s\nredcarpet:     58,420 i/s -   1.10x slower\nmarkly:        22,500 i/s -   2.85x slower\ncommonmarker:  18,053 i/s -   3.55x slower\nrdiscount:     13,839 i/s -   4.63x slower\nkramdown:         624 i/s - 102.64x slower\n```\n\n**`medium-1k` (1.0 KB)**\n```\nredcarpet:    216,968 i/s\ninkmark:      213,478 i/s -  1.02x slower\nmarkly:        70,251 i/s -  3.09x slower\ncommonmarker:  46,357 i/s -  4.68x slower\nrdiscount:     45,880 i/s -  4.73x slower\nkramdown:       2,813 i/s - 77.13x slower\n```\n\n**`small-512b` (0.5 KB)**\n```\ninkmark:      388,266 i/s\nredcarpet:    368,401 i/s -  1.05x slower\nrdiscount:     74,032 i/s -  5.24x slower\nmarkly:        61,175 i/s -  6.35x slower\ncommonmarker:  46,658 i/s -  8.32x slower\nkramdown:       3,952 i/s - 98.25x slower\n```\n\n**`tiny-256b` (0.3 KB)**\n```\nredcarpet:    535,972 i/s\ninkmark:      511,019 i/s -   1.05x slower\nrdiscount:     99,001 i/s -   5.41x slower\nmarkly:        96,159 i/s -   5.57x slower\ncommonmarker:  57,704 i/s -   9.29x slower\nkramdown:       4,117 i/s - 130.18x slower\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at\nhttps://github.com/yaroslav/inkmark.\n\n## Acknowledgements\n\nInkmark is built with:\n\n[pulldown-cmark](https://github.com/pulldown-cmark/pulldown-cmark) by Raph Levien, Marcus Klaas de Vries, Martín Pozo, Michael Howell, Roope Salmi and Martin Geisler;\n\n[Magnus](https://github.com/matsadler/magnus) by Matthew Sadler;\n\n[syntect](https://github.com/trishume/syntect) by Tristan Hume, Keith Hall, Google Inc and other contributors;\n\nAnd other Rust crates—thanks to their authors.\n\nThanks to Julik Tarkhanov for short but useful brainstorming sessions.\n\n## License\n\nThe gem is available as open source under the terms of the\n[MIT License](LICENSE.txt). Third-party content (benchmark assets, CommonMark\nspec) is attributed in `NOTICE` and `benchmarks/NOTICE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaroslav%2Finkmark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyaroslav%2Finkmark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaroslav%2Finkmark/lists"}