DitaCraft

The best way to edit and publish your DITA files

DitaCraft is a comprehensive Visual Studio Code extension for editing and publishing DITA (Darwin Information Typing Architecture) content. It provides syntax highlighting, validation, and seamless integration with DITA-OT for multi-format publishing.

Highlights

🔗 Smart Navigation - Ctrl+Click on href attributes in maps to open referenced topics (fixed in v0.1.2) ✅ DTD Validation - Complete DITA 1.3 DTD support with 168 bundled DTD files ⚡ Real-time Validation - Automatic validation on open, save, and change with debouncing 🚀 One-Click Publishing - Direct DITA-OT integration for HTML5, PDF, EPUB, and more 👁️ Live Preview - Side-by-side HTML5 preview with auto-refresh 📝 21 Smart Snippets - Comprehensive DITA code snippets for rapid editing 🧪 65+ Tests - Extensively tested with 96.7% test success rate including integration tests

Features

📝 DITA Editing

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

Ctrl+Click navigation in DITA maps and bookmaps
- Click on href attributes in <topicref> elements to open referenced files
- Works with relative paths and handles fragment identifiers (e.g., file.dita#topic_id)
- Visual link indicators (underlined hrefs when you hover)
- Hover tooltip showing target filename
- Automatically resolves paths relative to the map file location
- Skips external URLs (http://, https://) - they won't be underlined
Navigate seamlessly between maps and topics in your documentation structure
How to use:
1. Open a .ditamap or .bookmap file
2. Hover over any href attribute value - it will be underlined
3. Ctrl+Click (Windows/Linux) or Cmd+Click (Mac) to open the target file
4. Works with nested topicrefs and complex map structures

✅ Advanced Validation

Real-time validation on file open, save, and change (with 500ms debouncing)
DTD-based validation against DITA 1.3 specifications
- Bundled DITA 1.3 DTD files (topic, concept, task, reference, map, bookmap, learning, etc.)
- Validates required elements (id, title) and proper structure
- Accurate PUBLIC ID resolution with caching
Dual validation engines:
- Built-in parser with DTD support (default)
- xmllint integration for advanced validation
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)
Auto-detection of DITA files:
- By extension: .dita, .ditamap, .bookmap
- 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
Auto-refresh on save
Navigate directly from source to preview

🎯 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

Open VS Code
Press Ctrl+P / Cmd+P
Type ext install ditacraft
Press Enter

From VSIX

Download the latest .vsix file from Releases
Open VS Code
Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
Click ... menu → "Install from VSIX..."
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

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

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

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

Step 7: Verify Installation

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

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

Download DITA-OT from https://www.dita-ot.org/download
Extract to a location (e.g., C:\DITA-OT-4.2.1)
In VS Code, run "DITA: Configure DITA-OT Path"
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:

Edit TypeScript files in src/
Watch mode auto-compiles to out/
In Extension Host window, press Ctrl+R (or Cmd+R) to reload
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

DITA-OT 4.2.1 or higher (Download)

For Advanced Validation (Optional)

xmllint (libxml2) for strict XML validation

Quick Start

1. Install DITA-OT

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

2. Configure DitaCraft

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

3. Create Your First DITA File

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

4. Publish

Open your .dita, .ditamap, or .bookmap file
Press Ctrl+Shift+B / Cmd+Shift+B
Select output format (HTML5, PDF, etc.)
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: 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

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.showProgressNotifications`	boolean	`true`	Show progress notifications
`ditacraft.validationEngine`	string	`"xmllint"`	Validation engine
`ditacraft.ditaOtArgs`	array	`[]`	Custom DITA-OT arguments
`ditacraft.enableSnippets`	boolean	`true`	Enable code snippets

📖 Full Configuration Guide

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

Open a .ditamap or .bookmap file
Ctrl+Click (Cmd+Click on Mac) on any href attribute value in <topicref> elements
The referenced topic file opens in a new tab
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

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

Previewing Changes

Open .dita file
Make edits
Press Ctrl+Shift+H to preview
Preview auto-refreshes on save
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/
│   ├── extension.ts           # Entry point
│   ├── commands/              # Command handlers
│   │   ├── validateCommand.ts
│   │   ├── publishCommand.ts
│   │   ├── previewCommand.ts
│   │   └── fileCreationCommands.ts
│   ├── providers/
│   │   ├── ditaValidator.ts   # DITA validation engine
│   │   └── ditaLinkProvider.ts # Ctrl+Click navigation
│   ├── utils/
│   │   ├── ditaOtWrapper.ts   # DITA-OT integration
│   │   ├── dtdResolver.ts     # DTD catalog resolver
│   │   └── logger.ts          # Logging utility
│   ├── preview/
│   │   └── previewPanel.ts    # WebView preview
│   └── test/                  # Test suites
│       ├── suite/
│       │   ├── ditaValidator.test.ts
│       │   ├── dtdValidation.test.ts
│       │   ├── realtimeValidation.test.ts
│       │   ├── commandAndDetection.test.ts
│       │   └── ditaLinkProvider.test.ts
│       └── fixtures/          # Test fixtures
├── dtds/                      # DITA 1.3 DTD files
│   ├── base/
│   ├── technicalContent/
│   ├── bookmap/
│   └── learning/
├── syntaxes/
│   └── dita.tmLanguage.json   # Syntax highlighting
├── snippets/
│   └── dita.json              # Code snippets (21 snippets)
├── package.json               # Extension manifest
├── README.md
└── TEST-COVERAGE.md           # Test documentation

Quality & Testing

DitaCraft includes comprehensive test coverage for all key features:

Test Suites:

DTD Validation Tests - Tests DTD resolution and DTD-based validation
Real-time Validation Tests - Tests validation on file open, save, and change
Command & Auto-Detection Tests - Tests manual validation and file detection
Link Navigation Tests - Tests Ctrl+Click navigation in maps and bookmaps

Test Coverage:

✅ 65+ passing tests covering all key features (96.7% success rate)
✅ Real-time validation on file open, save, and change (with debouncing)
✅ DTD resolution and bundled DTD files
✅ Error highlighting with line/column accuracy
✅ Manual validation command
✅ Auto-detection by extension or DOCTYPE
✅ Smart navigation with Ctrl+Click on href attributes
✅ Language ID configuration and integration tests
✅ Link detection, range accuracy, and tooltip verification

Running Tests:

# Run all tests
npm test

# Run tests in watch mode
npm run watch

# Compile tests
npm run compile-tests

See TEST-COVERAGE.md for detailed test documentation.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Add tests for new features
Ensure all tests pass (npm test)
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Troubleshooting

DITA-OT Not Found

Problem: Extension shows "DITA-OT not found"

Solution:

Verify DITA-OT is installed
Run "DITA: Configure DITA-OT Path" command
Select DITA-OT installation directory
Verify with "DITA: Validate Current File"

Validation Errors

Problem: Validation shows unexpected errors

Solution:

Check XML syntax (closing tags, quotes, etc.)
Verify DOCTYPE declaration
Try switching validation engine: "ditacraft.validationEngine": "built-in"

Publishing Fails

Problem: Publishing fails with error

Solution:

Check DITA-OT logs in Output panel
Verify output directory is writable
Check for syntax errors in DITA file
Try publishing with --verbose flag:
```
"ditacraft.ditaOtArgs": ["--verbose"]
```

Problem: Ctrl+Click on href attributes doesn't open files

Solution:

Verify you're in a .ditamap or .bookmap file (check file extension in status bar)
Hover over the href value - it should be underlined if detected as a link
Make sure you're clicking on the href value itself (e.g., introduction.dita), not the attribute name href=
Check that the referenced file path is correct and file exists
Try reloading VS Code window (Ctrl+R / Cmd+R in VS Code)
Verify extension is activated (look for "DitaCraft" in Extensions)

Example of correct usage:

<topicref href="introduction.dita"/>
              ^^^^^^^^^^^^^^^^^^^^
         Ctrl+Click here (on the value)

Preview Not Showing

Problem: Preview panel is blank or shows error

Solution:

Verify HTML5 output was generated
Check output directory exists
Look for JavaScript errors in Developer Tools
Try republishing: Ctrl+Shift+B → HTML5

📖 Full Troubleshooting Guide

Documentation

Configuration Guide - Complete settings documentation
Commands and Shortcuts - All commands and keybindings
DITA-OT Integration - DITA-OT integration details
Contributing Guide - Development and contribution guidelines

Resources

DITA Resources

VS Code Resources

Recent Updates

Version 0.1.0 Fixes

✅ Fixed preview and publishing with paths containing spaces - File paths with spaces (e.g., "Learn Rust/project") now work correctly
✅ Fixed DITA validation - Title element is now correctly validated as required (error, not warning) per DTD spec
✅ Enhanced DTD validation - Added proper DTD validation support with xmllint
✅ Improved error messages - Better, more descriptive validation and publishing error messages
✅ Fixed file path validation - Added comprehensive checks to ensure files (not directories) are being processed
✅ Added verbose logging - Detailed console logging for easier debugging

Changelog

See CHANGELOG.md for release history.

License

This project is licensed under the MIT License - see LICENSE file for details.

Support

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: jyjeanne@gmail.com

Acknowledgments

DITA Open Toolkit team for the excellent DITA-OT
OASIS DITA Technical Committee
VS Code extension development community
All contributors and users

Made with ❤️ for technical writers and documentation teams

⭐ Star this project on GitHub

DitaCraft

Jeremy Jeanne

DitaCraft

Highlights

Features

📝 DITA Editing

🔗 Smart Navigation

✅ Advanced Validation

🚀 One-Click Publishing

👁️ Live Preview

🎯 Quick File Creation

⚙️ Flexible Configuration

Installation

From VS Code Marketplace

From VSIX

Local Installation for Development

Step 1: Prerequisites

Step 2: Get the Source Code

Step 3: Install Dependencies

Step 4: Compile TypeScript

Step 5: Package the Extension

Step 6: Install in VS Code

Step 7: Verify Installation

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

Troubleshooting Local Installation

Issue: npm install fails

Issue: Compilation errors

Issue: Extension not appearing in VS Code

Issue: "Cannot find module" errors

Development Workflow

Prerequisites

Required

For Publishing

For Advanced Validation (Optional)

Quick Start

1. Install DITA-OT

2. Configure DitaCraft

3. Create Your First DITA File

4. Publish

Commands

Configuration

Basic Settings

All Settings

Supported Output Formats

Workflows

Navigating Your Documentation Structure

Publishing a Book

Previewing Changes

Using Filters (DITAVAL)

Development

Building from Source

Project Structure

Quality & Testing

Contributing

Troubleshooting

DITA-OT Not Found

Validation Errors

Publishing Fails

Smart Navigation Not Working

Preview Not Showing

Documentation

Resources

DITA Resources

VS Code Resources

Recent Updates

Version 0.1.0 Fixes

Changelog

License

Support

Acknowledgments

Issue: `npm install` fails