0002: Md-isms as morg_-prefixed properties, native org constructs preferred

Status

Accepted (2026-09-10). Frontmatter superseded by ADR 0005 (2026-10-01): it travels as a marked comment block, not as keywords or properties.

Context

md → org must preserve Markdown constructs org cannot express natively (raw HTML, frontmatter (see ADR 0005), image title attributes, heading level under nestUnderHeadings, …) so the round trip can restore them. Storing them as org properties raises two questions: how to name the properties without colliding with user-authored ones, and how to encode non-scalar values given org property values are single-line.

Decision

  1. Prefix all core-emitted properties with morg_ (e.g. :morg_heading:). On org → md, only morg_-prefixed properties are consumed and restored; anything else is user data and passes through untouched. Unambiguous ownership is required for Convergence.
  2. Prefer native org constructs over properties when org has one: raw HTML becomes #+begin_export html, not a property. Properties are reserved for metadata-shaped md-isms.
  3. Values: plain scalars as-is; structured or multiline values JSON-encoded on a single line.
  4. Presets may override names with the target application's own conventions (Logseq: heading::), because there the application, not morg, is the consumer.
  5. Names are user-configurable (config file, post-bootstrap). Consequently Convergence is guaranteed per-config: round-tripping a file requires the same property-name mapping it was written with.

Consequences