Skip to main content

​
Overview

Oxygen Positron is a modern IDE for XML and structured content editing, built with AI capabilities. It supports the Model Context Protocol (MCP), allowing seamless integration with WebHelp MCP Server for context-aware documentation assistance.
Oxygen Positron provides native support for XML, DITA, XSLT, and other structured content formats, making it ideal for technical documentation workflows.

​
Prerequisites

  • Oxygen Positron IDE installed
  • WebHelp MCP Server deployed and accessible
  • Basic knowledge of XML/DITA workflows

​
Configuration

1

Access MCP Settings

Open Oxygen Positron’s MCP configuration:
  1. Launch Oxygen Positron
  2. Go to Settings > AI & MCP Servers
  3. Or use command palette: Cmd/Ctrl + Shift + P → “MCP: Configure Servers”
2

Add WebHelp MCP Server

Configure your WebHelp MCP Server connection:
{
  "mcpServers": {
    "oxygen-editor-docs": {
      "url": "https://webhelp-mcp.example.com/www.oxygenxml.com/doc/versions/27.1/ug-editor",
      "description": "Oxygen XML Editor User Guide",
      "icon": "book"
    }
  }
}
The priority field helps Oxygen Positron determine which MCP servers to query first. Options: high, medium, low.
3

Configure Context Rules

Set up automatic context detection for better AI assistance:
context-rules.json
{
  "contextRules": [
    {
      "filePattern": "**/*.dita",
      "mcpServers": ["oxygen-editor-docs", "dita-ot-docs"],
      "autoQuery": true
    },
    {
      "filePattern": "**/*.xsl",
      "mcpServers": ["oxygen-editor-docs"],
      "autoQuery": true
    },
    {
      "filePattern": "**/*.ditamap",
      "mcpServers": ["dita-ot-docs"],
      "autoQuery": true
    }
  ]
}
This configuration automatically queries relevant documentation based on the file type you’re editing.
4

Restart Oxygen Positron

Apply the configuration:
  • Restart the IDE, or
  • Use command: AI: Reload MCP Servers
5

Verify Connection

Test the integration:
  1. Open the AI Assistant panel (Alt/Option + A)
  2. Type: @oxygen-editor-docs What tools are available?
  3. You should see the search and fetch tools listed

​
Features

​
Context-Aware Assistance

Oxygen Positron automatically provides documentation context based on your current editing task: 
<!-- While editing DITA topics -->
<concept id="intro">
  <title>Introduction</title>
  <conbody>
    <!-- AI suggestions will reference Oxygen's DITA authoring guide -->
  </conbody>
</concept>
The AI assistant automatically searches relevant documentation when you:
  • Request code completion
  • Ask for explanations
  • Generate new content
  • Validate structures

​
Inline Documentation

Hover over XML elements to see documentation snippets:
  1. Place cursor on any DITA element
  2. Press Cmd/Ctrl + K then I
  3. Get instant documentation from WebHelp

​
Smart Validation

Validation messages enhanced with documentation links: 
<topic>
  <title>Test</title>
  <!-- Missing <shortdesc> -->
  <!-- AI suggests: "Consider adding <shortdesc> per Oxygen best practices" -->
  <!-- Links to: Oxygen docs on short descriptions -->
</topic>

​
Template Generation

Generate DITA/XML templates based on Oxygen standards: 
@oxygen-editor-docs Generate a DITA task topic structure

​
Available Tools

Description: Search Oxygen documentation for relevant content Parameters:
  • query (string): Search query with boolean operator support (AND, OR, NOT)
Usage in Oxygen Positron: 
@oxygen-editor-docs search XSLT debugging
Response format: 
[
  {
    "title": "XSLT Debugger",
    "id": "topics/xslt-debugger.html",
    "url": "https://www.oxygenxml.com/doc/versions/27.1/ug-editor/topics/xslt-debugger.html"
  },
  {
    "title": "Debugging XSLT Stylesheets",
    "id": "topics/debugging-xslt.html",
    "url": "https://www.oxygenxml.com/doc/versions/27.1/ug-editor/topics/debugging-xslt.html"
  }
]

​
fetch

Description: Retrieve complete document content by ID Parameters:
  • id (string): Document ID from search results
Usage in Oxygen Positron: 
@oxygen-editor-docs fetch topics/xslt-debugger.html
Response format: 
{
  "title": "XSLT Debugger",
  "url": "https://www.oxygenxml.com/doc/versions/27.1/ug-editor/topics/xslt-debugger.html",
  "text": "# XSLT Debugger\n\nThe XSLT Debugger in Oxygen XML Editor provides..."
}

​
Workflow Examples

​
Example 1: DITA Topic Creation

1

Create New Topic

  1. File > New > DITA Topic
  2. Open the AI Assistant (Alt/Option + A)
2

Query Documentation

@oxygen-editor-docs What are the best practices for writing concept topics?
3

Apply Recommendations

The AI will search the documentation and provide structured guidance:
  • Required elements
  • Content structure
  • Examples from the docs
4

Generate Content

Generate a concept topic about XML catalogs following Oxygen guidelines

​
Example 2: XSLT Transformation

1

Open XSLT File

Open or create an .xsl file in Oxygen Positron
2

Ask for Transform Patterns

@oxygen-editor-docs Show me how to create a transformation scenario
3

Get Step-by-Step Guide

The AI fetches relevant documentation and provides:
  • Configuration steps
  • Parameter settings
  • Output options
4

Debug with Context

When errors occur:
@oxygen-editor-docs How do I debug this XSLT transformation error?

​
Example 3: DITA Map Publishing

1

Open DITA Map

Open your .ditamap file
2

Query Publishing Options

@dita-ot-docs What are the WebHelp Responsive output parameters?
3

Configure Transformation

AI provides documentation on:
  • Available parameters
  • Customization options
  • Publishing workflow
4

Customize Output

@dita-ot-docs How do I customize the WebHelp template?
Get detailed instructions with code examples from DITA-OT documentation.

​
Advanced Features

​
Automatic Context Injection

Enable automatic context injection for AI responses:
settings.json
{
  "ai.contextInjection": {
    "enabled": true,
    "maxResults": 3,
    "autoFetch": true
  }
}
When enabled, relevant documentation is automatically included in AI context without explicit queries.

​
Custom Prompts with Documentation

Create custom prompts that leverage documentation:
custom-prompts.json
{
  "prompts": [
    {
      "name": "Generate DITA Task",
      "trigger": "dita-task",
      "template": "@oxygen-editor-docs Search for DITA task best practices, then generate a task topic about {topic} following those guidelines.",
      "variables": ["topic"]
    },
    {
      "name": "Validate Structure",
      "trigger": "validate-dita",
      "template": "@oxygen-editor-docs Check if this DITA structure follows Oxygen's recommended practices: {selection}",
      "variables": ["selection"]
    }
  ]
}
Use with: Cmd/Ctrl + Shift + P → type trigger name

​
Documentation-Driven Refactoring

@oxygen-editor-docs How should I restructure this DITA map for better organization?

[Select DITA map content]
The AI will:
  1. Search for DITA map best practices
  2. Analyze your current structure
  3. Suggest improvements based on Oxygen documentation
  4. Generate refactored structure

​
Batch Operations

Process multiple files with documentation context: 
@oxygen-editor-docs Generate consistent short descriptions for all DITA topics in this folder based on Oxygen style guide

​
Integration with Oxygen Features

​
Schema-Aware Editing

The AI assistant respects your XML schemas and DTDs: 
<topic>
  <title>Example</title>
  <!-- AI suggestions only include valid child elements per schema -->
  <[AI suggests: shortdesc, prolog, body, related-links]>
</topic>

​
Content Completion

Enhanced content completion with documentation examples: 
<steps>
  <step>
    <!-- Type 'cmd' and press Tab -->
    <!-- AI suggests commands based on similar examples from docs -->
  </step>
</steps>

​
Transformation Scenarios

Get help configuring transformation scenarios: 
@dita-ot-docs Configure a PDF transformation with custom styling
The AI will guide you through:
  1. Selecting the transformation type
  2. Setting parameters
  3. Customizing CSS/XSL
  4. Configuring output options

​
Troubleshooting

Solution:
  1. Check server URL in settings
  2. Verify network connectivity: Test URL in browser
  3. Check Oxygen Positron logs: Help > View Logs > MCP Connections
  4. Ensure HTTPS is used for remote servers
  5. Try with a local server first to isolate issues
Solution:
  1. Verify context rules in context-rules.json
  2. Check that file patterns match your files
  3. Ensure autoQuery is set to true
  4. Reload context rules: AI: Reload Context Rules
Solution:
  1. Use more specific search terms
  2. Apply boolean operators: "DITA AND maps AND organization"
  3. Check that the correct MCP server is being queried
  4. Verify the documentation site URL is correct
Solution:
  1. Explicitly mention the MCP server: @oxygen-editor-docs
  2. Enable automatic context injection in settings
  3. Increase maxResults in context injection settings
  4. Check that the MCP server is active (status indicator)
Solution:
  1. Reduce maxResults in context injection
  2. Disable autoFetch for very large documents
  3. Use specific queries instead of broad searches
  4. Configure caching in MCP server settings
Automatic context injection can increase AI response time for large documents. Adjust settings based on your performance requirements.
Create workspace-specific MCP configurations for different projects to automatically load the right documentation context.

​
Performance Optimization

​
Caching Configuration

settings.json
{
  "mcp.cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "100MB",
    "strategy": "lru"
  }
}

​
Request Batching

settings.json
{
  "mcp.batching": {
    "enabled": true,
    "maxBatchSize": 10,
    "debounceTime": 300
  }
}

​
Selective Context Loading

settings.json
{
  "ai.contextLoading": {
    "mode": "selective",
    "prioritize": ["current-file", "related-topics", "referenced-docs"],
    "maxContextSize": "50KB"
  }
}

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us