DitaCraft

The easiest way to edit and publish your DITA files

VS Code License CI Version

DitaCraft is a comprehensive Visual Studio Code extension for editing and publishing DITA (Darwin Information Typing Architecture) content. It provides syntax highlighting, real-time validation, smart navigation, AI-powered assistance, an MCP server for external AI agents, and seamless integration with DITA-OT for multi-format publishing.

Table of Contents

Highlights

🔗 Smart Navigation - Ctrl+Click on href, conref, keyref, and conkeyref attributes with full key space resolution 🔑 Key Space Resolution - Full DITA 1.3 spec-compliant key space construction: keyref chains, keyscope inheritance (PushDown), inline scope branches, provenance tracking, scope explosion protection (50 k cap), and explainKey() resolution diagnostics ✅ 13-Phase Validation Pipeline - DTD (TypesXML) + optional RelaxNG (salve-annos) + 43 DITA rules + custom rules with DITA 1.2/1.3/2.0 support, per-phase error isolation, severity overrides, and comment-based suppression 🌍 Localized Diagnostics - All 76+ diagnostic messages translatable (English + French included) ⚡ Real-time Validation - Smart debouncing (300ms topics, 1000ms maps) with per-document cancellation 🔒 Enterprise Security - Path traversal protection, XXE neutralization, command injection prevention, and quote-aware entity pre-checks (billion-laughs / XXE bypass-proof) 🚀 One-Click Publishing - Direct DITA-OT integration for HTML5, PDF, EPUB, and more 👁️ Live Preview - Side-by-side HTML5 preview with auto-refresh and bidirectional scroll sync 🗺️ Map Visualizer - Interactive tree view of DITA map hierarchies with navigation 📂 Activity Bar Views - DITA Explorer, Key Space, and Diagnostics views in dedicated sidebar 📝 21 Smart Snippets - Comprehensive DITA code snippets for rapid editing 🛡️ Rate Limiting - Built-in DoS protection for validation operations 🤖 AI-Powered Features - GitHub Copilot integration: @ditacraft chat participant, AI Quick Fix, AI Completion, map restructuring, and multi-provider cascade (Copilot → Anthropic → OpenAI → Ollama) 🔌 MCP Server - Standalone Model Context Protocol server for external AI agents (opencode, Claude Desktop, Cursor, Continue) — 6 tools, 3 resources, zero VS Code dependency 🧪 1564+ Tests - Extensively tested with comprehensive integration, security, and LSP server tests 📚 DITA User Guide - Comprehensive documentation written in DITA (~80 files, bookmap structure)

Features

🖥️ Language Server Protocol (LSP)

  • Full-featured DITA Language Server running in a separate process for performance
  • IntelliSense: Context-aware element, attribute, and value completions with subject scheme hierarchy grouping
  • Hover: Element documentation tooltips from DITA schema with conref content preview
  • Document Symbols: Hierarchical outline view (Ctrl+Shift+O)
  • Workspace Symbols: Cross-file symbol search (Ctrl+T)
  • Go to Definition: Navigate to href/conref/keyref targets with key space resolution
  • Find References: Locate all usages of an element ID across files
  • Rename: Rename IDs with automatic reference updates across workspace
  • Formatting: XML document formatting with inline/block/preformatted handling
  • Code Actions: 12 quick fixes for missing DOCTYPE, missing ID, missing title, empty elements, duplicate IDs, missing otherrole, deprecated indextermref, alt attribute conversion, missing alt text, invalid ID format sanitization, missing booktitle, missing mainbooktitle
  • Linked Editing: Simultaneous open/close XML tag name editing
  • Folding Ranges: Collapse XML elements, comments, and CDATA blocks
  • Document Links: Clickable href/conref/keyref links with key resolution
  • Diagnostics: XML well-formedness, DITA structure, ID, cross-reference, scope consistency, circular reference detection, DITA rules (43 Schematron-equivalent rules including DITA 2.0), profiling/subject scheme, DTD (OASIS catalog with DITA 1.2/1.3/2.0), optional RelaxNG, workspace-level analysis, DITAVAL validation, custom regex rules, per-rule severity overrides, and comment-based rule suppression
  • Localization: All diagnostic messages translatable via i18n system (English + French)

🤖 AI-Powered Features (GitHub Copilot Integration)

  • @ditacraft Chat Participant — Interact with your DITA workspace directly in GitHub Copilot Chat:
    • /restructure — AI-driven DITA map reorganization with diff review before applying
    • /validate — Get AI explanations for validation errors with fix suggestions
    • /explain — Plain-language explanations of DITA structure and element usage
    • /suggest-reuse — Find content reuse opportunities (shared topics, conrefs)
  • F2: AI Map Restructure — Bound to ditacraft.restructureMap; AI proposes a restructured map hierarchy; shows diff and asks for confirmation before writing
  • F3: AI Quick Fix — AI-generated fixes for 12 diagnostic codes (CM-001/002/003, XREF-001/003/004, STRUCT-003/004/005/008, DTD-001, XML-001) via Code Actions → "Fix with AI"
  • F4: AI Completion — Enriched IntelliSense: AI suggests element content and attribute values in context
  • Provider Cascade — Auto mode: Copilot → Anthropic → OpenAI → Ollama; supports copilot-only, byok-only, local-only modes
  • Circuit Breaker — Per-provider resilience: 3 failures in 5 min opens the breaker (10 min cooldown); zero-dependency on unavailable providers
  • Streaming Support — AI responses stream in real time via vscode.lm (Copilot) or server-sent events (Anthropic/OpenAI); Ollama uses /api/generate with streaming chunks
  • Metrics Dashboard — Request counts, latency, and error rates per provider; visible in the Configure AI panel
  • DitaCraft: Configure AI — Guided setup for provider selection, API keys (stored securely via OS keychain), and feature toggles

✍️ Syntax Highlighting & Snippets

  • Syntax highlighting for .dita, .ditamap, .bookmap, and .ditaval files
  • Intelligent code snippets and auto-completion (21 comprehensive snippets)
  • Support for all DITA topic types (concept, task, reference, topic, glossentry, troubleshooting)

🔗 Smart Navigation

  • Ctrl+Click navigation in DITA maps, bookmaps, and topics
    • Click on href attributes in <topicref> elements to open referenced files
    • Click on conref attributes to navigate to content references
    • Click on keyref and conkeyref to navigate to key-defined targets
    • Works with relative paths and handles fragment identifiers (e.g., file.dita#topic_id)
    • Visual link indicators (underlined references when you hover)
    • Hover tooltip showing target filename and reference type
    • Automatically resolves paths relative to the map file location
    • Skips external URLs (http://, https://) - they won't be underlined
  • Full Key Space Resolution (complete as of v0.7.4)
    • Automatically discovers root maps in your workspace
    • Builds and caches key space from map hierarchies (DITA 1.3 spec-compliant BFS)
    • Resolves @keyref, @conkeyref, and key-based references including multi-hop keyref chains
    • Full @keyscope support: PushDown inheritance, inline scope branches, qualified alias explosion cap (50,000 keys)
    • Provenance tracking: each key definition records its source line for diagnostics
    • explainKey() API returns a full KeyResolutionReport with lookup trace and keyref chain steps
    • Tiered caching (1-minute root map discovery, 5-minute key space TTL) with intelligent invalidation
  • Navigate seamlessly between maps and topics in your documentation structure
  • How to use:
    1. Open a .ditamap, .bookmap, or .dita file
    2. Hover over any href, conref, keyref, or conkeyref value - it will be underlined
    3. Ctrl+Click (Windows/Linux) or Cmd+Click (Mac) to open the target file
    4. Works with nested topicrefs, key definitions, and complex map structures

✅ Advanced Validation

  • Real-time validation on file open, save, and change with smart debouncing (300ms topics, 1000ms maps)
  • Full DTD validation against DITA 1.2, 1.3, and 2.0 specifications using TypesXML
    • Bundled DTDs for all three DITA versions (topic, concept, task, reference, map, bookmap, learning, etc.)
    • Master OASIS XML Catalog with <nextCatalog> chaining — auto-resolves PUBLIC IDs for any DITA version
    • Custom XML catalog support (ditacraft.xmlCatalogPath) for DTD specializations
    • Parser pool (3 concurrent instances) for efficient reuse
    • 100% W3C XML Conformance Test Suite compliance
  • Optional RelaxNG validation using salve-annos + saxes
    • Schema compilation with caching (max 20 grammars, JSON cache files)
    • Root element to RNG schema auto-mapping (10 DITA element types)
    • Configurable schema directory path
  • 43 DITA rules (Schematron-equivalent) with DITA version awareness + custom regex rules
    • 4 mandatory rules, 7 recommendation rules, 2 authoring rules, 8 accessibility rules
    • 10 DITA 2.0 removal/migration rules (deprecated elements and attributes)
    • Version-gated: rules apply only to relevant DITA versions
    • Precise attribute-level diagnostic highlighting
    • Custom regex rules from user-defined JSON file with fileType filtering and mtime-based caching
    • Per-rule severity overrides — change any diagnostic code's severity or suppress it entirely
    • Comment-based rule suppression — <!-- ditacraft-disable CODE --> / <!-- ditacraft-enable CODE --> / <!-- ditacraft-disable-file CODE -->
    • Large file optimization — heavy validation phases skipped for files exceeding configurable size threshold
  • Three validation engines:
    • TypesXML (default, recommended) - Pure TypeScript DTD validation with no native dependencies
    • Built-in parser with content model checking (lightweight, no full DTD)
    • xmllint integration for external validation (requires libxml2 installation)
  • DITA version detection: Auto-detects from @DITAArchVersion attribute or DOCTYPE declaration
  • Scope validation: Validates scope="local|peer|external" consistency with href format (DITA-SCOPE-001/002/003)
  • Circular reference detection: Detects href/conref/mapref cycles using DFS traversal (DITA-CYCLE-001)
  • Workspace-level analysis:
    • DITA: Validate Workspace command with progress reporting
    • Cross-file duplicate root ID detection (DITA-ID-003)
    • Unused topic detection — finds topics not referenced by any map (DITA-ORPHAN-001)
  • Enterprise Security Features:
    • XXE (XML External Entity) neutralization to prevent injection attacks
    • Path traversal protection with workspace bounds validation
    • Command injection prevention using safe execution methods
    • Async file operations to prevent LSP event loop blocking
    • Quote-aware entity pre-check — ]> inside quoted entity values cannot bypass billion-laughs or excessive-entity-count detection (defense-in-depth, CVE-class)
  • Intelligent error highlighting:
    • Inline error highlighting with squiggly underlines
    • Errors appear in Problems panel with severity indicators
    • Accurate line and column positioning
    • Source attribution (DTD validator, XML parser, DITA validator, dita-rules)
  • Auto-detection of DITA files:
    • By extension: .dita, .ditamap, .bookmap, .ditaval
    • By DOCTYPE: Recognizes DITA DOCTYPE declarations in .xml files
  • Manual validation command: DITA: Validate Current File (Ctrl+Shift+V / Cmd+Shift+V)

🚀 One-Click Publishing

  • Publish to multiple formats: HTML5, PDF, EPUB, and more
  • Direct integration with DITA Open Toolkit (DITA-OT)
  • Real-time progress tracking with visual indicators
  • Smart caching for faster preview generation

👁️ Live Preview

  • Side-by-side HTML5 preview with WebView panel
  • Auto-refresh on save with configurable behavior
  • Bidirectional scroll sync - Editor and preview scroll positions stay synchronized
  • Theme support - Light, dark, and auto modes (follows VS Code theme)
  • Custom CSS - Apply custom stylesheets to preview
  • Print preview mode - Print-optimized view with dedicated print button
  • Navigate directly from source to preview

📊 Build Output

  • Syntax-highlighted output - DITA-OT build output with automatic colorization
  • Log level detection - Errors, warnings, info, and debug messages color-coded
  • Error diagnostics - Build errors parsed and shown in Problems panel
  • Timestamped builds - Build start and completion times displayed
  • Validation report - Full guide validation results in WebView panel with filtering, search, and export

📂 Activity Bar Views

  • DitaCraft sidebar in the Activity Bar with three dedicated tree views
  • DITA Explorer — All workspace maps with expandable hierarchy, type icons, click-to-open navigation
  • Key Space View — Defined, undefined, and unused keys with usage locations and key scope support
  • Diagnostics View — Aggregated DITA issues, group by file or severity, click-to-navigate
  • Root Map Selector — Status bar indicator with click-to-set, auto-discover or explicit mode
  • File decorations — Error/warning badges on tree items from validation diagnostics
  • Welcome content — Helpful actions shown when views are empty
  • Auto-refresh on file and diagnostics changes with debouncing

🗺️ Map Visualizer

  • Interactive tree view - Visual hierarchy of DITA maps, bookmaps, and topics
  • Element type icons - Different icons for maps, chapters, appendices, parts, topics, keys, and glossrefs
  • Missing file detection - Missing referenced files shown with strikethrough styling
  • Circular reference protection - Detects and marks circular map references
  • Double-click navigation - Open any topic or map directly from the visualizer
  • Expand/Collapse controls - Easily navigate large map hierarchies
  • Real-time refresh - Update the visualization when map content changes

🎯 Quick File Creation

  • Create DITA topics from templates (concept, task, reference)
  • Generate DITA maps and bookmaps with proper structure
  • Pre-filled DOCTYPE declarations and valid XML structure

⚙️ Flexible Configuration

  • Configure DITA-OT installation path
  • Customize output formats and directories
  • Add custom DITA-OT arguments and filters
  • Choose validation engine (xmllint or built-in)

Installation

From VS Code Marketplace

  1. Open VS Code
  2. Press Ctrl+P / Cmd+P
  3. Type ext install ditacraft
  4. Press Enter

From VSIX

  1. Download the latest .vsix file from Releases
  2. Open VS Code
  3. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
  4. Click ... menu → "Install from VSIX..."
  5. Select the downloaded file

Local Installation for Development

If you want to install the plugin locally from source code for development or testing:

Step 1: Prerequisites

Ensure you have the following installed:

  • Node.js 18.x or 20.x (Download)
  • npm (comes with Node.js)
  • VS Code 1.80 or higher
  • Git (optional, for cloning)

Step 2: Get the Source Code

# Clone the repository (or download ZIP from GitHub)
git clone https://github.com/jyjeanne/ditacraft.git
cd ditacraft

# OR if you downloaded as ZIP:
# Extract the ZIP file and navigate to the extracted folder
cd DitaCraft

Step 3: Install Dependencies

npm install

This will install all required npm packages (~429 packages).

Step 4: Compile TypeScript

npm run compile

This compiles the TypeScript source code to JavaScript in the out/ directory.

Step 5: Package the Extension

npm run package

This creates a .vsix file in the project root (e.g., ditacraft-0.1.0.vsix).

Note: If you don't have vsce installed, install it first:

npm install -g @vscode/vsce

Step 6: Install in VS Code

Option A: Install from VSIX

  1. Open VS Code
  2. Press Ctrl+Shift+X (or Cmd+Shift+X on macOS) to open Extensions
  3. Click the ... menu at the top right
  4. Select "Install from VSIX..."
  5. Navigate to your project folder
  6. Select the ditacraft-0.1.0.vsix file
  7. Click "Install"
  8. Reload VS Code when prompted

Option B: Run in Development Mode (Recommended for testing)

  1. Open the ditacraft folder in VS Code
  2. Press F5 (or Run → Start Debugging)
  3. A new VS Code window opens with the extension loaded
  4. Test the extension in this window
  5. Make changes to code, save, and press Ctrl+R in the Extension Host window to reload

Step 7: Verify Installation

  1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  2. Type "DITA" - you should see all DitaCraft commands
  3. Try creating a new topic: "DITA: Create New Topic"

Step 8: Configure DITA-OT (Optional, for publishing)

  1. Download DITA-OT from https://www.dita-ot.org/download
  2. Extract to a location (e.g., C:\DITA-OT-4.2.1)
  3. In VS Code, run "DITA: Configure DITA-OT Path"
  4. Select your DITA-OT installation directory

Troubleshooting Local Installation

Issue: npm install fails

Solution:

  • Check Node.js version: node --version (should be 18.x or 20.x)
  • Clear npm cache: npm cache clean --force
  • Delete node_modules and package-lock.json, then run npm install again

Issue: Compilation errors

Solution:

  • Ensure TypeScript is installed: npm install -g typescript
  • Check for syntax errors in .ts files
  • Run npm run lint to check for code issues

Issue: Extension not appearing in VS Code

Solution:

  • Verify the .vsix file was created successfully
  • Check VS Code version is 1.80 or higher
  • Try uninstalling any existing version first
  • Restart VS Code completely

Issue: "Cannot find module" errors

Solution:

  • Run npm install again
  • Check that node_modules directory exists
  • Verify package.json has all dependencies

Development Workflow

For active development on the extension:

# Terminal 1: Watch mode (auto-compile on changes)
npm run watch

# Terminal 2: Run extension in debug mode
# Press F5 in VS Code (or Run → Start Debugging)

Making Changes:

  1. Edit TypeScript files in src/
  2. Watch mode auto-compiles to out/
  3. In Extension Host window, press Ctrl+R (or Cmd+R) to reload
  4. Test your changes

Running Tests:

npm test

Linting Code:

npm run lint

Prerequisites

Required

  • VS Code 1.80 or higher
  • Node.js 18.x or 20.x (for development)

For Publishing

For Alternative Validation (Optional)

  • xmllint (libxml2) for external XML validation (TypesXML is the default and recommended engine)

Quick Start

1. Install DITA-OT

Download and install DITA-OT from https://www.dita-ot.org/download

2. Configure DitaCraft

  1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  2. Type "DITA: Configure DITA-OT Path"
  3. Select your DITA-OT installation directory

3. Create Your First DITA File

  1. Open Command Palette
  2. Type "DITA: Create New Topic"
  3. Select topic type (concept, task, reference)
  4. Enter file name

4. Publish

  1. Open your .dita, .ditamap, or .bookmap file
  2. Press Ctrl+Shift+B / Cmd+Shift+B
  3. Select output format (HTML5, PDF, etc.)
  4. View published content

Commands

All commands are accessible via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Command Shortcut Description
DITA: Validate Current File Ctrl+Shift+V Validate DITA syntax and structure
DITA: Publish (Select Format) Ctrl+Shift+B Publish with format selection
DITA: Publish to HTML5 - Quick publish to HTML5
DITA: Preview HTML5 Ctrl+Shift+H Show live HTML5 preview
DITA: Show Map Visualizer - Show interactive map hierarchy
DITA: Create New Topic - Create new DITA topic
DITA: Create New Map - Create new DITA map
DITA: Create New Bookmap - Create new bookmap
DITA: Configure DITA-OT Path - Set DITA-OT installation path
DITA: Set Root Map - Choose explicit root map for key resolution
DITA: Clear Root Map - Revert to automatic root map discovery
DITA: Validate Workspace - Validate all DITA files across workspace
DITA: Validate Entire Guide - Full DITA-OT validation of root map with report panel
DITA: Configure AI Settings - Configure AI provider, API keys, and feature toggles
DITA: Restructure Map with AI F2 AI-driven map restructuring with diff review
DITA: Setup cSpell Configuration (deprecated) - Create a lean cSpell config for DITA files

Spell Checking with cSpell

DitaCraft provides a lean .cspellrc.json template that works alongside the LSP server. Rather than maintaining a large DITA word list (which is now handled by the LSP), the configuration uses regex-based patterns to silently ignore XML tags and attribute syntax, so cSpell focuses exclusively on prose spelling errors in your content.

What the config does

The generated .cspellrc.json:

  • Suppresses XML tag noise — ignores <element-name> and attr="value" patterns inside DITA files via ignoreRegExpList, so cSpell doesn't flag DITA markup as misspelled words
  • Leaves prose spell-checking intact — actual text content in <p>, <title>, <shortdesc>, etc. is still checked
  • Includes a TypeScript word allowlist — common DITA/LSP terms (dita, keyref, conref, oasis, vscode, etc.) allowed in .ts source files
  • Ignores generated/binary paths — node_modules, out, dist, .git, *.ditaval excluded

Note: The DITA: Setup cSpell Configuration command is deprecated. The DITA Language Server now handles DITA vocabulary validation; cSpell is only needed for prose spell-checking.

Setup cSpell

Option 1: Run the command (still works, now creates the lean config)

  1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  2. Type "DITA: Setup cSpell Configuration"
  3. Click the command — DitaCraft creates a .cspellrc.json in your workspace root

Option 2: Manual setup

Create .cspellrc.json at your workspace root:

{
  "version": "0.2",
  "language": "en",
  "ignorePaths": ["node_modules", "out", "dist", ".git", ".vscode-test", "*.ditaval"],
  "overrides": [
    {
      "filename": "**/*.{dita,ditamap,bookmap,xml}",
      "ignoreRegExpList": ["<[^>]+>", "\\s[a-zA-Z-]+=(\"[^\"]*\"|'[^']*')"]
    },
    {
      "filename": "src/**/*.ts",
      "words": ["dita","dtd","conref","keyref","topicref","ditamap","xml","xpath","oasis","vscode","textmate"]
    }
  ]
}

Configuration

Basic Settings

{
    "ditacraft.ditaOtPath": "C:\\DITA-OT-4.2.1",
    "ditacraft.defaultTranstype": "html5",
    "ditacraft.outputDirectory": "${workspaceFolder}/out"
}

All Settings

Setting Type Default Description
ditacraft.ditaOtPath string "" DITA-OT installation path
ditacraft.defaultTranstype string "html5" Default output format
ditacraft.outputDirectory string "${workspaceFolder}/out" Output directory
ditacraft.autoValidate boolean true Auto-validate on save
ditacraft.previewAutoRefresh boolean true Auto-refresh preview
ditacraft.previewScrollSync boolean true Bidirectional scroll sync
ditacraft.previewTheme string "auto" Preview theme (auto/light/dark)
ditacraft.previewCustomCss string "" Custom CSS for preview
ditacraft.showProgressNotifications boolean true Show progress notifications
ditacraft.validationEngine string "built-in" Validation engine (built-in/typesxml/xmllint)
ditacraft.ditaOtArgs array [] Custom DITA-OT arguments
ditacraft.enableSnippets boolean true Enable code snippets
ditacraft.maxNumberOfProblems number 100 Maximum diagnostics per file
ditacraft.ditaRulesEnabled boolean true Enable Schematron-equivalent DITA rules
ditacraft.ditaRulesCategories string[] all Rule categories to activate (mandatory, recommendation, authoring, accessibility)
ditacraft.crossRefValidationEnabled boolean true Validate cross-file references (href, conref, keyref)
ditacraft.subjectSchemeValidationEnabled boolean true Validate attribute values against subject schemes
ditacraft.rootMap string "" Explicit root map path (relative to workspace). Empty = auto-discover
ditacraft.xmlCatalogPath string "" Path to external XML catalog for custom DTD specializations
ditacraft.validationSeverityOverrides object {} Per-rule severity overrides (e.g., {"DITA-SCH-001": "hint", "DITA-ID-002": "off"})
ditacraft.largeFileThresholdKB number 500 Skip heavy validation phases for files larger than this (0 = disabled)
ditacraft.customRulesFile string "" Absolute path to a JSON file defining custom regex validation rules

📖 See the All Settings reference table above for the full list of configuration options.

AI Provider Configuration

DitaCraft supports four LLM backends with automatic fallback. This section shows how to set up each one.

Provider Overview

Provider Requires Privacy Best For
GitHub Copilot Active Copilot subscription Data sent to GitHub Default — zero config
Anthropic Claude ANTHROPIC_API_KEY (BYOK) Data sent to Anthropic Best reasoning quality
OpenAI (ChatGPT / GPT-4o) OPENAI_API_KEY (BYOK) Data sent to OpenAI Broad compatibility
Ollama (local) Ollama running on your machine Stays local Air-gapped / privacy-first

The active mode is set with ditacraft.ai.mode:

{
  "ditacraft.ai.mode": "auto"
}
Value Behaviour
"auto" Copilot first, then Anthropic, then OpenAI, then Ollama
"copilot-only" Only GitHub Copilot (error if no Copilot subscription)
"byok-only" Only Anthropic / OpenAI (skips Copilot entirely)
"local-only" Only Ollama — no data leaves your machine

🤖 GitHub Copilot (Default — No Setup Required)

DitaCraft uses the built-in vscode.lm API; no npm package or API key needed.

Requirements:

  • GitHub Copilot extension installed and signed in
  • Active Copilot Individual, Business, or Enterprise subscription

Steps:

  1. Install the GitHub Copilot extension
  2. Sign in with your GitHub account
  3. DitaCraft auto-detects Copilot and uses it immediately — nothing else to configure

Optional override (to use a specific Copilot model):

{
  "ditacraft.ai.mode": "copilot-only"
}

🧠 Anthropic Claude (BYOK)

Claude is the highest-quality model available for structured content tasks like DITA map restructuring.

Supported models: claude-3-5-sonnet-20241022 (default), claude-3-opus-20240229, claude-3-haiku-20240307

Steps:

  1. Get an API key from console.anthropic.com
  2. Open the Command Palette and run DitaCraft: Configure AI Settings
  3. In the panel, paste your key into the Anthropic field and click Save Key
  4. The key is stored in your OS keychain via vscode.SecretStorage — never in settings.json
  5. Optionally choose your model:
{
  "ditacraft.ai.mode": "byok-only",
  "ditacraft.ai.provider.anthropic.model": "claude-3-5-sonnet-20241022"
}

Key format: Anthropic API keys start with sk-ant-. Keys not matching this prefix are rejected before any network call.

💬 OpenAI / ChatGPT (BYOK)

Supports GPT-4o (default), GPT-4 Turbo, and other OpenAI Chat Completions models.

Supported models: gpt-4o (default), gpt-4-turbo, gpt-4, gpt-3.5-turbo

Steps:

  1. Get an API key from platform.openai.com
  2. Run DitaCraft: Configure AI Settings from the Command Palette
  3. Paste your key into the OpenAI field and click Save Key
  4. Optionally set the model:
{
  "ditacraft.ai.mode": "byok-only",
  "ditacraft.ai.provider.openai.model": "gpt-4o"
}

OpenAI-compatible APIs (LM Studio, Jan, etc.): These are not yet supported natively, but you can expose them via Ollama's OpenAI-compatible proxy endpoint in the meantime.

🏠 Local LLM with Ollama (Air-Gapped / Privacy Mode)

Ollama lets you run open-source models entirely on your machine — no data ever leaves your computer.

Install Ollama: ollama.ai

Recommended DITA-capable models:

Model Command Context Notes
llama3 ollama pull llama3 8 k Default; good general quality
llama3.1 ollama pull llama3.1 128 k Large context — better for big maps
mistral ollama pull mistral 8 k Fast, lighter footprint
codellama ollama pull codellama 16 k Good for XML/structured content
gemma3 ollama pull gemma3 8 k Google Gemma 3 (open weights)
phi3 ollama pull phi3 8 k Microsoft Phi-3; compact and fast

Steps:

  1. Install and start Ollama: ollama serve
  2. Pull your preferred model: ollama pull llama3
  3. Configure DitaCraft:
{
  "ditacraft.ai.mode": "local-only",
  "ditacraft.ai.provider.ollama.enabled": true,
  "ditacraft.ai.provider.ollama.baseUrl": "http://localhost:11434",
  "ditacraft.ai.provider.ollama.model": "llama3"
}
  1. Run DitaCraft: Configure AI Settings and click Test Connection to verify Ollama is reachable

Custom Ollama endpoint (remote server / Docker):

{
  "ditacraft.ai.provider.ollama.baseUrl": "http://my-gpu-server:11434"
}

Gemini via Ollama: Google does not publish full Gemini weights, but you can run gemma3 (Google's open-weights model) locally via ollama pull gemma3. For cloud Gemini (Gemini 1.5 Pro etc.), native support is planned in a future release.

☁️ Gemini (Google) — Planned

Native Google Gemini support (gemini-1.5-pro, gemini-1.5-flash) is planned for a future release via the Google Generative AI SDK.

Workarounds available today:

  • Local Gemma — run Google's open-weights model via Ollama: ollama pull gemma3
  • OpenAI-compatible proxy — expose Gemini through a proxy that implements the OpenAI Chat Completions API

Track progress: see the Roadmap section.

⚙️ Full AI Settings Reference

{
  "ditacraft.ai.enabled": true,
  "ditacraft.ai.mode": "auto",
  "ditacraft.ai.provider.anthropic.model": "claude-3-5-sonnet-20241022",
  "ditacraft.ai.provider.openai.model": "gpt-4o",
  "ditacraft.ai.provider.ollama.enabled": true,
  "ditacraft.ai.provider.ollama.baseUrl": "http://localhost:11434",
  "ditacraft.ai.provider.ollama.model": "llama3",
  "ditacraft.ai.context.maxTokens": 8000,
  "ditacraft.ai.quickfix.enabled": true,
  "ditacraft.ai.completion.enabled": true,
  "ditacraft.ai.streaming.enabled": true
}

MCP Server Integration (External AI Agents)

DitaCraft exposes its DITA intelligence — validation, key space, context snapshots — over the Model Context Protocol (MCP), letting external AI coding agents read and query your DITA workspace.

Status: MCP server is available in v0.8.0 (current). Build with npm run build-standalone to produce dist/mcp-server.js and dist/lsp-server.js.

What is MCP?

Model Context Protocol is an open standard (by Anthropic) that lets AI agents call tools and read resources from external servers. Compatible agents include opencode, Claude Desktop, Continue, Cursor, and any MCP-aware tool.

DitaCraft MCP Server

Run npm run build-standalone then configure your agent:

Tool Description
dita_validate Validate a DITA file or XML fragment and return diagnostics
dita_context_snapshot Token-budgeted map snapshot for LLM injection (L1/L2/L3)
dita_key_space List all defined keys and their resolved targets
dita_map_structure Return the full topic hierarchy (JSON/tree/CSV)
dita_resolve_reference Resolve an href/keyref/conref/conkeyref to its target
dita_explain_key Detailed step-by-step key resolution trace
Resource Description
dita://workspace/maps All DITA maps in the workspace
dita://workspace/diagnostics Current validation diagnostics
dita://workspace/keys Full key space

Using DitaCraft with opencode

// ~/.config/opencode/opencode.json
{
  "mcpServers": {
    "ditacraft": {
      "command": "node",
      "args": ["/path/to/ditacraft/dist/mcp-server.js"],
      "env": {
        "WORKSPACE": "/home/user/projects/my-dita-docs"
      }
    }
  }
}

> @ditacraft validate topics/intro.dita
> @ditacraft show me the map structure as a tree
> @ditacraft explain why keyref install-guide isn't resolving

Using DitaCraft with Claude Desktop

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "ditacraft": {
      "command": "node",
      "args": ["/absolute/path/to/dist/mcp-server.js"],
      "env": { "WORKSPACE": "/path/to/dita/project" }
    }
  }
}

Standalone LSP Server

DitaCraft also ships a standalone LSP server bundle for embedding in other Node.js projects:

npm run build-standalone
# → dist/lsp-server.js (2.0 MB) — self-contained, no node_modules needed

# Launch as headless LSP server:
node dist/lsp-server.js --stdio

Embed in any Node.js LSP client via child_process.spawn:

const { spawn } = require('child_process');
const server = spawn('node', ['lsp-server.js', '--stdio'], {
    env: { DITACRAFT_EXTENSION_ROOT: __dirname },
});
// Communicate via server.stdin / server.stdout using vscode-languageserver

Supported Output Formats

DitaCraft supports all DITA-OT transtypes:

  • HTML5 - Modern responsive HTML
  • PDF - PDF via Apache FOP
  • XHTML - XHTML output
  • EPUB - EPUB3 e-books
  • HTML Help - Windows CHM files
  • Markdown - Markdown conversion

Additional formats available through DITA-OT plugins.

Workflows

Navigating Your Documentation Structure

  1. Open a .ditamap or .bookmap file
  2. Ctrl+Click (Cmd+Click on Mac) on any href attribute value in <topicref> elements
  3. The referenced topic file opens in a new tab
  4. Navigate back and forth between map and topics seamlessly

Example:

<map>
    <topicref href="introduction.dita"/>     <!-- Ctrl+Click opens introduction.dita -->
    <topicref href="chapters/ch1.dita"/>     <!-- Works with relative paths -->
    <topicref href="overview.dita#intro"/>   <!-- Handles fragment IDs -->
</map>

Publishing a Book

  1. Create bookmap: DITA: Create New Bookmap
  2. Create chapters: DITA: Create New Topic (multiple times)
  3. Edit bookmap to reference chapters
  4. Use Ctrl+Click navigation to quickly jump between bookmap and chapter files
  5. Validate: Ctrl+Shift+V
  6. Publish: Ctrl+Shift+B → Select format
  7. Open output folder

Previewing Changes

  1. Open .dita file
  2. Make edits
  3. Press Ctrl+Shift+H to preview
  4. Preview auto-refreshes on save
  5. Toggle between source and preview

Using Filters (DITAVAL)

{
    "ditacraft.ditaOtArgs": [
        "--filter=filters/product-a.ditaval"
    ]
}

Development

Building from Source

# Clone repository
git clone https://github.com/jyjeanne/ditacraft.git
cd ditacraft

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Run tests
npm test

# Package extension
npm run package

Project Structure

ditacraft/
├── src/                         # Client-side extension code
│   ├── extension.ts             # Entry point
│   ├── commands/                # Command handlers
│   ├── providers/               # Tree views, validation, link & decoration providers
│   ├── utils/                   # Utilities (DITA-OT, key space, map parser, rate limiter)
│   └── test/                    # Client test suites (683+ tests)
├── server/                      # LSP Language Server (separate process)
│   ├── src/
│   │   ├── server.ts            # Server entry point & capability registration
│   │   ├── serverHandlers.ts    # Extracted LSP handler wiring & capabilities
│   │   ├── features/            # LSP feature handlers
│   │   │   ├── validation.ts    # Diagnostics (XML, DITA structure, IDs)
│   │   │   ├── completion.ts    # IntelliSense completions
│   │   │   ├── hover.ts         # Hover documentation
│   │   │   ├── symbols.ts       # Document & workspace symbols
│   │   │   ├── definition.ts    # Go to definition
│   │   │   ├── references.ts    # Find references
│   │   │   ├── rename.ts        # Rename with reference updates
│   │   │   ├── formatting.ts    # XML formatting
│   │   │   ├── codeActions.ts   # Quick fixes (12 actions)
│   │   │   ├── linkedEditing.ts # Tag name sync editing
│   │   │   ├── folding.ts       # Folding ranges
│   │   │   ├── documentLinks.ts # Clickable links
│   │   │   ├── crossRefValidation.ts    # Cross-file reference + scope validation
│   │   │   ├── circularRefDetection.ts  # Circular reference detection (DFS)
│   │   │   ├── workspaceValidation.ts   # Cross-file duplicate IDs, unused topics
│   │   │   ├── ditaRulesValidator.ts    # 43 Schematron-equivalent DITA rules (incl. DITA 2.0)
│   │   │   ├── profilingValidation.ts   # Subject scheme controlled values
│   │   │   └── customRulesValidator.ts  # User-defined regex validation rules
│   │   ├── services/            # Domain services with caching
│   │   │   ├── validationPipeline.ts       # 13-phase orchestration
│   │   │   ├── suppressionEngine.ts        # Comment-based rule suppression
│   │   │   ├── interfaces.ts               # Service interfaces (IKeySpaceService, etc.)
│   │   │   ├── catalogValidationService.ts # DTD validation (TypesXML)
│   │   │   ├── rngValidationService.ts     # RNG validation (salve-annos)
│   │   │   ├── keySpaceService.ts