From f0c1979b1d86d4030887dc3b470456a72df8cbec Mon Sep 17 00:00:00 2001 From: icyleaf Date: Sun, 2 Mar 2025 11:10:33 +0800 Subject: [PATCH 01/15] Update 0.6.0 changelog --- CHANGELOG.md | 16 ++++- README.md | 156 +++++++++++++++++++++---------------------- shard.yml | 2 +- src/markd/version.cr | 2 +- 4 files changed, 92 insertions(+), 84 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d44291..abac6f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Full GFM support +## [0.6.0] (2025-03-?) + +Welcome new maintainer @[nobodywasishere](https://github.com/nobodywasishere) who brought support for gfm new features. + +- Add matrix platform and Cyrstal version to github action. #[59](https://github.com/icyleaf/markd/pull/59) thanks @[devnote-dev](https://github.com/devnote-dev) +- Correct version check for Crystal::VERSION. #[60](https://github.com/icyleaf/markd/pull/60) thanks @[nobodywasishere](https://github.com/nobodywasishere) +- Add GitHub emoji support. #[61](https://github.com/icyleaf/markd/pull/61) thanks @[nobodywasishere](https://github.com/nobodywasishere) +- Implement strikethrough support. #[62](https://github.com/icyleaf/markd/pull/62) thanks @[nobodywasishere](https://github.com/nobodywasishere) +- [gfm] Add tagfilter option. #[64](https://github.com/icyleaf/markd/pull/64) thanks @[nobodywasishere](https://github.com/nobodywasishere) +- [gfm] Add task list support. #[65](https://github.com/icyleaf/markd/pull/65) thanks @[nobodywasishere](https://github.com/nobodywasishere) +- Add tartrazine render code block. #[67](https://github.com/icyleaf/markd/pull/67) thanks @[zw963](https://github.com/zw963) +- [gfm] Add table support. #[72](https://github.com/icyleaf/markd/pull/72) thanks @[ralsina](https://github.com/ralsina) + ## [0.5.0] (2022-06-14) - Support CommonMark 0.29 #[50](https://github.com/icyleaf/markd/pull/50) thanks @[HertzDevil](https://github.com/HertzDevil). @@ -91,7 +104,8 @@ No changelog. - [initial implementation](https://github.com/icyleaf/markd/milestone/1?closed=1) -[Unreleased]: https://github.com/icyleaf/markd/compare/v0.5.0...HEAD +[Unreleased]: https://github.com/icyleaf/markd/compare/v0.6.0...HEAD +[0.6.0]: https://github.com/icyleaf/markd/compare/v0.5.0...v0.6.0 [0.5.0]: https://github.com/icyleaf/markd/compare/v0.4.2...v0.5.0 [0.4.2]: https://github.com/icyleaf/markd/compare/v0.4.1...v0.4.2 [0.4.1]: https://github.com/icyleaf/markd/compare/v0.4.0...v0.4.1 diff --git a/README.md b/README.md index acfa892..38c1c84 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,6 @@ [![Tag](https://img.shields.io/github/tag/icyleaf/markd.svg)](https://github.com/icyleaf/markd/blob/master/CHANGELOG.md) [![Build Status](https://img.shields.io/circleci/project/github/icyleaf/markd/master.svg?style=flat)](https://circleci.com/gh/icyleaf/markd) - -**THIS PROJECT IS LOOKING FOR MAINTAINER** - -Unfortunately, the maintainer no longer has the time and/or resources to work on markd further. This means that bugs will not be fixed and features will not be added unless someone else does so. - -If you're interested in fixing up markd, please [file an issue](https://github.com/icyleaf/markd/issues/new) let me know. -
Yet another markdown parser built for speed, written in [Crystal](https://crystal-lang.org), Compliant to [CommonMark](http://spec.commonmark.org) specification (`v0.29`). Copy from [commonmark.js](https://github.com/jgm/commonmark.js). @@ -55,9 +48,10 @@ Markd.to_html(markdown, options) | source_pos | `Bool` | false | if **true**, source position information for block-level elements
will be rendered in the data-sourcepos attribute (for HTML) | | safe | `Bool` | false | if **true**, raw HTML will not be passed through to HTML output (it will be replaced by comments) | | prettyprint | `Bool` | false | if **true**, code tags generated by code blocks will have a `prettyprint` class added to them, to be used by [Google code-prettify](https://github.com/google/code-prettify). | -| gfm | `Bool` | false | **Partial support** | -| autolink | `Bool` | false | if **true**, more autolinks are detected, like bare email addresses or http links | +| gfm | `Bool` | false | **Partial support** | +| autolink | `Bool` | false | if **true**, more autolinks are detected, like bare email addresses or http links | | toc | `Bool` | false | **Not supported for now** | +| emoji | `Bool` | false | if **true**, convert Github style emoji chars. | | base_url | `URI?` | nil | if not **nil**, relative URLs of links are resolved against this `URI`. It act's like HTML's `` in the context of a Markdown document. | ## Advanced @@ -105,13 +99,13 @@ require "markd" formatter = Tartrazine::Html.new( theme: Tartrazine.theme("emacs"), - + # Disable print line number line_numbers: false, - + # Set standalone to false for better performace. # - # You need generate css file use `bin/tartrazine -f html -t "emacs" --css`, + # You need generate css file use `bin/tartrazine -f html -t "emacs" --css`, # then link it in you site. standalone: false, ) @@ -133,75 +127,75 @@ Currently Tartrazine supports 247 languages and [331 themes](https://github.com/ ```crystal [ - "LiquidLexer", "VelocityLexer", - - "abap", "abnf", "actionscript", "actionscript_3", "ada", "agda", "al", "alloy", "angular2", - "antlr", "apacheconf", "apl", "applescript", "arangodb_aql", "arduino", "armasm", - "autohotkey", "autoit", "awk", - - "ballerina", "bash", "bash_session", "batchfile", "bbcode", "bibtex", "bicep", "blitzbasic", - "bnf", "bqn", "brainfuck", - - "c", "c#", "c++", "cap_n_proto", "cassandra_cql", "ceylon", "cfengine3", "cfstatement", - "chaiscript", "chapel", "cheetah", "clojure", "cmake", "cobol", "coffeescript", - "common_lisp", "coq", "crystal", "css", "cue", "cython", - - "d", "dart", "dax", "desktop_entry", "diff", "django_jinja", "dns", "docker", "dtd", "dylan", - - "ebnf", "elixir", "elm", "emacslisp", "erlang", - - "factor", "fennel", "fish", "forth", "fortran", "fortranfixed", "fsharp", - - "gas", "gdscript", "gdscript3", "gherkin", "gleam", "glsl", "gnuplot", "go_template", - "graphql", "groff", "groovy", - - "handlebars", "hare", "haskell", "hcl", "hexdump", "hlb", "hlsl", "holyc", "html", "hy", - - "idris", "igor", "ini", "io", "iscdhcpd", - - "j", "java", "javascript", "json", "jsonata", "julia", "jungle", - - "kotlin", - - "lighttpd_configuration_file", "llvm", "lua", - - "makefile", "mako", "markdown", "mason", "materialize_sql_dialect", "mathematica", "matlab", - "mcfunction", "meson", "metal", "minizinc", "mlir", "modula-2", "moinwiki", "monkeyc", - "morrowindscript", "myghty", "mysql", - - "nasm", "natural", "ndisasm", "newspeak", "nginx_configuration_file", "nim", "nix", - - "objective-c", "objectpascal", "ocaml", "octave", "odin", "onesenterprise", "openedge_abl", - "openscad", "org_mode", - - "pacmanconf", "perl", "php", "pig", "pkgconfig", "pl_pgsql", "plaintext", "plutus_core", - "pony", "postgresql_sql_dialect", "postscript", "povray", "powerquery", "powershell", - "prolog", "promela", "promql", "properties", "protocol_buffer", "prql", "psl", "puppet", - "python", "python_2", - - "qbasic", "qml", - - "r", "racket", "ragel", "react", "reasonml", "reg", "rego", "rexx", "rpm_spec", "rst", - "ruby", "rust", - - "sas", "sass", "scala", "scheme", "scilab", "scss", "sed", "sieve", "smali", "smalltalk", - "smarty", "snobol", "solidity", "sourcepawn", "sparql", "sql", "squidconf", "standard_ml", - "stas", "stylus", "swift", "systemd", "systemverilog", - - "tablegen", "tal", "tasm", "tcl", "tcsh", "termcap", "terminfo", "terraform", "tex", - "thrift", "toml", "tradingview", "transact-sql", "turing", "turtle", "twig", "typescript", - "typoscript", "typoscriptcssdata", "typoscripthtmldata", - - "ucode", - - "v", "v_shell", "vala", "vb_net", "verilog", "vhdl", "vhs", "viml", "vue", "wdte", - - "webgpu_shading_language", "whiley", - - "xml", "xorg", - - "yaml", "yang", "z80_assembly", - + "LiquidLexer", "VelocityLexer", + + "abap", "abnf", "actionscript", "actionscript_3", "ada", "agda", "al", "alloy", "angular2", + "antlr", "apacheconf", "apl", "applescript", "arangodb_aql", "arduino", "armasm", + "autohotkey", "autoit", "awk", + + "ballerina", "bash", "bash_session", "batchfile", "bbcode", "bibtex", "bicep", "blitzbasic", + "bnf", "bqn", "brainfuck", + + "c", "c#", "c++", "cap_n_proto", "cassandra_cql", "ceylon", "cfengine3", "cfstatement", + "chaiscript", "chapel", "cheetah", "clojure", "cmake", "cobol", "coffeescript", + "common_lisp", "coq", "crystal", "css", "cue", "cython", + + "d", "dart", "dax", "desktop_entry", "diff", "django_jinja", "dns", "docker", "dtd", "dylan", + + "ebnf", "elixir", "elm", "emacslisp", "erlang", + + "factor", "fennel", "fish", "forth", "fortran", "fortranfixed", "fsharp", + + "gas", "gdscript", "gdscript3", "gherkin", "gleam", "glsl", "gnuplot", "go_template", + "graphql", "groff", "groovy", + + "handlebars", "hare", "haskell", "hcl", "hexdump", "hlb", "hlsl", "holyc", "html", "hy", + + "idris", "igor", "ini", "io", "iscdhcpd", + + "j", "java", "javascript", "json", "jsonata", "julia", "jungle", + + "kotlin", + + "lighttpd_configuration_file", "llvm", "lua", + + "makefile", "mako", "markdown", "mason", "materialize_sql_dialect", "mathematica", "matlab", + "mcfunction", "meson", "metal", "minizinc", "mlir", "modula-2", "moinwiki", "monkeyc", + "morrowindscript", "myghty", "mysql", + + "nasm", "natural", "ndisasm", "newspeak", "nginx_configuration_file", "nim", "nix", + + "objective-c", "objectpascal", "ocaml", "octave", "odin", "onesenterprise", "openedge_abl", + "openscad", "org_mode", + + "pacmanconf", "perl", "php", "pig", "pkgconfig", "pl_pgsql", "plaintext", "plutus_core", + "pony", "postgresql_sql_dialect", "postscript", "povray", "powerquery", "powershell", + "prolog", "promela", "promql", "properties", "protocol_buffer", "prql", "psl", "puppet", + "python", "python_2", + + "qbasic", "qml", + + "r", "racket", "ragel", "react", "reasonml", "reg", "rego", "rexx", "rpm_spec", "rst", + "ruby", "rust", + + "sas", "sass", "scala", "scheme", "scilab", "scss", "sed", "sieve", "smali", "smalltalk", + "smarty", "snobol", "solidity", "sourcepawn", "sparql", "sql", "squidconf", "standard_ml", + "stas", "stylus", "swift", "systemd", "systemverilog", + + "tablegen", "tal", "tasm", "tcl", "tcsh", "termcap", "terminfo", "terraform", "tex", + "thrift", "toml", "tradingview", "transact-sql", "turing", "turtle", "twig", "typescript", + "typoscript", "typoscriptcssdata", "typoscripthtmldata", + + "ucode", + + "v", "v_shell", "vala", "vb_net", "verilog", "vhdl", "vhs", "viml", "vue", "wdte", + + "webgpu_shading_language", "whiley", + + "xml", "xorg", + + "yaml", "yang", "z80_assembly", + "zed", "zig" ] ``` diff --git a/shard.yml b/shard.yml index b6c8871..846b25b 100644 --- a/shard.yml +++ b/shard.yml @@ -1,5 +1,5 @@ name: markd -version: 0.5.0 +version: 0.6.0 authors: - icyleaf diff --git a/src/markd/version.cr b/src/markd/version.cr index d5062b5..3708604 100644 --- a/src/markd/version.cr +++ b/src/markd/version.cr @@ -1,3 +1,3 @@ module Markd - VERSION = "0.5.0" + VERSION = "0.6.0" end From 342d487ecf7098aac789c61efd4ba06840d065bf Mon Sep 17 00:00:00 2001 From: icyleaf Date: Mon, 3 Mar 2025 13:40:35 +0800 Subject: [PATCH 02/15] Update README.md Co-authored-by: Margret Riegert --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 38c1c84..eeef57b 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ Markd.to_html(markdown, options) | autolink | `Bool` | false | if **true**, more autolinks are detected, like bare email addresses or http links | | toc | `Bool` | false | **Not supported for now** | | emoji | `Bool` | false | if **true**, convert Github style emoji chars. | +| tagfilter | `Bool` | false | if **true**, escape certain HTML tags. | | base_url | `URI?` | nil | if not **nil**, relative URLs of links are resolved against this `URI`. It act's like HTML's `` in the context of a Markdown document. | ## Advanced From 110885942581f53605a527464b28574211793d56 Mon Sep 17 00:00:00 2001 From: icyleaf Date: Mon, 3 Mar 2025 13:40:53 +0800 Subject: [PATCH 03/15] Update shard.yml Co-authored-by: Margret Riegert --- shard.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/shard.yml b/shard.yml index 846b25b..755088d 100644 --- a/shard.yml +++ b/shard.yml @@ -3,6 +3,7 @@ version: 0.6.0 authors: - icyleaf + - nobodywasishere crystal: ">= 0.36.1, < 2.0.0" From ebb9b1cac605bf7d8f135dac76ec376a57e64051 Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Fri, 7 Mar 2025 16:42:39 -0300 Subject: [PATCH 04/15] feature: Footnotes --- .gitignore | 7 +- .vscode/tasks.json | 71 +++++++++++ spec/fixtures/gfm-extensions.txt | 6 +- spec/fixtures/gfm-regression.txt | 14 +- src/markd/node.cr | 52 ++++---- src/markd/parsers/block.cr | 170 +++++++++++++++++++++++-- src/markd/parsers/inline.cr | 50 +++++++- src/markd/renderer.cr | 29 +++-- src/markd/renderers/html_renderer.cr | 144 ++++++++++++++++++++- src/markd/rule.cr | 4 +- src/markd/rules/footnote_definition.cr | 64 ++++++++++ 11 files changed, 545 insertions(+), 66 deletions(-) create mode 100644 .vscode/tasks.json create mode 100644 src/markd/rules/footnote_definition.cr diff --git a/.gitignore b/.gitignore index 1bad4d9..3e99378 100644 --- a/.gitignore +++ b/.gitignore @@ -10,4 +10,9 @@ # vscode /.history/ -/.vscode/settings.json +/.vscode/ + + +# claude +CLAUDE.md +/.claude/ diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..c288689 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,71 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + }, + { + "label": "Run Crystal spec tests", + "type": "shell", + "command": "crystal spec", + "group": "test" + } + ] +} \ No newline at end of file diff --git a/spec/fixtures/gfm-extensions.txt b/spec/fixtures/gfm-extensions.txt index a5ff96d..e7de5be 100644 --- a/spec/fixtures/gfm-extensions.txt +++ b/spec/fixtures/gfm-extensions.txt @@ -704,7 +704,7 @@ Even with {"x":"y"} or 1 > 2 or whatever. Even **markdown**. ## Footnotes -```````````````````````````````` example pending +```````````````````````````````` example This is some text![^1]. Other text.[^footnote]. Here's a thing[^other-note]. @@ -764,7 +764,7 @@ Hi! ## When a footnote is used multiple times, we insert multiple backrefs. -```````````````````````````````` example pending +```````````````````````````````` example This is some text. It has a footnote[^a-footnote]. This footnote is referenced[^a-footnote] multiple times, in lots of different places.[^a-footnote] @@ -784,7 +784,7 @@ This footnote is referenced[^a-footnote] multiple times, in lots of different pl ## Footnote reference labels are href escaped -```````````````````````````````` example pending +```````````````````````````````` example Hello[^">] [^">]: pwned diff --git a/spec/fixtures/gfm-regression.txt b/spec/fixtures/gfm-regression.txt index b611a0c..a65a717 100644 --- a/spec/fixtures/gfm-regression.txt +++ b/spec/fixtures/gfm-regression.txt @@ -167,7 +167,7 @@ This ~text~ ~~is~~ ~~~curious~~~. Footnotes in tables -```````````````````````````````` example table footnotes pending +```````````````````````````````` example table footnotes A footnote in a paragraph[^1] | Column1 | Column2 | @@ -273,7 +273,7 @@ Pull request #128 - Buffer overread in tables extension Footnotes may be nested inside other footnotes. -```````````````````````````````` example footnotes pending +```````````````````````````````` example footnotes This is some text. It has a citation.[^citation] [^another-citation]: My second citation. @@ -295,7 +295,7 @@ This is some text. It has a citation.[^citation] Footnotes are similar to, but should not be confused with, link references -```````````````````````````````` example footnotes pending +```````````````````````````````` example footnotes This is some text. It has two footnotes references, side-by-side without any spaces,[^footnote1][^footnote2] which are definitely not link references. [^footnote1]: Hello. @@ -317,7 +317,7 @@ This is some text. It has two footnotes references, side-by-side without any spa Footnotes may begin with or have a 'w' or a '_' in their reference label. -```````````````````````````````` example footnotes autolink pending +```````````````````````````````` example footnotes autolink This is some text. Sometimes the autolinker splits up text into multiple nodes, hoping it will find a hyperlink, so this text has a footnote whose reference label begins with a `w`.[^widely-cited] It has another footnote that contains many different characters (the autolinker was also breaking on `_`).[^sphinx-of-black-quartz_judge-my-vow-0123456789] @@ -342,7 +342,8 @@ It has another footnote that contains many different characters (the autolinker Footnotes interacting with strikethrough should not lead to a use-after-free -```````````````````````````````` example footnotes autolink strikethrough table pending + +```````````````````````````````` example footnotes autolink strikethrough table |Tot.....[^_a_]| .

|Tot.....[^_a_]|

@@ -350,7 +351,8 @@ Footnotes interacting with strikethrough should not lead to a use-after-free Footnotes interacting with strikethrough should not lead to a use-after-free pt2 -```````````````````````````````` example footnotes autolink strikethrough table pending + +```````````````````````````````` example footnotes autolink strikethrough table [^~~is~~1] .

[^~~is~~1]

diff --git a/src/markd/node.cr b/src/markd/node.cr index 31223b3..c318585 100644 --- a/src/markd/node.cr +++ b/src/markd/node.cr @@ -2,32 +2,33 @@ module Markd class Node # Node Type enum Type - Document - Paragraph - Text - Strong - Emphasis - Strikethrough - Link - Image - Heading - List - Item BlockQuote Alert ThematicBreak Code CodeBlock + CustomBlock + CustomInLine + Document + Emphasis + Footnote + FootnoteDefinition + Heading HTMLBlock HTMLInline + Image + Item LineBreak + Link + List + Paragraph SoftBreak - - CustomInLine - CustomBlock + Strikethrough + Strong Table TableCell TableRow + Text def container? CONTAINER_TYPES.includes?(self) @@ -35,23 +36,24 @@ module Markd end CONTAINER_TYPES = { + Type::BlockQuote, + Type::Alert, + Type::CustomBlock, + Type::CustomInLine, Type::Document, - Type::Paragraph, - Type::Strong, Type::Emphasis, - Type::Strikethrough, - Type::Link, - Type::Image, + Type::FootnoteDefinition, Type::Heading, - Type::List, + Type::Image, Type::Item, - Type::BlockQuote, - Type::Alert, - Type::CustomInLine, - Type::CustomBlock, + Type::Link, + Type::List, + Type::Paragraph, + Type::Strikethrough, + Type::Strong, Type::Table, - Type::TableRow, Type::TableCell, + Type::TableRow, } alias DataValue = String | Int32 | Bool diff --git a/src/markd/parsers/block.cr b/src/markd/parsers/block.cr index 2f0d459..b329fc3 100644 --- a/src/markd/parsers/block.cr +++ b/src/markd/parsers/block.cr @@ -7,17 +7,18 @@ module Markd::Parser end RULES = { - Node::Type::Document => Rule::Document.new, - Node::Type::BlockQuote => Rule::BlockQuote.new, - Node::Type::Alert => Rule::BlockQuote.new, # Alerts and BlockQuotes are the same - Node::Type::Heading => Rule::Heading.new, - Node::Type::CodeBlock => Rule::CodeBlock.new, - Node::Type::HTMLBlock => Rule::HTMLBlock.new, - Node::Type::ThematicBreak => Rule::ThematicBreak.new, - Node::Type::List => Rule::List.new, - Node::Type::Item => Rule::Item.new, - Node::Type::Paragraph => Rule::Paragraph.new, - Node::Type::Table => Rule::Table.new, + Node::Type::Document => Rule::Document.new, + Node::Type::BlockQuote => Rule::BlockQuote.new, + Node::Type::Alert => Rule::BlockQuote.new, # Alerts and BlockQuotes are the same + Node::Type::Heading => Rule::Heading.new, + Node::Type::CodeBlock => Rule::CodeBlock.new, + Node::Type::HTMLBlock => Rule::HTMLBlock.new, + Node::Type::ThematicBreak => Rule::ThematicBreak.new, + Node::Type::List => Rule::List.new, + Node::Type::Item => Rule::Item.new, + Node::Type::Paragraph => Rule::Paragraph.new, + Node::Type::Table => Rule::Table.new, + Node::Type::FootnoteDefinition => Rule::FootnoteDefinition.new, } property! tip : Node? @@ -59,10 +60,127 @@ module Markd::Parser parse_blocks(source) end + # Process footnote definitions - parse their content as blocks + if @options.gfm? + process_footnote_definitions + end + Utils.timer("inline parsing", @options.time?) do process_inlines end + if @options.gfm? + # Extract all footnotes and footnote definitions + walker = @document.walker + footnotes = {} of String => Array(Node) + footnote_definitions = {} of String => Node + while (event = walker.next) + node, entering = event + if node.type.footnote? + title = node.data["title"].to_s + footnotes[title] ||= [] of Node + footnotes[title] << node + elsif !entering && node.type.footnote_definition? + footnote_definitions[node.data["title"].to_s] = node + end + end + + # Recursively resolve nested footnotes in definitions before numbering + loop do + new_nodes = 0 + footnotes.each do |footnote_title, nodes| + if !footnote_definitions.has_key?(footnote_title) + nodes.each do |fn_node| + fn_node.type = Node::Type::Text + fn_node.text = "[^#{footnote_title}]" + end + footnotes.delete footnote_title + else + def_node = footnote_definitions[footnote_title] + walker = def_node.walker + while (event = walker.next) + n, entering = event + if entering && n.type.text? + replaced = false + n.text = n.text.gsub(/\[\^([\w\-]+)\]/) do |m| + nested_label = $1 + if footnote_definitions[nested_label]? + fn = Node.new(Node::Type::Footnote) + fn.data["title"] = nested_label + n.insert_after(fn) + footnotes[nested_label] ||= [] of Node + footnotes[nested_label] << fn + replaced = true + new_nodes += 1 + "" + else + m + end + end + if replaced && n.parent? + @inline_lexer.parse(n.parent) + end + n.unlink if n.text.empty? + end + end + end + end + break if new_nodes == 0 + end + + # Ensure all Footnote nodes are present in the footnotes hash + walker = @document.walker + while (event = walker.next) + node, entering = event + if node.type.footnote? + title = node.data["title"].to_s + footnotes[title] ||= [] of Node + unless footnotes[title].includes?(node) + footnotes[title] << node + end + end + end + + # Remove definitions without footnotes + footnote_definitions.each do |footnote_title, def_node| + unless footnotes.has_key?(footnote_title) + def_node.unlink + footnote_definitions.delete footnote_title + end + end + + # Footnote numbers are normalized to 1...n + # Each reference gets a ref_index (1, 2, 3...) and the definition gets a ref_count + footnote_number = 0 + footnotes.each do |footnote_title, nodes| + footnote_number += 1 + nodes.each_with_index do |fn_node, index| + fn_node.data["number"] = footnote_number + fn_node.data["ref_index"] = index + 1 + end + footnote_definitions[footnote_title].data["number"] = footnote_number + footnote_definitions[footnote_title].data["ref_count"] = nodes.size + end + + # Footnote definitions are moved to the end of the document + footnotes.each do |footnote_title, _| + def_node = footnote_definitions[footnote_title] + def_node.unlink + @document.append_child(def_node) + end + + # After all footnote definitions are attached, re-run inline parsing on their children + footnote_definitions.each_value do |def_node| + child = def_node.first_child? + while child + next_child = child.next? + if child.type.paragraph? || child.type.heading? || child.type.table_cell? + @inline_lexer.parse(child) + end + child = next_child + end + end + end @document end @@ -198,6 +316,8 @@ module Markd::Parser @inline_lexer.refmap = @refmap while (event = walker.next) node, entering = event + # Note: footnote_definition is not parsed here because its content + # has already been parsed as blocks in process_footnote_definitions if !entering && (node.type.paragraph? || node.type.heading? || node.type.table_cell?) @inline_lexer.parse(node) end @@ -206,6 +326,34 @@ module Markd::Parser nil end + # Parse footnote definition contents as block-level content + private def process_footnote_definitions + walker = @document.walker + while (event = walker.next) + node, entering = event + if entering && node.type.footnote_definition? && !node.text.empty? + # Parse the footnote definition content as blocks + content = node.text + node.text = "" + + # Create a temporary sub-parser for the footnote content + sub_parser = Block.new(@options) + sub_doc = sub_parser.parse(content) + + # Move all children from the sub-document to the footnote definition + child = sub_doc.first_child? + while child + next_child = child.next? + child.unlink + node.append_child(child) + child = next_child + end + end + end + + nil + end + def token(container : Node, line_number : Int32) container_parent = container.parent? diff --git a/src/markd/parsers/inline.cr b/src/markd/parsers/inline.cr index 8854318..872b5ab 100644 --- a/src/markd/parsers/inline.cr +++ b/src/markd/parsers/inline.cr @@ -14,6 +14,7 @@ module Markd::Parser @text = "" @pos = 0 @refmap = {} of String => Hash(String, String) | String + @footnote_counter = 0 end def parse(node : Node) @@ -194,12 +195,19 @@ module Markd::Parser private def bang(node : Node) start_pos = @pos @pos += 1 - if char_at?(@pos) == '[' + # It's an image if the next character is a [ + # And it's not a footnote OR we are not in GFM mode + # + # * This IS an image: `![...]` + # * This IS an image in non-GFM mode: `![^...]` + # * This IS NOT an image in GFM mode: `![^...]` + + if char_at?(@pos) == '[' && (char_at?(@pos + 1) != '^' || !@options.gfm?) @pos += 1 child = text("![") node.append_child(child) - add_bracket(child, start_pos + 1, true) + add_bracket(child, start_pos + 1, image: true) else node.append_child(text("!")) end @@ -207,9 +215,9 @@ module Markd::Parser true end - private def add_bracket(node : Node, index : Int32, image = false) + private def add_bracket(node : Node, index : Int32, *, image = false, footnote = false) brackets.bracket_after = true if brackets? - @brackets = Bracket.new(node, @brackets, @delimiters, index, image, true) + @brackets = Bracket.new(node, @brackets, @delimiters, index, image: image, active: true, footnote: footnote) end private def remove_bracket @@ -223,7 +231,11 @@ module Markd::Parser child = text("[") node.append_child(child) - add_bracket(child, start_pos, false) + if char_at(@pos) == '^' && @options.gfm? + add_bracket(child, start_pos, footnote: true) + else + add_bracket(child, start_pos) + end true end @@ -253,6 +265,7 @@ module Markd::Parser # If we got here, open is a potential opener is_image = opener.image? + is_footnote = opener.footnote? # Check to see if we have a link/image save_pos = @pos @@ -271,6 +284,20 @@ module Markd::Parser end end + # Is it a footnote? + if is_footnote + # If the 1st char after the closing bracket is a ":" then it's NOT + # a footnote, it's a footnote definition. + if char_at?(@pos) == ':' + @pos = start_pos + node.append_child(text("]")) + remove_bracket + return true + end + title = @text[opener.@index + 2...@pos - 1] + matched = true + end + ref_label = nil unless matched # Next, see if there's a link label @@ -300,7 +327,15 @@ module Markd::Parser end if matched - child = Node.new(is_image ? Node::Type::Image : Node::Type::Link) + if is_image + child = Node.new(Node::Type::Image) + elsif is_footnote + child = Node.new(Node::Type::Footnote) + child.data["number"] = @footnote_counter += 1 + else + child = Node.new(Node::Type::Link) + end + child.data["destination"] = dest.not_nil! child.data["title"] = title || "" @@ -1101,8 +1136,9 @@ module Markd::Parser property? image : Bool property? active : Bool property? bracket_after : Bool + property? footnote : Bool - def initialize(@node, @previous, @previous_delimiter, @index, @image, @active = true) + def initialize(@node, @previous, @previous_delimiter, @index, *, @image = false, @active = true, @footnote = false) @bracket_after = false end end diff --git a/src/markd/renderer.cr b/src/markd/renderer.cr index 35aad32..5515b23 100644 --- a/src/markd/renderer.cr +++ b/src/markd/renderer.cr @@ -49,28 +49,31 @@ module Markd false end - abstract def heading(node : Node, entering : Bool) : Nil - abstract def list(node : Node, entering : Bool) : Nil - abstract def item(node : Node, entering : Bool) : Nil abstract def block_quote(node : Node, entering : Bool) : Nil abstract def alert(node : Node, entering : Bool) : Nil abstract def thematic_break(node : Node, entering : Bool) : Nil abstract def code_block(node : Node, entering : Bool, formatter : T?) : Nil forall T abstract def code(node : Node, entering : Bool) : Nil + abstract def emphasis(node : Node, entering : Bool) : Nil + abstract def footnote(node : Node, entering : Bool) : Nil + abstract def footnote_definition(node : Node, entering : Bool) : Nil + abstract def heading(node : Node, entering : Bool) : Nil abstract def html_block(node : Node, entering : Bool) : Nil abstract def html_inline(node : Node, entering : Bool) : Nil + abstract def image(node : Node, entering : Bool) : Nil + abstract def item(node : Node, entering : Bool) : Nil + abstract def line_break(node : Node, entering : Bool) : Nil + abstract def link(node : Node, entering : Bool) : Nil + abstract def list(node : Node, entering : Bool) : Nil abstract def paragraph(node : Node, entering : Bool) : Nil - abstract def emphasis(node : Node, entering : Bool) : Nil abstract def soft_break(node : Node, entering : Bool) : Nil - abstract def line_break(node : Node, entering : Bool) : Nil - abstract def strong(node : Node, entering : Bool) : Nil abstract def strikethrough(node : Node, entering : Bool) : Nil - abstract def link(node : Node, entering : Bool) : Nil - abstract def image(node : Node, entering : Bool) : Nil - abstract def text(node : Node, entering : Bool) : Nil - abstract def table(node : Node, entering : Bool) : Nil - abstract def table_row(node : Node, entering : Bool) : Nil + abstract def strong(node : Node, entering : Bool) : Nil abstract def table_cell(node : Node, entering : Bool) : Nil + abstract def table_row(node : Node, entering : Bool) : Nil + abstract def table(node : Node, entering : Bool) : Nil + abstract def text(node : Node, entering : Bool) : Nil + abstract def thematic_break(node : Node, entering : Bool) : Nil def render(document : Node, formatter : T?) forall T Utils.timer("rendering", @options.time?) do @@ -121,6 +124,10 @@ module Markd table_row(node, entering) when Node::Type::TableCell table_cell(node, entering) + when Node::Type::Footnote + footnote(node, entering) + when Node::Type::FootnoteDefinition + footnote_definition(node, entering) else text(node, entering) end diff --git a/src/markd/renderers/html_renderer.cr b/src/markd/renderers/html_renderer.cr index e7d0631..64cf23b 100644 --- a/src/markd/renderers/html_renderer.cr +++ b/src/markd/renderers/html_renderer.cr @@ -253,11 +253,76 @@ module Markd newline tag("p", attrs(node)) else + # If this is the last paragraph in a footnote definition, append backrefs + if last_paragraph_in_footnote?(node) + append_footnote_backrefs(node.parent) + end tag("p", end_tag: true) newline end end + # Check if this paragraph is the last paragraph child of a footnote definition + private def last_paragraph_in_footnote?(node : Node) : Bool + parent = node.parent? + return false unless parent && parent.type.footnote_definition? + + # Check if this is the last paragraph (there might be no more paragraphs after this) + # but there could be non-paragraph nodes after, so we check if there's no next sibling + # that is a paragraph + sibling = node.next? + while sibling + return false if sibling.type.paragraph? + sibling = sibling.next? + end + true + end + + # Encode a string for use in HTML id attributes + # This matches the old URI.encode behavior for footnote IDs + private def encode_id_component(string : String) : String + String.build do |io| + URI.encode(string, io) do |byte| + # Allow unreserved chars plus some additional chars that are safe in HTML IDs + URI.unreserved?(byte) || ['/', '(', ')', '*', '!', '$', '\'', ',', ';', ':', '@', '&', '=', '+'].includes?(byte.chr) + end + end + end + + # Append footnote back-reference links + # @param in_paragraph If true, adds a space before the backrefs + private def append_footnote_backrefs(footnote_def : Node, in_paragraph : Bool = true) : Nil + encoded_title = encode_id_component(footnote_def.data["title"].to_s) + footnote_number = footnote_def.data["number"].as(Int32) + ref_count = footnote_def.data["ref_count"].as(Int32) + + # Add a space before the backrefs if we're inside a paragraph + literal " " if in_paragraph + + # Generate backref(s) - multiple if referenced multiple times + (1..ref_count).each do |ref_index| + backref_id = ref_index == 1 ? "fnref-#{encoded_title}" : "fnref-#{encoded_title}-#{ref_index}" + backref_idx = ref_index == 1 ? footnote_number.to_s : "#{footnote_number}-#{ref_index}" + + tag("a", { + "href" => "##{backref_id}", + "class" => "footnote-backref", + "data-footnote-backref" => nil, + "data-footnote-backref-idx" => backref_idx, + "aria-label" => "Back to reference #{backref_idx}", + }) + literal "↩" + # For 2nd and later backrefs, add a superscript with the index + if ref_index > 1 + tag("sup", {"class" => "footnote-ref"}) + literal ref_index.to_s + tag("sup", end_tag: true) + end + tag("a", end_tag: true) + literal " " if ref_index < ref_count + end + end + def emphasis(node : Node, entering : Bool) : Nil if entering node.data["strong_stack"] = @strong_stack @@ -296,6 +361,79 @@ module Markd output(node.text) end + def footnote(node : Node, entering : Bool) : Nil + # Spec says `[^1]` should generate: + # 1 + # For multiple references to the same footnote: + # First: id="fnref-label", Second: id="fnref-label-2", etc. + if entering + tag("sup", { + "class" => "footnote-ref", + }) + ref_index = node.data["ref_index"].as(Int32) + encoded_title = encode_id_component(node.data["title"].to_s) + id = ref_index == 1 ? "fnref-#{encoded_title}" : "fnref-#{encoded_title}-#{ref_index}" + tag("a", { + "href" => "#fn-#{encoded_title}", + "id" => id, + "data-footnote-ref" => nil, + }) + # GFM spec says to output the number of the footnote + output node.data["number"].to_s + tag("a", end_tag: true) + tag("sup", end_tag: true) + end + end + + def footnote_definition(node : Node, entering : Bool) : Nil + # A footnote definition by spec should render something like: + #
  • + #

    The actual content of the footnote + # ↩

    + #
  • + # For multiple references, multiple backref links are generated: + # ↩ + # ↩2 + if entering + if !node.prev.type.footnote_definition? + newline + tag("section", {"class" => "footnotes", "data-footnotes" => nil}) + newline + tag("ol") + end + newline + tag("li", { + "id" => "fn-#{encode_id_component(node.data["title"].to_s)}", + }) + newline + else + # If there's no paragraph child, output backrefs here + # (e.g., for footnote definitions that only contain code blocks) + unless has_paragraph_child?(node) + append_footnote_backrefs(node, in_paragraph: false) + newline + end + tag("li", end_tag: true) + if node == node.parent.last_child + newline + tag("ol", end_tag: true) + newline + tag("section", end_tag: true) + newline + end + end + end + + # Check if a node has a paragraph child + private def has_paragraph_child?(node : Node) : Bool + child = node.first_child? + while child + return true if child.type.paragraph? + child = child.next? + end + false + end + private def tag(name : String, attrs = nil, self_closing = false, end_tag = false) return if @disable_tag > 0 @@ -303,7 +441,11 @@ module Markd @output_io << "/" if end_tag @output_io << name attrs.try &.each do |key, value| - @output_io << ' ' << key << '=' << '"' << value << '"' + if value.nil? + @output_io << ' ' << key + else + @output_io << ' ' << key << '=' << '"' << value << '"' + end end @output_io << " /" if self_closing diff --git a/src/markd/rule.cr b/src/markd/rule.cr index 5f57db0..c216417 100644 --- a/src/markd/rule.cr +++ b/src/markd/rule.cr @@ -15,7 +15,7 @@ module Markd ATTRIBUTE_VALUE_SPEC_STRING = "(?:" + "\\s*=" + "\\s*" + ATTRIBUTE_VALUE_STRING + ")" ATTRIBUTE = "(?:" + "\\s+" + ATTRIBUTE_NAME_STRING + ATTRIBUTE_VALUE_SPEC_STRING + "?)" - MAYBE_SPECIAL = {'#', '`', '~', '*', '+', '_', '=', '<', '>', '-', '|'} + MAYBE_SPECIAL = {'#', '`', '~', '*', '+', '_', '=', '<', '>', '-', '|', '['} THEMATIC_BREAK = /^(?:(?:\*[ \t]*){3,}|(?:_[ \t]*){3,}|(?:-[ \t]*){3,})[ \t]*$/ ESCAPABLE = /^#{ESCAPABLE_STRING}/ @@ -107,6 +107,8 @@ module Markd ADMONITION_START = /^> \[!((?:NOTE|TIP|IMPORTANT|CAUTION|WARNING)+)](\s*.*)?$/ + FOOTNOTE_DEFINITION_START = /\[\^[^\]]+\]:(\s|$)/ + # Match Value # # - None: no match diff --git a/src/markd/rules/footnote_definition.cr b/src/markd/rules/footnote_definition.cr new file mode 100644 index 0000000..db0ada4 --- /dev/null +++ b/src/markd/rules/footnote_definition.cr @@ -0,0 +1,64 @@ +module Markd::Rule + struct FootnoteDefinition + include Rule + + def match(parser : Parser, container : Node) : MatchValue + if match?(parser) && parser.gfm? + parser.close_unmatched_blocks + parser.add_child(Node::Type::FootnoteDefinition, 0) + MatchValue::Leaf + else + MatchValue::None + end + end + + # Footnote definitions continue as long as lines are indented (4+ spaces) + # Blank lines are allowed (they separate paragraphs inside footnotes) + def continue(parser : Parser, container : Node) : ContinueStatus + # Blank lines are allowed (separate paragraphs) + return ContinueStatus::Continue if parser.blank + + # Indented content continues the definition + return ContinueStatus::Continue if parser.indent >= Rule::CODE_INDENT + + ContinueStatus::Stop + end + + def token(parser : Parser, container : Node) : Nil + lines = container.text.split "\n" + lines.each_with_index do |line, i| + if i == 0 + # First line has the footnote definition label removed and + # leading spaces removed. + container.data["title"] = line.split("]:")[0].lstrip("[^") + lines[i] = line.split("]:", 2)[1].lstrip + elsif line == "" + # Empty lines go as-is + lines[i] = "" + else + # Subsequent lines have the leading 4 spaces removed + lines[i] = line[4..-1] + end + end + # Store the processed text for later block parsing + container.text = lines.join("\n") + end + + def can_contain?(type) + true + end + + # Footnote definitions can be multiline + def accepts_lines? : Bool + true + end + + # Match only lines that look like the first line of a footnote definition: + # Start with [^something]: + + private def match?(parser) + !parser.indented && \ + parser.line.match(FOOTNOTE_DEFINITION_START) + end + end +end From 33d53634dd22b00bd6a844bf1695957d53576207 Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Mon, 23 Feb 2026 10:04:25 -0300 Subject: [PATCH 05/15] refactor: move footnote processing to helper method --- src/markd/parsers/block.cr | 192 +++++++++++++++++++------------------ 1 file changed, 100 insertions(+), 92 deletions(-) diff --git a/src/markd/parsers/block.cr b/src/markd/parsers/block.cr index b329fc3..ac26e2f 100644 --- a/src/markd/parsers/block.cr +++ b/src/markd/parsers/block.cr @@ -70,118 +70,126 @@ module Markd::Parser end if @options.gfm? - # Extract all footnotes and footnote definitions - walker = @document.walker - footnotes = {} of String => Array(Node) - footnote_definitions = {} of String => Node - while (event = walker.next) - node, entering = event - if node.type.footnote? - title = node.data["title"].to_s - footnotes[title] ||= [] of Node - footnotes[title] << node - elsif !entering && node.type.footnote_definition? - footnote_definitions[node.data["title"].to_s] = node - end + process_footnotes + end + + @document + end + + # Process footnotes: extract, resolve nested references, number them, and move definitions to end + private def process_footnotes + # Extract all footnotes and footnote definitions + walker = @document.walker + footnotes = {} of String => Array(Node) + footnote_definitions = {} of String => Node + while (event = walker.next) + node, entering = event + if node.type.footnote? + title = node.data["title"].to_s + footnotes[title] ||= [] of Node + footnotes[title] << node + elsif !entering && node.type.footnote_definition? + footnote_definitions[node.data["title"].to_s] = node end + end - # Recursively resolve nested footnotes in definitions before numbering - loop do - new_nodes = 0 - footnotes.each do |footnote_title, nodes| - if !footnote_definitions.has_key?(footnote_title) - nodes.each do |fn_node| - fn_node.type = Node::Type::Text - fn_node.text = "[^#{footnote_title}]" - end - footnotes.delete footnote_title - else - def_node = footnote_definitions[footnote_title] - walker = def_node.walker - while (event = walker.next) - n, entering = event - if entering && n.type.text? - replaced = false - n.text = n.text.gsub(/\[\^([\w\-]+)\]/) do |m| - nested_label = $1 - if footnote_definitions[nested_label]? - fn = Node.new(Node::Type::Footnote) - fn.data["title"] = nested_label - n.insert_after(fn) - footnotes[nested_label] ||= [] of Node - footnotes[nested_label] << fn - replaced = true - new_nodes += 1 - "" - else - m - end - end - if replaced && n.parent? - @inline_lexer.parse(n.parent) + # Recursively resolve nested footnotes in definitions before numbering + loop do + new_nodes = 0 + footnotes.each do |footnote_title, nodes| + if !footnote_definitions.has_key?(footnote_title) + nodes.each do |fn_node| + fn_node.type = Node::Type::Text + fn_node.text = "[^#{footnote_title}]" + end + footnotes.delete footnote_title + else + def_node = footnote_definitions[footnote_title] + walker = def_node.walker + while (event = walker.next) + n, entering = event + if entering && n.type.text? + replaced = false + n.text = n.text.gsub(/\[\^([\w\-]+)\]/) do |m| + nested_label = $1 + if footnote_definitions[nested_label]? + fn = Node.new(Node::Type::Footnote) + fn.data["title"] = nested_label + n.insert_after(fn) + footnotes[nested_label] ||= [] of Node + footnotes[nested_label] << fn + replaced = true + new_nodes += 1 + "" + else + m end - n.unlink if n.text.empty? end + if replaced && n.parent? + @inline_lexer.parse(n.parent) + end + n.unlink if n.text.empty? end end end - break if new_nodes == 0 end + break if new_nodes == 0 + end - # Ensure all Footnote nodes are present in the footnotes hash - walker = @document.walker - while (event = walker.next) - node, entering = event - if node.type.footnote? - title = node.data["title"].to_s - footnotes[title] ||= [] of Node - unless footnotes[title].includes?(node) - footnotes[title] << node - end + # Ensure all Footnote nodes are present in the footnotes hash + walker = @document.walker + while (event = walker.next) + node, entering = event + if node.type.footnote? + title = node.data["title"].to_s + footnotes[title] ||= [] of Node + unless footnotes[title].includes?(node) + footnotes[title] << node end end + end - # Remove definitions without footnotes - footnote_definitions.each do |footnote_title, def_node| - unless footnotes.has_key?(footnote_title) - def_node.unlink - footnote_definitions.delete footnote_title - end + # Remove definitions without footnotes + footnote_definitions.each do |footnote_title, def_node| + unless footnotes.has_key?(footnote_title) + def_node.unlink + footnote_definitions.delete footnote_title end + end - # Footnote numbers are normalized to 1...n - # Each reference gets a ref_index (1, 2, 3...) and the definition gets a ref_count - footnote_number = 0 - footnotes.each do |footnote_title, nodes| - footnote_number += 1 - nodes.each_with_index do |fn_node, index| - fn_node.data["number"] = footnote_number - fn_node.data["ref_index"] = index + 1 - end - footnote_definitions[footnote_title].data["number"] = footnote_number - footnote_definitions[footnote_title].data["ref_count"] = nodes.size + # Footnote numbers are normalized to 1...n + # Each reference gets a ref_index (1, 2, 3...) and the definition gets a ref_count + footnote_number = 0 + footnotes.each do |footnote_title, nodes| + footnote_number += 1 + nodes.each_with_index do |fn_node, index| + fn_node.data["number"] = footnote_number + fn_node.data["ref_index"] = index + 1 end + footnote_definitions[footnote_title].data["number"] = footnote_number + footnote_definitions[footnote_title].data["ref_count"] = nodes.size + end - # Footnote definitions are moved to the end of the document - footnotes.each do |footnote_title, _| - def_node = footnote_definitions[footnote_title] - def_node.unlink - @document.append_child(def_node) - end + # Footnote definitions are moved to the end of the document + footnotes.each do |footnote_title, _| + def_node = footnote_definitions[footnote_title] + def_node.unlink + @document.append_child(def_node) + end - # After all footnote definitions are attached, re-run inline parsing on their children - footnote_definitions.each_value do |def_node| - child = def_node.first_child? - while child - next_child = child.next? - if child.type.paragraph? || child.type.heading? || child.type.table_cell? - @inline_lexer.parse(child) - end - child = next_child + # After all footnote definitions are attached, re-run inline parsing on their children + footnote_definitions.each_value do |def_node| + child = def_node.first_child? + while child + next_child = child.next? + if child.type.paragraph? || child.type.heading? || child.type.table_cell? + @inline_lexer.parse(child) end + child = next_child end end - @document + + nil end private def parse_blocks(source) From 84f8f1f2a4801cca50d42a655983e4fbef991471 Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Wed, 29 Jul 2026 13:04:06 -0300 Subject: [PATCH 06/15] chore: remove .vscode files from git tracking --- .vscode/launch.json | 13 --------- .vscode/tasks.json | 71 --------------------------------------------- 2 files changed, 84 deletions(-) delete mode 100644 .vscode/launch.json delete mode 100644 .vscode/tasks.json diff --git a/.vscode/launch.json b/.vscode/launch.json deleted file mode 100644 index 3ab15c3..0000000 --- a/.vscode/launch.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "version": "0.2.0", - "configurations": [ - { - "type": "lldb", - "request": "launch", - "name": "Launch", - "program": "${workspaceRoot}/bin/main", - "args": [], - "cwd": "${workspaceRoot}" - } - ] -} diff --git a/.vscode/tasks.json b/.vscode/tasks.json deleted file mode 100644 index c288689..0000000 --- a/.vscode/tasks.json +++ /dev/null @@ -1,71 +0,0 @@ -{ - "version": "2.0.0", - "tasks": [ - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - }, - { - "label": "Run Crystal spec tests", - "type": "shell", - "command": "crystal spec", - "group": "test" - } - ] -} \ No newline at end of file From efda35af16720d3f0dd6f9928f7e68a90ea9dcbb Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Thu, 13 Aug 2026 11:18:12 -0300 Subject: [PATCH 07/15] chore: ignore compiled spec binary --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 3e99378..98023d3 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,9 @@ /.shards/ /src/main.cr +# Compiled spec binary +/markd_spec + # Libraries don't need dependency lock # Dependencies will be locked in application that uses them /shard.lock From e2498ff9f0688c8026c3ef32ecb10d0b60365c72 Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Thu, 13 Aug 2026 15:17:25 -0300 Subject: [PATCH 08/15] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/markd/renderer.cr | 1 - 1 file changed, 1 deletion(-) diff --git a/src/markd/renderer.cr b/src/markd/renderer.cr index 5515b23..7745276 100644 --- a/src/markd/renderer.cr +++ b/src/markd/renderer.cr @@ -73,7 +73,6 @@ module Markd abstract def table_row(node : Node, entering : Bool) : Nil abstract def table(node : Node, entering : Bool) : Nil abstract def text(node : Node, entering : Bool) : Nil - abstract def thematic_break(node : Node, entering : Bool) : Nil def render(document : Node, formatter : T?) forall T Utils.timer("rendering", @options.time?) do From 59d36cfaf4887fccee5de004ef069be6ce3e3211 Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Thu, 13 Aug 2026 15:22:31 -0300 Subject: [PATCH 09/15] fix: address PR review comments on footnotes - renderer.cr: remove duplicate thematic_break abstract method declaration - rule.cr: anchor FOOTNOTE_DEFINITION_START to line start so mid-line [^x]: does not incorrectly start a block-level definition - block.cr: iterate over a snapshot of hash keys instead of mutating footnotes/footnote_definitions during each-iteration (fixes potential Hash modified during iteration errors) - block.cr: broaden nested-footnote label regex from [\w-]+ to [^\]]+ so nested references with arbitrary label characters are detected - inline.cr: skip inline-link (...) parsing for footnote openers so [^a](url) renders as a footnote ref with (url) preserved as text --- src/markd/parsers/block.cr | 10 +++++++--- src/markd/parsers/inline.cr | 4 +++- src/markd/rule.cr | 2 +- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/src/markd/parsers/block.cr b/src/markd/parsers/block.cr index ac26e2f..0c8a2b5 100644 --- a/src/markd/parsers/block.cr +++ b/src/markd/parsers/block.cr @@ -96,7 +96,9 @@ module Markd::Parser # Recursively resolve nested footnotes in definitions before numbering loop do new_nodes = 0 - footnotes.each do |footnote_title, nodes| + footnotes.keys.each do |footnote_title| + nodes = footnotes[footnote_title]? + next unless nodes if !footnote_definitions.has_key?(footnote_title) nodes.each do |fn_node| fn_node.type = Node::Type::Text @@ -110,7 +112,7 @@ module Markd::Parser n, entering = event if entering && n.type.text? replaced = false - n.text = n.text.gsub(/\[\^([\w\-]+)\]/) do |m| + n.text = n.text.gsub(/\[\^([^\]]+)\]/) do |m| nested_label = $1 if footnote_definitions[nested_label]? fn = Node.new(Node::Type::Footnote) @@ -150,7 +152,9 @@ module Markd::Parser end # Remove definitions without footnotes - footnote_definitions.each do |footnote_title, def_node| + footnote_definitions.keys.each do |footnote_title| + def_node = footnote_definitions[footnote_title]? + next unless def_node unless footnotes.has_key?(footnote_title) def_node.unlink footnote_definitions.delete footnote_title diff --git a/src/markd/parsers/inline.cr b/src/markd/parsers/inline.cr index 872b5ab..d358389 100644 --- a/src/markd/parsers/inline.cr +++ b/src/markd/parsers/inline.cr @@ -271,7 +271,9 @@ module Markd::Parser save_pos = @pos # Inline link? - if char_at?(@pos) == '(' + # Footnote openers ([^...]) are not links, so don't try to parse a + # `(destination)` after the closing bracket for them. + if !is_footnote && char_at?(@pos) == '(' @pos += 1 if spnl && (dest = link_destination) && spnl && (char_at?(@pos - 1).try(&.whitespace?) && diff --git a/src/markd/rule.cr b/src/markd/rule.cr index c216417..1efaaa2 100644 --- a/src/markd/rule.cr +++ b/src/markd/rule.cr @@ -107,7 +107,7 @@ module Markd ADMONITION_START = /^> \[!((?:NOTE|TIP|IMPORTANT|CAUTION|WARNING)+)](\s*.*)?$/ - FOOTNOTE_DEFINITION_START = /\[\^[^\]]+\]:(\s|$)/ + FOOTNOTE_DEFINITION_START = /^\[\^[^\]]+\]:(\s|$)/ # Match Value # From 0bb6a8363a72d3b15e0a48bb8a2db07c4b814a8e Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Sat, 5 Sep 2026 10:13:44 -0300 Subject: [PATCH 10/15] test: add regression fixtures for footnote review fixes Cover the edge cases from the Copilot review on PR #78 that had no spec coverage: - [^a](url) keeps the footnote ref and the parentheses as text instead of consuming (url) as a link destination - a mid-line [^x]: does not start a footnote definition - nested footnote references resolve with arbitrary label characters --- spec/fixtures/gfm-regression.txt | 49 ++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/spec/fixtures/gfm-regression.txt b/spec/fixtures/gfm-regression.txt index a65a717..302b3ab 100644 --- a/spec/fixtures/gfm-regression.txt +++ b/spec/fixtures/gfm-regression.txt @@ -376,3 +376,52 @@ Issue #424 - emphasis before links .

    text link

    ```````````````````````````````` + +A footnote reference followed by (parentheses) is not parsed as a link + +```````````````````````````````` example footnotes +Text with a footnote[^a], and [^a](url) with a link-ish suffix. + +[^a]: note one +. +

    Text with a footnote1, and 1(url) with a link-ish suffix.

    +
    +
      +
    1. +

      note one ↩ ↩2

      +
    2. +
    +
    +```````````````````````````````` + +Footnote definitions must start at the beginning of the line + +```````````````````````````````` example footnotes +foo [^b]: this is mid-line, so not a definition + +[^b]: real note +. +

    foo [^b]: this is mid-line, so not a definition

    +```````````````````````````````` + +Nested footnote references may contain arbitrary characters + +```````````````````````````````` example footnotes +See[^one]. + +[^one]: outer [^">] + +[^">]: inner note +. +

    See1.

    +
    +
      +
    1. +

      outer 2 ↩

      +
    2. +
    3. +

      inner note ↩

      +
    4. +
    +
    +```````````````````````````````` From 078f61538b6acb8cb87ae1ba970fbf63bcd58ffa Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Sat, 5 Sep 2026 10:13:47 -0300 Subject: [PATCH 11/15] chore: fix ameba lint warnings - add spaces around macro expression in Node#to_s - drop redundant return in Inline#match --- src/markd/node.cr | 2 +- src/markd/parsers/inline.cr | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/markd/node.cr b/src/markd/node.cr index c318585..783c29b 100644 --- a/src/markd/node.cr +++ b/src/markd/node.cr @@ -134,7 +134,7 @@ module Markd end def to_s(io : IO) - io << "#<" << {{@type.name.id.stringify}} << ":0x" + io << "#<" << {{ @type.name.id.stringify }} << ":0x" object_id.to_s(16, io) io << " @type=" << @type io << " @parent=" << @parent if @parent diff --git a/src/markd/parsers/inline.cr b/src/markd/parsers/inline.cr index d358389..f1089f7 100644 --- a/src/markd/parsers/inline.cr +++ b/src/markd/parsers/inline.cr @@ -941,7 +941,7 @@ module Markd::Parser text = @text.byte_slice(@pos) if (match = text.match(regex)) @pos += match.byte_end.not_nil! - return match[0] + match[0] end end From effa6b7a89396a2638f89f69442f97a90886ede0 Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Sun, 6 Sep 2026 04:32:12 -0300 Subject: [PATCH 12/15] ci: install development deps for specs job The tartrazine require test compile-runs spec/fixtures/tartrazine.cr, which needs the tartrazine dev dependency, so --without-development broke spec compilation on every OS in the matrix (same fix the ameba job already got). Also fix ameba warnings in the fixture itself. --- .github/workflows/ci.yml | 2 +- spec/fixtures/tartrazine.cr | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fc1bd28..20ee7c3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,7 +64,7 @@ jobs: crystal: ${{ matrix.crystal }} - name: Install dependencies - run: shards install --without-development + run: shards install - name: Run specs run: crystal spec --error-on-warnings --error-trace diff --git a/spec/fixtures/tartrazine.cr b/spec/fixtures/tartrazine.cr index 5b1cb9f..f3473bf 100644 --- a/spec/fixtures/tartrazine.cr +++ b/spec/fixtures/tartrazine.cr @@ -2,9 +2,9 @@ require "tartrazine" require "../../src/markd" markdown = <<-MD -# Hello Markd + # Hello Markd -> Yet another markdown parser built for speed, written in Crystal, Compliant to CommonMark specification. -MD + > Yet another markdown parser built for speed, written in Crystal, Compliant to CommonMark specification. + MD -html = Markd.to_html(markdown) +Markd.to_html(markdown) From e03fc75116c2b6b7bbadcd1a8b59089cd4fcaf74 Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Sun, 6 Sep 2026 04:48:54 -0300 Subject: [PATCH 13/15] ci: bump ameba to v1.7.0 v1.6.4 no longer compiles with current Crystal (undefined method 'next_string_array_token' on Crystal::Lexer). v1.7.0 builds with Crystal >= 1.19 and passes this repo's .ameba.yml with no changes. --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 20ee7c3..06cee60 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - ameba-version: [v1.6.4] + ameba-version: [v1.7.0] name: Ameba ${{ matrix.ameba-version }} linter check steps: - name: Install latest Crystal From 490f0bc3129d1e625464b3f4da7336a2a978cffe Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Sun, 6 Sep 2026 14:14:14 -0300 Subject: [PATCH 14/15] fix: cut footnote reference labels by byte offset MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The inline parser tracks positions as byte offsets, but the footnote label was cut from the text with character-based slicing. Any multi-byte character earlier in the line (an emoji, an accented letter) shifted the label: the reference matched no definition and degraded to literal text like '✅[^]'. Cut the label with byte_slice instead, and guard it with a regression fixture covering emoji and accented characters in paragraphs and table cells. --- spec/fixtures/gfm-extensions.txt | 45 ++++++++++++++++++++++++++++++++ src/markd/parsers/inline.cr | 4 ++- 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/spec/fixtures/gfm-extensions.txt b/spec/fixtures/gfm-extensions.txt index e7de5be..dbb876d 100644 --- a/spec/fixtures/gfm-extensions.txt +++ b/spec/fixtures/gfm-extensions.txt @@ -762,6 +762,51 @@ Hi! ```````````````````````````````` +Multibyte characters before a reference must not shift its label: +the parser tracks byte offsets but the label used to be cut with +character-based slicing. + +```````````````````````````````` example +Emoji ✅[^emoji] and accented é[^accent]. + +| Tables | Cells | +| ------ | ----- | +| emoji | ✅[^t-emoji] | + +[^emoji]: emoji note +[^accent]: accent note +[^t-emoji]: table note +. +

    Emoji ✅1 and accented é2.

    + + + + + + + + + + + + + +
    TablesCells
    emoji✅3
    +
    +
      +
    1. +

      emoji note ↩

      +
    2. +
    3. +

      accent note ↩

      +
    4. +
    5. +

      table note ↩

      +
    6. +
    +
    +```````````````````````````````` + ## When a footnote is used multiple times, we insert multiple backrefs. ```````````````````````````````` example diff --git a/src/markd/parsers/inline.cr b/src/markd/parsers/inline.cr index f1089f7..78c34dc 100644 --- a/src/markd/parsers/inline.cr +++ b/src/markd/parsers/inline.cr @@ -296,7 +296,9 @@ module Markd::Parser remove_bracket return true end - title = @text[opener.@index + 2...@pos - 1] + # @pos and opener.@index are byte offsets: slice bytes, or any + # multi-byte character earlier in the line shifts the label. + title = @text.byte_slice(opener.@index + 2, @pos - opener.@index - 3) matched = true end From 7fd5ea9129cb2112fa2a04db47a5eba3f913190e Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Thu, 19 Nov 2026 12:38:38 -0300 Subject: [PATCH 15/15] fix: address copilot review issues in footnote support - Insert nested footnote references at their marker positions and in order by splitting the text node around each match, instead of appending every reference after the whole text node (reversing them). Unlinking an emptied text node mid-walk is also avoided, since it terminates the walker early. - Use the bounds-safe char_at? when inspecting the character after an opening bracket, so an unmatched '[' at end of input renders as literal text instead of raising. - Make the footnote renderer hooks non-abstract no-ops so existing custom Renderer subclasses keep compiling. - Discard duplicate footnote definitions: only the last definition per label was kept, but earlier ones still rendered without numbering data and crashed backref generation. - Treat a missing previous sibling as the start of the footnotes section, so a definition referenced only from another definition no longer raises on nil prev. - Strip exactly the '[^' syntax prefix from definition labels instead of every leading '[' or '^', so labels like '[^^a]' resolve. - Strip continuation indentation by columns with tab expansion instead of blindly removing four characters, so tab-indented continuation lines keep their content. Co-Authored-By: Claude Opus 5.5 --- src/markd/parsers/block.cr | 69 ++++++++++++++++++++------ src/markd/parsers/inline.cr | 2 +- src/markd/renderer.cr | 12 ++++- src/markd/renderers/html_renderer.cr | 3 +- src/markd/rules/footnote_definition.cr | 32 ++++++++++-- 5 files changed, 97 insertions(+), 21 deletions(-) diff --git a/src/markd/parsers/block.cr b/src/markd/parsers/block.cr index 0c8a2b5..29233e8 100644 --- a/src/markd/parsers/block.cr +++ b/src/markd/parsers/block.cr @@ -89,7 +89,14 @@ module Markd::Parser footnotes[title] ||= [] of Node footnotes[title] << node elsif !entering && node.type.footnote_definition? - footnote_definitions[node.data["title"].to_s] = node + title = node.data["title"].to_s + # Duplicate definitions: only the last one per title is kept, so + # discard earlier ones (they would otherwise render without + # numbering data and crash backref generation). + if (existing = footnote_definitions[title]?) + existing.unlink + end + footnote_definitions[title] = node end end @@ -112,25 +119,59 @@ module Markd::Parser n, entering = event if entering && n.type.text? replaced = false - n.text = n.text.gsub(/\[\^([^\]]+)\]/) do |m| - nested_label = $1 - if footnote_definitions[nested_label]? - fn = Node.new(Node::Type::Footnote) - fn.data["title"] = nested_label - n.insert_after(fn) - footnotes[nested_label] ||= [] of Node - footnotes[nested_label] << fn - replaced = true + # Collect the nested references first, then split the text + # node around each marker so the reference node lands at + # the marker's position (in order), not after the whole + # text node. + insertions = [] of {Int32, Int32, Node} + n.text.scan(/\[\^([^\]]+)\]/) do |match_data| + byte_start = match_data.begin(0) + byte_end = match_data.end(0) + nested_label = match_data[1] + next unless byte_start && byte_end + next unless footnote_definitions[nested_label]? + fn = Node.new(Node::Type::Footnote) + fn.data["title"] = nested_label + insertions << {byte_start, byte_end, fn} + end + + unless insertions.empty? + replaced = true + original_text = n.text + cursor = n + last_byte = 0 + insertions.each do |(byte_start, byte_end, fn)| + gap = original_text.byte_slice(last_byte, byte_start - last_byte) + if cursor == n + n.text = gap + else + gap_node = Node.new(Node::Type::Text) + gap_node.text = gap + cursor.insert_after(gap_node) + cursor = gap_node + end + cursor.insert_after(fn) + cursor = fn + title = fn.data["title"].to_s + footnotes[title] ||= [] of Node + footnotes[title] << fn new_nodes += 1 - "" - else - m + last_byte = byte_end + end + rest = original_text.byte_slice(last_byte) + unless rest.empty? + rest_node = Node.new(Node::Type::Text) + rest_node.text = rest + cursor.insert_after(rest_node) end end + if replaced && n.parent? @inline_lexer.parse(n.parent) end - n.unlink if n.text.empty? + # Note: don't unlink an emptied text node here — the walker + # is positioned on it, and unlinking mid-walk would stop + # the walk early. end end end diff --git a/src/markd/parsers/inline.cr b/src/markd/parsers/inline.cr index 78c34dc..e19ef7c 100644 --- a/src/markd/parsers/inline.cr +++ b/src/markd/parsers/inline.cr @@ -231,7 +231,7 @@ module Markd::Parser child = text("[") node.append_child(child) - if char_at(@pos) == '^' && @options.gfm? + if char_at?(@pos) == '^' && @options.gfm? add_bracket(child, start_pos, footnote: true) else add_bracket(child, start_pos) diff --git a/src/markd/renderer.cr b/src/markd/renderer.cr index 1578e4c..5795f8d 100644 --- a/src/markd/renderer.cr +++ b/src/markd/renderer.cr @@ -55,8 +55,16 @@ module Markd abstract def code_block(node : Node, entering : Bool, formatter : T?) : Nil forall T abstract def code(node : Node, entering : Bool) : Nil abstract def emphasis(node : Node, entering : Bool) : Nil - abstract def footnote(node : Node, entering : Bool) : Nil - abstract def footnote_definition(node : Node, entering : Bool) : Nil + + # Footnote hooks are intentionally not abstract: existing custom + # Renderer subclasses should keep compiling (and render footnotes as + # plain content) without implementing them. + def footnote(node : Node, entering : Bool) : Nil + end + + def footnote_definition(node : Node, entering : Bool) : Nil + end + abstract def heading(node : Node, entering : Bool) : Nil abstract def html_block(node : Node, entering : Bool) : Nil abstract def html_inline(node : Node, entering : Bool) : Nil diff --git a/src/markd/renderers/html_renderer.cr b/src/markd/renderers/html_renderer.cr index 912ca12..c9986d5 100644 --- a/src/markd/renderers/html_renderer.cr +++ b/src/markd/renderers/html_renderer.cr @@ -399,7 +399,8 @@ module Markd # ↩ # ↩2 if entering - if !node.prev.type.footnote_definition? + prev_sibling = node.prev? + if prev_sibling.nil? || !prev_sibling.type.footnote_definition? newline tag("section", {"class" => "footnotes", "data-footnotes" => nil}) newline diff --git a/src/markd/rules/footnote_definition.cr b/src/markd/rules/footnote_definition.cr index db0ada4..f0c2c91 100644 --- a/src/markd/rules/footnote_definition.cr +++ b/src/markd/rules/footnote_definition.cr @@ -30,20 +30,46 @@ module Markd::Rule if i == 0 # First line has the footnote definition label removed and # leading spaces removed. - container.data["title"] = line.split("]:")[0].lstrip("[^") + title = line.split("]:")[0] + # Strip exactly the `[^` syntax prefix, not every leading + # `[` or `^` character (labels may legitimately start with them). + title = title[2..] if title.starts_with?("[^") + container.data["title"] = title lines[i] = line.split("]:", 2)[1].lstrip elsif line == "" # Empty lines go as-is lines[i] = "" else - # Subsequent lines have the leading 4 spaces removed - lines[i] = line[4..-1] + # Subsequent lines have the leading indentation removed + lines[i] = strip_code_indent(line) end end # Store the processed text for later block parsing container.text = lines.join("\n") end + # Remove up to CODE_INDENT columns of leading whitespace, expanding + # tabs to their column width, so tab-indented continuation lines keep + # their content instead of losing characters. + private def strip_code_indent(line : String) : String + column = 0 + offset = 0 + while offset < line.size && column < Rule::CODE_INDENT + char = line[offset] + if char == ' ' + column += 1 + offset += 1 + elsif char == '\t' + column += Rule::CODE_INDENT - (column % Rule::CODE_INDENT) + offset += 1 + else + break + end + end + + line[offset..] + end + def can_contain?(type) true end