Skip to content

Add abbreviation definition syntax#385

Open
dereuromark wants to merge 1 commit intojgm:mainfrom
dereuromark:add-abbreviation-syntax
Open

Add abbreviation definition syntax#385
dereuromark wants to merge 1 commit intojgm:mainfrom
dereuromark:add-abbreviation-syntax

Conversation

@dereuromark
Copy link
Copy Markdown
Contributor

@dereuromark dereuromark commented Mar 16, 2026

This PR adds abbreviation definition syntax to djot, enabling automatic wrapping of defined terms in abbreviation elements throughout a document.

Syntax

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

When these abbreviations appear in text, they render as:

<abbr title="Hyper Text Markup Language">HTML</abbr>
<abbr title="World Wide Web Consortium">W3C</abbr>

Rationale

1. Accessibility

Screen readers can expand abbreviations for users, improving comprehension. The <abbr> element with a title attribute is the semantic HTML way to provide this.

2. DRY Principle

Currently, the only way to create abbreviations in djot is manually per occurrence:

[HTML]{title="Hyper Text Markup Language"}

For technical documentation with dozens of acronyms appearing multiple times, this is tedious and error-prone. Define-once, apply-everywhere is more practical.

3. Established Syntax

The *[ABBR]: expansion syntax is well-established:

  • PHP Markdown Extra (2006) - original implementation
  • Pandoc - supports via abbreviations extension
  • Python-Markdown - abbr extension
  • Maruku, kramdown, Marked - all support this syntax
  • djot-php - already implements this

This isn't inventing new syntax—it's adopting a proven pattern.

4. Fits Djot's Design

The syntax mirrors existing djot patterns:

Feature Syntax
Reference link [label]: url
Footnote [^label]: content
Abbreviation *[ABBR]: expansion

The * prefix distinguishes it from links, and the structure is consistent with other definition-style blocks.

5. Non-Breaking Addition

  • New syntax that doesn't conflict with existing constructs
  • *[ at line start isn't valid in current djot
  • Documents without abbreviation definitions are unaffected

Implementation Notes

  • Definitions can appear anywhere in the document
  • Matching is case-sensitive and word-boundary aware
  • Multiple definitions for different cases (HTML vs html) are valid
  • The definitions themselves don't render in output

Prior Art / Requests

Reference Implementation

djot-php implements this syntax and can serve as a reference:
https://php-collective.github.io/djot-php/guide/syntax.html#abbreviations-extension
A corresponding PR for djot.js can follow if this spec change is accepted.

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