What Makes DitaCraft the VS Code Extension DITA Writers Have Been Waiting For

As technical writers and developers, we constantly look for tools that don’t just support structured writing — they fundamentally change how we think, organize, and produce documentation. That’s the ambition behind DitaCraft, an open-source Visual Studio Code extension built to bring the full power of DITA (Darwin Information Typing Architecture) into a modern developer workflow.

DITA is the gold standard for structured technical documentation in enterprise environments. Yet the tooling ecosystem has historically required expensive commercial authoring suites , creating a painful divide between developers working in VS Code all day and technical writers forced into separate, heavyweight environments.

DitaCraft closes that gap. Let's take a deep dive into what makes it genuinely special.

🔗 Smart Navigation That Understands Your DITA Structure

DITA documentation isn't a folder of independent files. It's a web of relationships: topics referenced in maps, content reused through conref, keys resolved across map hierarchies. Most editors treat your DITA files as simple XML — DitaCraft treats them as what they actually are: a structured knowledge graph.

Ctrl+Click navigation works across the full spectrum of DITA reference types:

• href on <topicref> elements — opens the referenced .dita file directly
• conref attributes — jumps to the specific reused content element
• keyref and conkeyref — resolves the key through the full key space and navigates to the target

Hover over any reference attribute and it becomes underlined, showing a tooltip with the target filename and reference type. It works with relative paths, fragment identifiers (e.g., file.dita#topic_id), and correctly skips external URLs.

Full Key Space Resolution

This is where DitaCraft earns serious credibility. Key-based referencing in DITA is notoriously hard to resolve without building a full map-aware engine. DitaCraft does exactly that:

• Automatically discovers root maps in your workspace
• Builds and caches the complete key space from the entire map hierarchy, including submaps and nested maps
• Resolves @keyref, @conkeyref, and key-based href references against this key space
• Maintains a 1-minute cache TTL with intelligent invalidation when map files change
• Uses 300ms file watcher debouncing to keep performance snappy

In practice, this means you can Ctrl+Click a keyref attribute and land directly at the content — the same level of navigation you’d expect from a dedicated DITA IDE.

✅ Real-Time Validation with DITA 1.3 DTDs — Bundled and Ready

Validation is not an afterthought in DitaCraft. The extension ships with * bundled DITA DTD files covering the full specification: base, technical content, bookmap, learning, and more. You don’t need to configure an external catalog or point to a local DITA-OT installation just to get validation working.

Validation triggers automatically on:

• File open — catch errors before you even start editing
• Save — the classic write-validate loop
• Change — real-time feedback with 500ms debouncing to avoid thrashing

Errors appear as inline squiggly underlines in the editor and are surfaced in the Problems panel with accurate line and column positioning. Source attribution tells you whether an error came from the DTD validator, XML parser, or DITA structure validator — a small but meaningful UX detail that saves debugging time.

For teams with stricter requirements, DitaCraft also integrates with xmllint (libxml2) as an alternative validation engine, configurable via "ditacraft.validationEngine": "xmllint".

Enterprise-Grade Security

This deserves its own mention. DitaCraft's validation engine was built with security in mind:

• XXE (XML External Entity) neutralization — prevents malicious XML from reading local files or triggering SSRF
• Path traversal protection — file operations are validated to stay within workspace bounds
• Command injection prevention — DITA-OT integration uses safe execution methods, not raw shell interpolation
• Async file operations — nothing blocks the VS Code UI thread

If you're working in an enterprise environment with security-conscious infrastructure teams, these aren't nice-to-haves — they're table stakes.

🗺️ The DITA Map Visualizer: Structure You Can See

Understanding the shape of a large DITA publication by reading raw XML is exhausting. DitaCraft's Map Visualizer renders your map hierarchy as an interactive tree view directly inside VS Code's sidebar. Here's what it looks like in practice:

│ Map Visualizer: user-guide.ditamap [↻] [−] [+] │

│ 📘 User Guide │
│ ├── 📑 Chapter 1: Getting Started │
│ │ ├── 📄 Introduction │
│ │ ├── 📄 Installation │
│ │ └── 📄 Quick Start │
│ ├── 📑 Chapter 2: Core Features │
│ │ ├── 📄 Feature Overview │
│ │ └── ⚠️ missing-topic.dita (!) ← file not found │
│ └── 🔑 Key Definitions │
│ ├── 🔑 product-name │
│ └── 🔑 version │

Each node in the tree is typed — maps, chapters, appendices, parts, topics, and key definitions all get distinct icons. Missing referenced files are shown with a warning indicator so broken references are immediately visible without running a full build. The visualizer also detects circular map references and flags them automatically, an invaluable feature when working with complex submap architectures.

Double-click any node to open that topic or map in the editor. Use ↻ Refresh, − Collapse All, and + Expand All toolbar controls to navigate large publication hierarchies efficiently.

👁️ Live Preview with Bidirectional Scroll Sync

Writing DITA and then launching a full DITA-OT build just to see your output is a painful feedback loop. DitaCraft’s Live Preview (Ctrl+Shift+H) renders your topic as HTML5 in a side-by-side WebView panel, auto-refreshing on save. The preview uses real DITA-OT output.

The preview goes well beyond a simple render:

• Bidirectional scroll sync — scroll in the editor, the preview follows; scroll in the preview, the editor follows. This is the kind of detail that separates a thoughtfully built tool from a weekend project.
• Theme support — light, dark, and auto modes that follow your VS Code theme setting automatically, with no refresh needed
• Custom CSS — point the ditacraft.previewCustomCss setting to your organization’s stylesheet to preview with real corporate branding
• Print preview mode — a print-optimized view with a dedicated print button, for quick paper reviews

🧠 IntelliSense: Context-Aware DITA Completion

This is one of the most transformative features to land in DitaCraft. Version 0.5.0 introduces full IntelliSense support for DITA files — bringing the kind of intelligent authoring assistance that Java and TypeScript developers take for granted, directly into your .dita and .ditamap files.

364 DITA elements are covered, with context-aware completion that knows what elements are valid at the current cursor position:

• Type < inside a <body> and get completions filtered to valid body-level elements only
• Attribute completions respect the element's DTD constraints
• Enumerated attribute values (format, scope, type, audience, etc.) are offered as completion items

DITAVAL IntelliSense

DITAVAL condition files get the same treatment: full IntelliSense, validation, and hover documentation for .ditaval files. If you manage conditional publishing profiles, this alone is a significant productivity win.

Hover Documentation

Hover over any DITA element and get instant documentation pulled from the DITA schema — element purpose, valid children, and usage notes. No more tabbing to a browser to look up whether <shortdesc> can contain <ph>.

📊 Intelligent Build Output Panel

When you run a publish command, the output channel renders DITA-OT's log as syntax-highlighted, navigable output — not a wall of monospace text.

DITA-OT Build Started — 14:32:05 ║

[INFO] Processing: user-guide.ditamap
[WARN] ⚠ Missing navtitle for topicref: chapter3.dita
[ERROR] ✖ DOTX001E: Topic not found: missing-topic.dita
[INFO] Generating HTML5 output...

║ Build completed in 4.2s — FAILED (1 error) ║

Log level detection is automatic — DitaCraft parses DITA-OT error codes (DOTX001E → Error, DOTJ003W → Warning) as well as standard markers and Java logging format. Errors are clickable: click a file path in the output to jump directly to that file at the reported line and column. All build errors also appear in VS Code's Problems panel, so you can press F8 to cycle through them like any other code diagnostic.

🗂️ Project Management Views (v0.6.0)

Version 0.6.0 adds a suite of project-level views that turn DitaCraft into a full documentation workspace:

• DITA Explorer — A tree view of all DITA maps in your workspace, with expandable hierarchy, element type icons, and context menus for common operations. Think of it as the Solution Explorer for your documentation project.
• Key Space View — Browse all key definitions across your entire publication, with columns showing defined keys, undefined references, and unused keys. Click any key to navigate to its definition or to all its usages. This makes large-scale key management tractable in a way that wasn’t possible before.
• Diagnostics View — An aggregated view of all DITA issues across your workspace, with grouping by file or by severity. File decorations (error/warning badges on tree items) mean you can see at a glance which topics need attention without opening them.

🚀 One-Click Publishing to Multiple Formats

DitaCraft wraps DITA-OT with a clean, VS Code-native interface. Press Ctrl+Shift+B, choose a format, and your content is published. Supported transtypes include HTML5, PDF (via Apache FOP), XHTML, EPUB3, HTML Help (CHM), and Markdown — plus any custom transtype installed in your DITA-OT plugins directory.

DITAVAL filtering is supported via the configuration:

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

This makes conditional publishing — building different outputs for different audiences from the same source — a first-class citizen of the workflow.

📝 21 Smart Snippets + cSpell Integration

DITA's verbosity is often cited as a barrier to adoption. Typing <step><cmd></cmd></step> repeatedly is tedious. DitaCraft ships with 21 comprehensive code snippets covering all core topic types, structural elements (section, table, fig, note), cross-referencing (xref, conref, keyref), and map elements (topicref, keydef, reltable). Snippets insert proper XML structure with Tab-stop navigation.

Built-In cSpell Configuration

DITA includes hundreds of technical terms (titlealts, conkeyref, ditaval, topicref) that standard spell checkers flag as errors. DitaCraft includes a pre-configured .cspellrc.json that whitelists the entire DITA 1.3 vocabulary — preventing false positives while still catching real typos in your content. Run DITA: Setup cSpell Configuration to install it in your workspace in one step.

⚙️ Quick File Creation from Templates

Creating a new DITA topic from scratch means getting the DOCTYPE declaration right, the root element attributes correct, and the required <title> in place. DitaCraft's Create New Topic command handles all of this — pick a type (concept, task, reference), enter a filename, and get a valid, ready-to-edit topic with the correct DOCTYPE and structure.

The same applies to maps (DITA: Create New Map) and bookmaps (DITA: Create New Bookmap).

🧪 Comprehensive Testing: Reliability You Can Trust

Open-source tooling lives and dies by its reliability. DitaCraft's test suite covers:

• DTD resolution and validation logic
• Real-time validation on open, save, and change
• Navigation link detection and key space resolution
• Content reference parsing (@conref, @conkeyref, @keyref)
• Security scenarios (path traversal, XXE injection attempts)
• Async operations and caching behavior
• All v0.5.0 and v0.6.0 views and utilities (72 new tests added in v0.6.0 alone)
• Cross-platform CI: Windows, macOS, and Linux

Coverage thresholds are enforced in CI (62% lines, 65% functions, 73% branches), and a dedicated weekly security audit job runs automatically. This is the kind of engineering discipline that makes a tool safe to depend on professionally.

🛠️ The Roadmap: A Clear Path Forward

DitaCraft's public roadmap is precise and committed to, not vague marketing:

The velocity here is notable: four significant milestones shipped, each adding a coherent layer on top of the last. v0.7.0's cross-file validation will be particularly impactful for teams maintaining large publication sets with shared key definitions and conrefs across dozens of topics.

🔍 Getting Started in 5 Minutes

# Install from VS Code Marketplace
# Press Ctrl+P, type:
ext install ditacraft

Then configure your DITA-OT path:

1. Open Command Palette (Ctrl+Shift+P)
2. Run DITA: Configure DITA-OT Path
3. Select your DITA-OT 4.x installation directory

That's it. Open any .dita, .ditamap, or .bookmap file and the extension activates automatically — by file extension or by DOCTYPE declaration detection. No project configuration file needed.

💡 Why DitaCraft Is Different

The technical documentation tooling space tends toward two extremes: expensive, monolithic commercial IDEs on one end, and bare XML editors with a few DITA-specific snippets on the other. DitaCraft is something else: a focused, engineering-quality open-source tool that takes DITA's complexity seriously.

Key space resolution. DTD-bundled validation. Bidirectional scroll sync. 364-element IntelliSense. XXE protection. A Key Space browser. A published, delivered roadmap. These aren't features you bolt on — they reflect a coherent philosophy about what professional DITA tooling should look like inside a developer's primary editor.

DitaCraft doesn't just help you write structured content — it helps you think in structure.

💬 Get Involved

DitaCraft is fully open source under the MIT license:

• ⭐ Star the project on GitHub
• 📦 Install from the VS Code Marketplace
• 🐛 Report bugs or request features
• 🤝 Contribute — good first issues are labeled

Whether you're a lone technical writer, a docs-as-code team embedding documentation in a software monorepo, or a developer who occasionally needs to produce structured reference docs — DitaCraft is worth a serious look.

Structured writing is no longer a constraint. With DitaCraft, it becomes a superpower.

DitaCraft is developed by Jeremy Jeanne. Special thanks to all contributors and the DITA community for their feedback and support.