Pelcrow for VS Code

Pelcrow is the governance and integrity layer that sits between your writers, your AI, and everything you publish. It is the system around the writing that catches conflicts at the gate, records provenance, and prevents AI from introducing contradictory answers into your documentation set.

This extension provides the official authoring interface for Pelcrow directly inside VS Code. It bridges your AI authoring agents and your human writers with a fully structured visual editor for Markdown, MDITA, DITA topics, DITA maps, and schema-driven XML.

When connected to your company's Pelcrow workspace, the system provides:

• Structure & Memory: Knows what already exists in your documentation and tells your AI what to reuse.
• Governance: Catches conflicts at the gate and ensures that contradictory answers never enter the documentation set.
• Provenance: Records exactly where every piece of AI-generated content came from with cited sources.
• Human-in-the-Loop Review: Focuses review on the uncertain and changed parts, showing validation findings and cited sources alongside dual-view diffs before anything goes live.
• Writing Policies: Centrally managed, plain-language writing guides that actively dictate how your AI agents draft content.
• Asset Integrity: Tracks images and binary assets in the reuse graph, preventing dangling references and automatically refactoring links when files are renamed.

While the extension connects deeply with Pelcrow to enforce this integrity, it also works as a standalone visual editor for standard Markdown, MDITA, and DITA topics in your Git workflow. DITA maps and other XML documents use the matching organization XML schema.

Features

• Open .md, .markdown, .dita, .ditamap, and .xml files with Pelcrow Visual Editor.
• Reload visual content when the source changes through an AI agent, Git operation, source editor, or another external process.
• Edit headings, emphasis, links, lists, code, images, and source-preserving Markdown tables.
• Apply and remove MDITA data-props conditions from the selection inspector.
• Edit repository-defined YAML metadata with required-field and allowed-value feedback.
• See Pelcrow metadata diagnostics in VS Code Problems.
• View and edit canonical key references and content references as semantic tokens.
• Navigate from a keyref or conref to its workspace definition.
• Switch back to the source editor at any time.

When Pelcrow cannot safely preserve a construct, the custom editor presents a source-mode fallback instead of rewriting the document.

Getting started

1. Open a supported Markdown or XML document.
2. Run Pelcrow: Open Visual Editor, or use Open With... and select Pelcrow Visual Editor.
3. Use the Properties panel for frontmatter and the Selection panel for conditions, images, and references.
4. Use Open Source whenever you need direct control over the MDITA source.

The extension reads metadata rules from .pelcrow/config.json. Local/self-hosted workspaces may instead use pelcrow.config.json with metadataSchemaFile. Set pelcrow.configPath when the server config is outside the workspace root.

For standalone editor use, create .pelcrow/config.json in the repository root. This valid example makes title, owner, and topic type available in the Properties panel without enabling Git push enforcement:

{
  "version": 1,
  "prePushValidation": false,
  "sourceLinkBases": {
    "ticket": "https://example.atlassian.net",
    "spec": "https://example.atlassian.net/wiki/spaces/DOC/pages/",
    "commit": "https://github.com/example/docs",
    "pr": "https://github.com/example/docs"
  },
  "metadataSchema": [
    {
      "key": "title",
      "label": "Title",
      "type": "string",
      "required": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "string",
      "required": true
    },
    {
      "key": "type",
      "label": "Topic type",
      "type": "string",
      "required": true,
      "allowedValues": ["concept", "task", "reference", "troubleshooting"]
    },
    {
      "key": "audience",
      "label": "Audience",
      "type": "string-list",
      "required": false,
      "allowedValues": ["administrator", "developer", "end-user"]
    }
  ]
}

The optional sourceLinkBases entries make bare citations such as ticket:DOC-42, spec:123456789, commit:a1b2c3d, and pr:17 clickable in the Sources panel. Use the Jira site root for ticket, the complete Confluence page prefix for spec, and the GitHub repository URL for commit and pr.

Supported metadata field types are string, string-list, and boolean. allowedValues is optional. In a connected repository, Pelcrow generates and synchronizes this file from the organization and project settings, so do not maintain it by hand.

Commands

• Pelcrow: Open Visual Editor
• Pelcrow: Open Visual Editor to Side
• Pelcrow: Open Source
• Pelcrow: Open Reference Target

Current safety boundary

Canonical empty <span data-keyref="..."></span>, <span data-conref="..."></span>, and <div data-conref="..."></div> elements are supported visually. Key-definition containers, references with nested content or additional attributes, and raw HTML tables remain source-only.

Enterprise Support

For advanced integrations, custom deployment, and enterprise support, visit pelcrow.com to contact sales.