Skip to content

Add opt-in source-line tracking for editor scroll-sync - #262

Merged
dereuromark merged 1 commit into
masterfrom
feature/source-line-tracking
Jul 18, 2026
Merged

Add opt-in source-line tracking for editor scroll-sync#262
dereuromark merged 1 commit into
masterfrom
feature/source-line-tracking

Conversation

@dereuromark

Copy link
Copy Markdown
Contributor

What

Adds 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:

$html = (new DjotConverter(sourceLines: true))->convert("# Heading\n\nA paragraph.\n");
<section id="Heading">
  <h1 data-source-line="1">Heading</h1>
  <p data-source-line="3">A paragraph.</p>
</section>

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-line matches in the rendered pane, scroll it into view. The 1-based value matches editor gutters (Monaco / CodeMirror).

Details

  • BlockParser gains a trackSourceLines constructor 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">).
  • DjotConverter exposes it as a sourceLines constructor option, threaded to the default parser (ignored when a pre-configured $parser is passed — set new BlockParser(trackSourceLines: true) instead).
  • Off by default, so normal output is unchanged. Raw HTML blocks and comments are not stamped.
  • Documented in the API reference (new "Source-line tracking" section) and the README.

Full suite green (2703 tests), phpstan and phpcs clean.

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

codecov Bot commented Jul 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.37%. Comparing base (f70cf58) to head (71e2c97).

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@dereuromark
dereuromark merged commit 386cb7d into master Jul 18, 2026
6 checks passed
@dereuromark
dereuromark deleted the feature/source-line-tracking branch July 18, 2026 11:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant