Djot-Extra: Optional Syntax Extension: Definition-Style Metadata

[dereuromark]

Idea: How to support extra syntax that does not contradict the current spec, but also is not yet part of it, so needs to be clearly kept separate and opt-in.

Solution:
A curated set of optional syntax extensions for djot-php that can be toggled on/off.

$converter = new DjotConverter(['extra' => true]);
// or selectively:
$converter = new DjotConverter(['extra' => ['metadata']]);

---

Design Principles

Following the djot rationale:

1. Unambiguous - No syntax conflicts with base djot
2. No backtracking - Parseable in single pass
3. Clear value - Each feature serves real documentation needs
4. Optional - Base djot remains fully functional without extras

Default OFF.
They must be explicitly enabled via the extra option.

---

Proposed Extensions

Definition-Style Metadata

Syntax:

---
title: My Document
author: John Doe
date: 2024-01-15
tags: [djot, documentation, php]
---

Document content starts here...

Rules:

• --- fenced block at document start only
• YAML-style key-value pairs
• Available via $converter->getMetadata()
• Not rendered in output
• --- at document start is unambiguous

Value: Standard document metadata (title, author, date, etc.)

---

Explicitly NOT Included

These violate djot's rationale or add complexity without clear value:

Feature	Reason for Exclusion
Custom containers :::name	Already in base djot via fenced divs
Smart fractions 1/2	Ambiguous with paths, dates
Auto-linking URLs	Conflicts with <url> autolinks
Emoji shortcodes :smile:	Conflicts with symbols :name:
Table alignment |:--:|	Attributes {align=center} exist

---

Implementation Status

Extension	Status	Upstream issue
Metadata	Proposed	jgm/djot#35

---

Usage Example

<?php
use Djot\DjotConverter;

// Enable all extras
$converter = new DjotConverter(['extra' => true]);

// Enable specific extras
$converter = new DjotConverter([
    'extra' => ['abbr', 'captions', 'metadata'],
]);

$djot = <<<'DJOT'
---
title: Getting Started
author: Jane Doe
---

Text starts here
DJOT;

$html = $converter->convert($djot);
$meta = $converter->getMetadata(); // ['title' => 'Getting Started', 'author' => 'Jane Doe']

Why are those not in the cookbook as extensions on user level side?

They are most likely not possible without first level support:

Feature	Extension API?	Why Not
Metadata	❌	Document-start + API needed

---

Feedback

These extensions are proposals. Before implementation:

1. Does this conflict with any base djot syntax?
2. Is the parsing unambiguous?
3. Does it provide clear value for documentation?
4. Is there a simpler way using base djot?

[dereuromark]

People pointed out on the original ticket, that maybe metadata is more complex.

--- {custom key}
title: Getting Started
author: Jane Doe
---
--- {custom other key}
title: Getting Started
author: Jane Doe
---

Allowing maybe even multiple and not parsing the content (too complex).

Maybe those would be the keyed by this {key} and the values the full text as is, the libraries using it can then validate/parse or alike if needed.

---

As for abbr:

The original ticket also proposes an inline format: [HTML]{abbr="HyperText Markup Language"}
It seems elegant - it uses standard djot span + attribute syntax, so no spec collision.

The block-level *[TERM]: Definition syntax from the original issue would require parser extension, but this inline approach is zero-cost and spec-compliant.

So putting abbr on hold then for now, since it was added to extension possibility via cookbook: 105daf3