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.

Features

📝 DITA Editing

Syntax highlighting for .dita, .ditamap, and .bookmap files
Intelligent code snippets and auto-completion
Real-time validation with inline error highlighting
Support for all DITA topic types (concept, task, reference, topic)

🚀 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+P`	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

Publishing a Book

Create bookmap: DITA: Create New Bookmap
Create chapters: DITA: Create New Topic (multiple times)
Edit bookmap to reference chapters
Validate: Ctrl+Shift+V
Publish: Ctrl+Shift+B → Select format
Open output folder

Previewing Changes

Open .dita file
Make edits
Press Ctrl+Shift+P 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
│   ├── utils/
│   │   └── ditaOtWrapper.ts   # DITA-OT integration
│   └── preview/
│       └── previewPanel.ts    # WebView preview
├── syntaxes/
│   └── dita.tmLanguage.json   # Syntax highlighting
├── snippets/
│   └── dita.json              # Code snippets
├── package.json               # Extension manifest
└── README.md

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')
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"]
```

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

Features

📝 DITA Editing

🚀 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

Publishing a Book

Previewing Changes

Using Filters (DITAVAL)

Development

Building from Source

Project Structure

Contributing

Troubleshooting

DITA-OT Not Found

Validation Errors

Publishing Fails

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