Repository navigation
Conversation
d9a392d to
ac17b63
Compare
|
If this is in a stable place, I'm fine to merge this now and sort out the issues in followup PRs. |
|
It implements some basic cases and doesn't seem to break anything at least :-) |
|
I am working now on finishing this. |
|
Weird, tests were passing before, fixing. |
|
Sigh, I asked the LLM to fix ameba warnings and it choose wrong on every one of them. Fixed now :-) |
|
Wonder if the Edit: Same with CLAUDE.md and the like |
Deleted and ignored. |
|
I can't spend any more time working on this PR. |
|
I can carry it from here if you want. |
That would be great, thanks. |
|
I may have some time to work on markpdf these days if the project is still alive. Is there any problem with this PR? |
|
Guess it's dead. If someone wants to pick up the footnotes implementation the code is there. |
|
Sorry about the tantrum. Costs me nothing to keep this PR open for whenever someone wants it. |
There was a problem hiding this comment.
Pull request overview
Implements GitHub Flavored Markdown (GFM) footnotes end-to-end in Markd: parsing inline footnote references and block footnote definitions, post-processing to normalize numbering / resolve nested references, and HTML rendering including backrefs.
Changes:
- Added a new block rule and node types to recognize and store footnote definitions and inline footnote references.
- Added a post-parse footnote processing pass to resolve references (including nesting), normalize numbering, and move definitions to the end.
- Implemented HTML output for footnote refs/definitions and enabled fixture-based coverage for the new behavior.
Reviewed changes
Copilot reviewed 10 out of 11 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/markd/rules/footnote_definition.cr | New block rule to match and collect footnote definition blocks. |
| src/markd/rule.cr | Adds footnote definition start regex and treats [ as “maybe special”. |
| src/markd/renderers/html_renderer.cr | Renders footnote refs/definitions and backrefs; supports valueless (boolean) attributes. |
| src/markd/renderer.cr | Adds abstract renderer hooks for footnote nodes (but currently has a duplicate abstract method). |
| src/markd/parsers/inline.cr | Parses [^label] as a new inline Footnote node in GFM mode. |
| src/markd/parsers/block.cr | Adds passes to parse definition contents as blocks and to resolve/number/move footnotes. |
| src/markd/node.cr | Introduces Footnote / FootnoteDefinition node types and container classification changes. |
| spec/fixtures/gfm-regression.txt | Enables existing regression fixtures that exercise footnotes (including nesting). |
| spec/fixtures/gfm-extensions.txt | Enables GFM extension fixtures for footnotes and escaping behavior. |
| .vscode/launch.json | Removes editor launch configuration from the repo. |
| .gitignore | Ignores spec binary and editor/agent files; broadens VS Code ignore to entire folder. |
Suppressed comments (1)
src/markd/parsers/block.cr:156
footnote_definitionsis deleted from insidefootnote_definitions.each, which can raise due to Hash mutation during iteration. Iterate overkeyssnapshot instead.
footnote_definitions.delete footnote_title
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
I'll do a first round of review using Copilot first. @nobodywasishere hasn't been active in this project for a while—I wonder if she's been busy since joining the Crystal core team. |
|
I am still here. Over the past year though have been dealing with a lot of personal stuff, and wrestling with how programming is changing in the advent of AI. Hard to find the joy in doing things if there's a machine that'll do it much faster than you. |
Understand the feeling |
|
Tried to accept the fix suggestions but after the 1st one now they are stale :-D I will get a minion to look at them |
Cover the edge cases from the Copilot review on PR icyleaf#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
Co-authored-by: Margret Riegert <margret@eowyn.net>
Co-authored-by: Margret Riegert <margret@eowyn.net>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
- 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
Cover the edge cases from the Copilot review on PR icyleaf#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
- add spaces around macro expression in Node#to_s - drop redundant return in Inline#match
# Conflicts: # shard.yml
|
Comments addressed, updated from main |
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.
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.
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.
There was a problem hiding this comment.
🟡 Changes recommended
Active critical and moderate issues remain in footnote parsing, rendering, robustness, and backward compatibility, including runtime errors and incorrect marker placement.
7 open issues
Insert nested footnotes at their marker positions · New Handle unmatched opening brackets without an out-of-bounds access · New Avoid breaking existing Renderer subclasses with new abstract hooks · New Discard or handle duplicate footnote definitions consistently · New Handle a missing previous sibling when appending footnotes · New Strip only the footnote syntax prefix from labels · New Preserve tab-indented footnote continuation content · New
5 resolved since last review
The footnote branch is evaluated after the inline-link parsing block, so[^a](url)will be… Nested-footnote resolution only matches labels made of[\w-](/\[\^([\w\-]+)\]/), but footnote…footnotesis mutated (e.g.,delete, inserting nested labels) while iterating via…FOOTNOTE_DEFINITION_STARTisn't anchored, so it can match[^label]:appearing mid-line and…thematic_breakis declared twice as an abstract method (lines 54 and 76). Crystal will reject…
Review effort: Lite
| 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) |
| if char_at(@pos) == '^' && @options.gfm? | ||
| add_bracket(child, start_pos, footnote: true) |
| 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 |
| elsif !entering && node.type.footnote_definition? | ||
| footnote_definitions[node.data["title"].to_s] = node | ||
| end |
| # <a href="#fnref-label" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a> | ||
| # <a href="#fnref-label-2" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1-2" aria-label="Back to reference 1-2">↩<sup class="footnote-ref">2</sup></a> | ||
| if entering | ||
| if !node.prev.type.footnote_definition? |
| if i == 0 | ||
| # First line has the footnote definition label removed and | ||
| # leading spaces removed. | ||
| container.data["title"] = line.split("]:")[0].lstrip("[^") |
| lines[i] = "" | ||
| else | ||
| # Subsequent lines have the leading 4 spaces removed | ||
| lines[i] = line[4..-1] |
- 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 <noreply@anthropic.com>


This is, AFAIK a full implementation of footnotes as per the specs we have on the repo.