Skip to content

Conversation

@dereuromark
Copy link
Contributor

@dereuromark dereuromark commented Dec 13, 2025

Summary

Adds explicit syntax for creating multiple <dd> elements for the same term in definition lists while maintaining djot spec compliance.

Demo: https://sandbox.dereuromark.de/sandbox/djot?d=OiBEam90CiAoL2TKksmRdC8pCiAgQSBsaWdodHdlaWdodCBtYXJrdXAgbGFuZ3VhZ2UgZGVzaWduZWQgYnkgSm9obiBNYWNGYXJsYW5lLAogIGNyZWF0b3Igb2YgUGFuZG9jIGFuZCBDb21tb25NYXJrLgo6ICsKICBFbmhhbmNlZCBieSBNYXJrIFNjaGVyZXIgYW5kIERqb3QgUEhQIGltcGxlbWVudGF0aW9uIHRvIHN1cHBvcnQgbW9yZSBhd2Vzb21lbmVzcy4KCjogTWFya2Rvd24KOiBDb21tb25NYXJrCjogR0ZNCgogIEVhcmxpZXIgbWFya3VwIGxhbmd1YWdlcyB0aGF0IGluc3BpcmVkIERqb3QncyBkZXNpZ24sCiAgYnV0IHdpdGggbGVzcyBjb25zaXN0ZW50IHBhcnNpbmcgcnVsZXMuCgogIFRoZXkgY2FuIGJlIHVwIHRvIHR3byB0aW1lcyBzbG93ZXIu

The Problem

HTML definition lists support multiple <dd> elements per term (for multiple distinct definitions), but the djot spec uses blank lines for paragraph separation within a single <dd>. There was no way to create multiple <dd> elements.

The Solution

  • Spec compliant: Blank lines within definition content create paragraphs in the same <dd>
  • New syntax: : + marker explicitly creates additional <dd> elements

Example

: Term

  First paragraph

  Second paragraph (same dd - multiple paragraphs)

: +

  Third paragraph (new dd - separate definition)

Produces:

<dl>
<dt>Term</dt>
<dd>
<p>First paragraph</p>
<p>Second paragraph</p>
</dd>
<dd>
<p>Third paragraph</p>
</dd>
</dl>

Roundtrip Support

  • HtmlToDjot converter now outputs : + markers for multiple <dd> elements
  • Full roundtrip fidelity: HTML → Djot → HTML preserves structure

Refs jgm/djot#128

@codecov
Copy link

codecov bot commented Dec 13, 2025

Codecov Report

❌ Patch coverage is 95.65217% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.38%. Comparing base (2946eb7) to head (7d1c3e0).
⚠️ Report is 4 commits behind head on master.

Files with missing lines Patch % Lines
src/Parser/BlockParser.php 95.00% 1 Missing ⚠️
Additional details and impacted files
@@             Coverage Diff              @@
##             master      #49      +/-   ##
============================================
- Coverage     93.72%   93.38%   -0.34%     
+ Complexity     1928     1924       -4     
============================================
  Files            74       74              
  Lines          5177     5173       -4     
============================================
- Hits           4852     4831      -21     
- Misses          325      342      +17     

☔ View full report in Codecov by Sentry.
📢 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 reopened this Dec 13, 2025
@dereuromark dereuromark force-pushed the feature/definition-list-continuation-marker branch from 0f9a93e to cedf46b Compare December 13, 2025 22:12
…lists

- Maintain spec compliance: blank lines within definition content create
  paragraphs in the same <dd> element
- Add new `: +` marker syntax to explicitly create additional <dd> elements
  for the same term when needed
- Update HtmlToDjot converter to output `: +` markers for multiple <dd> elements
- Add skip mechanism for intentional spec deviations in OfficialTestSuiteTest
  (currently empty as we're fully spec compliant)

This approach gives users explicit control over when to create multiple
definitions vs multiple paragraphs within one definition, while maintaining
backwards compatibility with the djot spec.

Example:
```
: Term

  First paragraph (same dd)

  Second paragraph (same dd)

: +

  Third paragraph (new dd)
```
@dereuromark dereuromark force-pushed the feature/definition-list-continuation-marker branch from cedf46b to 4c97d81 Compare December 13, 2025 22:33
@dereuromark dereuromark merged commit 1ea357f into master Dec 15, 2025
5 of 6 checks passed
@dereuromark dereuromark deleted the feature/definition-list-continuation-marker branch December 15, 2025 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

extra beyond standard/specs RFC

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants