How to Use Oxygen XML Editor for DITA Authoring
[Step‑by‑Step Guide]
Oxygen XML Editor is one of the most powerful and widely adopted tools for authoring DITA content. Whether you’re creating user manuals, release notes, or knowledge base articles, Oxygen helps you:
Work with DITA topics, maps, and reusable components
Validate XML against DITA DTDs and Schemas
Collaborate with teams using a CCMS like Bluestream’s XDocs
Publish to multiple outputs: PDF, HTML5, WebHelp, EPUB, and more
In this guide, we’ll walk through exactly how to start using Oxygen XML Editor for DITA, even if you’re new to structured content.
✅ Step-by-Step Guide to DITA Authoring in Oxygen XML Editor
Step 1: Install Oxygen XML Editor
You can download a free trial or licensed version from oxygenxml.com. Choose the “Editor” edition unless you’re working in an enterprise CCMS environment (then you’ll likely use Author or Web Author edition).
👉 Tip: If your organization uses Bluestream XDocs, ask your admin if there’s an integration profile for Oxygen already configured.
Step 2: Create a New DITA Project
Once Oxygen is installed:
Go to File → New
Choose DITA → DITA Map or DITA Topic
Select a topic type (e.g., concept, task, reference)
This gives you a validated XML skeleton to start writing content.
Oxygen provides a dual view:
Text View (for XML pros)
Author View (WYSIWYG, like Word)
Use the Author View to:
Insert reusable elements (titles, steps, notes, tables)
Structure tasks using
<steps>and<cmd>Link between topics using
<xref>
📌 Pro Tip: Use the Content Completion Assistant (Ctrl+Space) to speed up tagging and reduce errors.
Step 4: Create and Link a DITA Map
DITA maps define relationships between topics.
To create a DITA Map:
Go to File → New → DITA → DITA Map
Drag and drop your topics into the map
Use
<topicref>elements to organize content hierarchically
The map is your master structure for publishing.
Step 5: Validate and Troubleshoot
Click the Validate (✓) icon to check your topic or map against the DITA standard.
Look for:
Missing required elements
Broken xrefs or hrefs
Invalid nesting
Oxygen will highlight issues and offer suggestions.
Step 6: Publish to Multiple Outputs
Oxygen supports out-of-the-box transformation scenarios:
HTML5: Modern responsive web output
PDF via DITA-OT: Print-ready documents
WebHelp: Interactive documentation portal
To publish:
Go to DITA Maps Manager → Open your map
Click Transform → Configure Transformation Scenario
Select an output format, adjust parameters, and hit Apply
Need branded output? Oxygen supports custom plugins or can publish via your CCMS (e.g., XDocs Dynamic Delivery Portal)
Step 7: Integrate with a DITA CCMS (Optional, but Recommended)
For enterprise teams, managing hundreds or thousands of topics locally is not scalable.
A DITA-native CCMS like Bluestream XDocs helps you:
Version control your topics
Manage reuse with conditional profiling and metadata
Automate publishing pipelines
Collaborate with writers, translators, and reviewers
Oxygen integrates natively with XDocs, letting you check content in/out, validate on the fly, and publish directly from within the editor
🖚 Final Thoughts
Oxygen XML Editor is the gold standard for structured content authoring—and when paired with DITA and a CCMS like XDocs, it becomes a powerhouse for scalable documentation.
Whether you’re just getting started with DITA or looking to level up your XML workflow, mastering Oxygen is a crucial step.
📥 Ready to Scale DITA Across Your Team?
Bluestream’s XDocs CCMS integrates seamlessly with Oxygen XML, giving you complete control over authoring, reuse, translation, and publishing.
👉 Book a Demo to see how it works in your environment.
Ready to upgrade your content experience? Talk to Bluestream about how XDocs and XDelivery can power your next-generation documentation portal.
