DitaCraft

The easiest 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, conref, keyref, and conkeyref attributes with full key space resolution 🔑 Key Space Resolution - Automatic resolution of DITA keys from map hierarchies with intelligent caching ✅ 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 🔒 Enterprise Security - Path traversal protection, XXE neutralization, and command injection prevention 🚀 One-Click Publishing - Direct DITA-OT integration for HTML5, PDF, EPUB, and more 👁️ Live Preview - Side-by-side HTML5 preview with auto-refresh 🗺️ Map Visualizer - Interactive tree view of DITA map hierarchies with navigation 📝 21 Smart Snippets - Comprehensive DITA code snippets for rapid editing 🖨️ Print Preview - Print-optimized preview with dedicated print button 🧪 450+ Tests - Extensively tested with comprehensive integration and security 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, 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 (NEW in v0.2.0)
- Automatically discovers root maps in your workspace
- Builds and caches key space from map hierarchies
- Resolves @keyref, @conkeyref, and key-based references
- Handles submaps, nested maps, and complex key definitions
- 1-minute cache 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 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
Enterprise Security Features (NEW in v0.2.0):
- 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 UI blocking
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 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

🗺️ Map Visualizer

Interactive tree view - Visual hierarchy of DITA maps, bookmaps, and topics
Element type icons - Different icons for maps, chapters, appendices, parts, topics, and keys
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

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: 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: Setup cSpell Configuration	-	Create cSpell config for DITA files

Spell Checking with cSpell

DitaCraft includes a pre-configured cSpell configuration with comprehensive DITA vocabulary to prevent false "unknown word" errors when using spell checkers.

Setup cSpell

Option 1: Automatic Setup (Recommended)

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Type "DITA: Setup cSpell Configuration"
Click the command
DitaCraft will create a .cspellrc.json file in your workspace root with all DITA terminology pre-configured

Option 2: Manual Setup

Copy the template .cspellrc.json from the DitaCraft project repository
Place it in your workspace root folder
The configuration includes:
- All DITA 1.3 elements (topic, titlealts, topicref, etc.)
- Common DITA attributes (href, conref, keyref, format, scope, etc.)
- Publishing terms (ditamap, bookmap, ditaval, etc.)
- Specialized configurations for .dita, .ditamap, .bookmap, and .ditaval files

Why cSpell Configuration?

DITA includes many technical terms and element names (like titlealts, conref, keyref) that aren't recognized by standard spell checkers. The pre-configured .cspellrc.json prevents false "unknown word" warnings for these legitimate DITA terms while still catching actual spelling errors in your documentation content.

What's Included in the Configuration

The default cSpell configuration includes:

DITA elements: topic, concept, task, reference, figure, table, section, and 100+ more
DITA attributes: href, conref, keyref, conkeyref, format, scope, type, and more
Map elements: ditamap, topicref, mapref, keydef, reltable, and more
Bookmap elements: chapter, part, appendix, frontmatter, backmatter, and more
Learning elements: learningBase, learningObject, learningContent, and more
Specialized terms: ditaarch, xmlns, OASIS standards, and DITA-OT related terms

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	`"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
└── CHANGELOG.md               # Version history

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 including key resolution
Key Space Resolution Tests - Tests key space building and caching

Test Coverage:

✅ 450+ passing tests covering all key features
✅ 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 key space resolution
✅ Content references (@conref, @conkeyref, @keyref)
✅ Security testing (path traversal, XXE protection)
✅ Async file operations and caching
✅ 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

Known Limitations

The current implementation provides comprehensive navigation support. Minor limitations include:

Same-file Content References (@conref with #) - e.g., <ph conref="#v4.3/summary"/>
- References starting with # point to elements within the same file
- Currently opens the file but doesn't scroll to the specific element
Conditional Key Definitions
- Keys with DITAVAL conditions may not be resolved correctly
- The key space builder uses the first definition found
External Key Scopes
- Keys defined in external key scopes are not yet supported
- Limited to keys within the workspace

What now works (NEW in v0.2.0):

✅ href="path/to/file.dita" - Direct file paths
✅ href="file.dita#topic_id" - File paths with fragment identifiers
✅ conref="file.dita#element_id" - Content references
✅ keyref="key-name" - Key references resolved via key space
✅ conkeyref="key-name/element" - Content key references
✅ Automatic root map discovery and key space building
✅ Intelligent caching with 1-minute TTL
✅ File watcher debouncing (300ms) for performance

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

Resources

DITA Resources

VS Code Resources

Recent Updates

Version 0.4.0 (Current)

Enhanced Preview, Build Output & Map Visualizer Milestone

✅ DITA Map Visualizer - Interactive tree view showing map hierarchies with navigation
✅ Bidirectional Scroll Sync - Editor and preview scroll positions stay synchronized
✅ Print Preview Mode - Print-optimized view with dedicated print button
✅ Syntax-Highlighted Build Output - DITA-OT output with automatic colorization by log level
✅ Log Level Detection - Errors, warnings, info, debug messages auto-classified
✅ Build Timestamps - Build start and completion times displayed
✅ Circular Reference Detection - Map visualizer detects and warns about circular map references
✅ 450+ Tests - Comprehensive test suite with new feature coverage

Version 0.3.0

Developer Experience & Quality Milestone

✅ Code Coverage with c8 - Switched from nyc to c8 for VS Code extension-compatible coverage
✅ Coverage Threshold Enforcement - CI enforces minimum coverage (62% lines, 65% functions, 73% branches)
✅ CI Security Audit - Dedicated security audit job with weekly scheduled scans
✅ Cross-Platform CI - Tests run on Windows, macOS, and Linux
✅ Dynamic Configuration - Centralized ConfigurationManager with real-time change propagation
✅ Advanced Element Navigation - Same-file and cross-file element navigation with fragment support
✅ Configurable Settings - Validation debounce, key space TTL, DITA-OT timeout, max link matches
✅ Code Quality - Removed unused dependencies, consolidated file reading, standardized async patterns

Version 0.2.4

✅ Fixed DITA-OT HTML5 Publishing - Resolved Windows path case sensitivity issue
✅ Comprehensive Test Suite - 307+ tests including error handling tests
✅ Improved Error Handling - Added fireAndForget utility for safe async handling

Version 0.2.0

✅ Full Key Space Resolution - Navigate @keyref, @conkeyref, and key-based references with automatic key space building
✅ Enhanced Security - XXE neutralization, path traversal protection, and command injection prevention
✅ Performance Optimizations - Async file operations, intelligent caching (1-min TTL), and file watcher debouncing
✅ Content Reference Navigation - Ctrl+Click on @conref attributes to navigate to referenced content
✅ Better UI Responsiveness - Async operations prevent UI blocking during file operations

Version 0.1.3 Fixes

✅ Fixed preview and publishing with paths containing spaces - File paths with spaces now work correctly
✅ Fixed DITA validation - Title element is now correctly validated as required 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 - Comprehensive checks to ensure files are being processed
✅ Added verbose logging - Detailed console logging for easier debugging

Roadmap

We have an exciting roadmap planned for DitaCraft! See our detailed ROADMAP.md for:

v0.3.0 - Developer Experience & Quality ✅ COMPLETE
v0.4.0 - Enhanced Preview, Build Output & Map Visualizer ✅ COMPLETE
v0.5.0 - IntelliSense & Content Assistance (hover, completion, code actions) NEXT
v0.6.0 - Project Management & Views (DITA Explorer, Key Space browser)
v0.7.0 - Advanced Validation (DITA 1.2/2.0 DTDs, cross-file validation)
v0.8.0 - Refactoring & Productivity (rename keys, templates)
v0.9.0 - Publishing Enhancements (profiles, DITAVAL editor)

Contributing

We welcome contributions! Here's how you can help:

Good First Issues

Look for issues labeled good first issue - these are great starting points for new contributors.

Development Setup

git clone https://github.com/jyjeanne/ditacraft.git
cd ditacraft
npm install
npm run compile
# Press F5 in VS Code to run in debug mode

Areas Needing Help

Area	Difficulty	Description
Test Coverage	Easy-Medium	Add tests for commands and providers
Documentation	Easy	Improve README, add tutorials
WebView Preview	Medium	Complete HTML5 preview feature
IntelliSense	Medium-Hard	Hover and completion providers
DTD Support	Hard	Add DITA 1.2/2.0 support

See ROADMAP.md for detailed feature breakdown and contribution opportunities.

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

📊 Build Output

🗺️ Map Visualizer

🎯 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

Spell Checking with cSpell

Setup cSpell

Why cSpell Configuration?

What's Included in the Configuration

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

Known Limitations

Smart Navigation (v0.2.0)

Contributing

Troubleshooting

DITA-OT Not Found

Validation Errors

Publishing Fails

Smart Navigation Not Working

Preview Not Showing

Resources

DITA Resources

VS Code Resources

Recent Updates

Version 0.4.0 (Current)

Version 0.3.0

Version 0.2.4

Version 0.2.0

Version 0.1.3 Fixes

Roadmap

Contributing

Good First Issues

Issue: `npm install` fails