Skip to content

Annotations Export — Developer Reference

Developer-focused reference. For Drush command usage and format descriptions see README.md.

ObsidianVaultWriter

ObsidianVaultWriter (annotations_export.obsidian_vault_writer) writes one .md file per annotation target to an output directory.

$count = $writer->write($payload, '/path/to/vault');
// Returns: int — number of files written
// Throws: RuntimeException on directory creation or write failure

Per-file structure:

  1. YAML frontmatter (--- delimited): target, entity_type, bundle, aliases (array with target label), conditional tags (annotated if annotations/fields exist; {n}-fields if fields are present)
  2. # {label} heading
  3. Bundle-level annotation text (if any)
  4. ## {field_label} section per field, with annotation text beneath
  5. ## Relationships section (if ref_depth > 0) — one bullet per ER relationship as [[dest_target_id]] via \field_name``; wikilinks resolve to sibling vault files

Frontmatter uses Yaml::dump($data, 2, 2) — inline level 2 keeps scalars on one line.

Keeping a vault up to date

Neither of the following approaches is implemented. They are noted here as considered options if incremental vault updates become useful.

Diff-mode export

A --diff flag could be added to ann:ex --format=obsidian. ObsidianVaultWriter would generate content per target, compare it against the existing .md file on disk (byte-for-byte or hash), and only write the file if the content has changed. Orphaned files (targets that no longer exist in scope) would be deleted. Because the writer produces deterministic output, comparison is trivial.

With diff-mode you could schedule a cron job that keeps an existing vault current without rewriting every file on each run:

# cron: run every few minutes
drush ann:ex --format=obsidian --output=/path/to/my-vault --diff

Hook-based live sync

For a more immediate update cycle, a live-sync mode could hook into annotation entity save and delete events. When an annotation is saved or deleted, Drupal would re-export just the single affected target file to a pre-configured vault path stored in Drupal state. A new ann:vault:path /path/to/vault command would set the path.

The tradeoff: the vault must be on a filesystem the web process can write to. A vault on a developer's local machine (synced via a network share or Git) would not update automatically unless the export path points to a location accessible from the server.