Add opt-in source-line tracking for editor scroll-sync - #262
Merged
Conversation
Add a `sourceLines` option (default off) that stamps each top-level block element with a `data-source-line` attribute holding the 1-based source line where the block started. This lets an editor live-preview map rendered blocks back to the source textarea for accurate scroll synchronization. - BlockParser gains a `trackSourceLines` constructor flag; when set, the main block loop stamps newly appended top-level children (the document's direct children) via a small helper. The attribute is added to the node, so it renders through the normal attribute path, after any author attributes. - DjotConverter exposes the flag as a `sourceLines` constructor option, threaded to the default parser. - Off by default, so normal rendering output is unchanged. Raw HTML blocks and comments are not stamped. Documented in the API reference (new "Source-line tracking" section) and the README feature list.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #262 +/- ##
============================================
+ Coverage 92.36% 92.37% +0.01%
- Complexity 3637 3643 +6
============================================
Files 109 109
Lines 10292 10307 +15
============================================
+ Hits 9506 9521 +15
Misses 786 786 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This was referenced Jul 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a
sourceLinesoption (default off) that stamps each top-level block element with adata-source-lineattribute holding the 1-based source line where the block started:Why
Editor live-preview scroll synchronization: read the line of the block at the top of the source pane, find the element whose
data-source-linematches in the rendered pane, scroll it into view. The 1-based value matches editor gutters (Monaco / CodeMirror).Details
BlockParsergains atrackSourceLinesconstructor flag; the main block loop stamps the document's direct children via a small helper. The attribute is set on the node, so it renders through the normal attribute path (after author attributes, e.g.<p class="note" data-source-line="2">).DjotConverterexposes it as asourceLinesconstructor option, threaded to the default parser (ignored when a pre-configured$parseris passed — setnew BlockParser(trackSourceLines: true)instead).Full suite green (2703 tests), phpstan and phpcs clean.