Skip to content

Annotations Documents

Generates AI-authored documentation for your annotation targets and stores it in a two-panel browser.

Requirements

  • Annotations (root module)
  • Annotations Context
  • Drupal AI with a configured default chat provider
  • Content Translation (core) — optional; only needed if you want to generate documents in more than one language. Not a hard dependency, and the language picker only appears if your site is already multilingual.

Installation

ddev drush en annotations_docs

The module installs an annotations_document content type with four fields: annotations_doc_body, annotations_doc_target, annotations_doc_type, and annotations_doc_locked. This content type is intentionally excluded from the annotation targets list.

Usage

Before generating, at least one annotation type must have In AI context enabled (Admin > Annotations > Types > edit a type). This module sends annotation content to an AI provider, so it only ever generates for types opted into AI context — the same gate the MCP endpoint and the Tool API integration use. A type with content but without this setting is silently excluded from generation, and generating with none enabled at all fails immediately with an explanatory error.

  1. Navigate to Content > Annotations > Documents (/annotations/documents)
  2. The left panel lists all annotation targets grouped by entity type
  3. Targets with existing documents are clickable; targets without show a Generate link
  4. Click Generate to open the confirmation form. Choose an Audience (a role) to only generate the annotation types that role is permitted to see, or leave it as "All types" to generate without filtering. On a multilingual site, also choose a Language.
  5. Click the button to trigger generation — a progress indicator appears while the AI provider is called once per included annotation type, then the page redirects to the target's documents on completion. A target with more than one generated type shows a tab per type at the top of the main panel; a document with more than one language shows a language switcher.
  6. Review each draft; click Edit to refine, then set the node's status to Published. Every document starts, and stays, unpublished until you do this — publishing is always a manual step, including after a regenerate.
  7. Click Regenerate at any time to produce fresh drafts for the same target — this re-runs generation for whichever role/language you choose on the confirmation form, and overwrites any existing document for that type and language, subject to the overwrite protection below.

Overwrite protection

  • Lock a document by editing it and checking Locked. A locked document is skipped on regenerate with an on-screen error, unless you hold administer annotation documents, in which case regeneration proceeds and you'll see a warning that you overrode a lock.
  • Hand-edited documents are protected automatically, no locking required: if you edit a document's body directly and someone later regenerates it, they'll see a warning (with a link to that document's revision history) after the overwrite happens. An untouched AI draft never triggers this — only a real edit does, so routine regeneration after your source annotations change stays silent.

Permissions

Permission Purpose
access annotation documents View the browser and document nodes directly (published documents only — see below)
generate annotation documents Trigger AI generation and regeneration
administer annotation documents Full administration, including viewing unpublished/draft documents; implies access annotation documents but not generate annotation documents — generation must always be explicitly granted because it triggers potentially paid AI API calls

Viewing a document also requires consume {type} annotations for whichever annotation type it was generated from (or administer annotations) — the same permission that gates that type everywhere else in the suite.

Customizing the system prompt

The AI system prompt is stored as a config entity at ai.ai_prompt.annotations_docs__generate__default and can be edited at Admin > Config > AI > Prompts. Changes take effect immediately on the next generation. The same prompt is shared across every annotation type — there's no separate prompt per type yet.