Annotations Export

Submodule of Annotations. Exports assembled annotation context to a markdown file or an Obsidian vault via Drush. No web UI — intended for documentation pipelines, AI context preparation, and offline knowledge-base import.

Requirements

annotations (core Annotations module)
annotations_context (context assembly and markdown rendering)

Installation

ddev drush en annotations_export

Drush command

`annotations:export` (alias `ann:ex`)

Assembles annotation context and writes it as markdown or an Obsidian vault.

drush ann:ex                                              # all targets → stdout (markdown)
drush ann:ex --output=context.md                          # write to file
drush ann:ex --format=obsidian --output=/tmp/my-vault  # Obsidian vault (directory created if absent)
drush ann:ex --target=node__article                       # single target
drush ann:ex --entity-type=node                           # all targets of an entity type
drush ann:ex --annotation-types=editorial,rules           # filter by annotation type IDs
drush ann:ex --ref-depth=1                                # follow entity-reference fields one hop
drush ann:ex --inc-meta                                   # include field type/cardinality/description
drush ann:ex --inc-refs                                   # add incoming_refs (reverse ER sources)
drush ann:ex --strip-headings                             # remove # markers for plain-text terminal output

Options

Option	Default	Description
`--format`	`markdown`	Output format: `markdown` or `obsidian`.
`--output`	stdout	Destination path. File path for `markdown`; vault directory for `obsidian` (created if it does not exist). Required for `obsidian`.
`--target`	—	Limit to a single `annotation_target` ID (e.g. `node__article`).
`--entity-type`	—	Limit to all targets of a given entity type (e.g. `node`).
`--annotation-types`	—	Comma-separated annotation type IDs to include (e.g. `editorial,rules`).
`--ref-depth`	`0`	Entity-reference traversal depth (0–2). Follows ER fields into referenced targets.
`--inc-meta`	off	Include field type, cardinality, and help-text description alongside annotations.
`--inc-refs`	off	Add `incoming_refs` to each target — reverse ER sources.
`--strip-headings`	off	Strip `#` heading markers — useful for piping to plain-text tools.

All options are optional and combine freely.

Formats

`markdown`

Renders the full context payload via ContextRenderer to a single UTF-8 markdown string. When --output is omitted the result goes to stdout, preceded by a summary line (target count, ref depth, generated timestamp). When --output is set the file is written directly.

drush ann:ex --target=node__article --ref-depth=1 --output=article-context.md

`obsidian`

Generates one .md file per annotation target in the output directory. Each file includes YAML frontmatter, a heading, bundle-level annotation text, per-field annotation sections, and a Relationships section with [[wikilinks]] to related targets when --ref-depth is greater than 0.

drush ann:ex --format=obsidian --output=/path/to/my-vault --ref-depth=1
# → /path/to/my-vault/node__article.md, node__page.md, media__image.md, ...

The vault directory is created if it does not exist. Re-running to the same path overwrites changed files in place, making it straightforward to keep an existing vault current.

Import the directory into Obsidian as a vault (or drop it into an existing vault folder) to get a navigable knowledge graph of your site's content architecture.

See DEVELOPING.md for ObsidianVaultWriter internals and notes on planned diff-mode and live-sync vault update approaches.