Edit online

Startup DITA Project

17 May 2021
Read time: 7 minute(s)

The Startup DITA Project contents are useful for starting a new DITA project with Oxygen XML Editor version 23.0 or newer, using collaboration version control systems such as Git or Subversion.

When the project.xpr is open in the Project view, it imposes a custom set of options, as well as an imposed custom DITA framework extension.

Project Structure

The project contains the following folder structure:

  • custom-settings/frameworks - Contains custom DITA and DITA Map framework extensions.
  • custom-settings/learned-words - Contains learned words for the English dictionary.
  • filters - This initially empty folder can be updated to contain DITAVAL Filter files used to profile the DITA content when publishing.
  • images - Contains images used in the DITA project.
  • oxygen-term-checker - Contains a terminology file with an example rule.
  • publishing - Contains a DITA-OT project file and a publishing template.
  • reusables - Contains various reusable components. For example, in the "reusable_components.dita" topic, you can add various DITA elements (such as notes, paragraphs, lists, and list items) that are reused in various places in the project. See more about reusing DITA content.
  • topics - Contains all the DITA topics in the project.

Settings Saved at Project Level

Most of the preference pages in Options > Preferences can be saved at project level. When the project is open in the Project view, the following options are imposed:

  • The Editor / Spell Check preferences page is saved at project level with automatic spell checking enabled.
  • The Editor / Spell Check / Dictionaries preferences page is saved at project level and all learned words are saved in the custom-settings/learned-words/en.tdi file.
  • The Editor / Edit Modes / Author preferences page is saved at project level.
  • The DITA / Maps preferences page is saved at project level.
  • The Document Type Association preferences page disables certain framework configurations that are not useful (e.g. DocBook 5).
  • The Document Type Association / Locations preferences page references two custom framework configurations that are described further.

Framework Customizations

The editing environment for DITA Maps and Topics can be customized by extending their current frameworks.

The framework extension for editing DITA Topics is defined in the custom-settings/frameworks/dita-extension/dita-extension.exf framework script file. You can add your own custom actions to the toolbars, menus, or contextual menus, and add, change, or remove transformation scenarios or validation scenarios.

  • You can customize the existing DITA Topic file templates by making changes to the custom-settings/frameworks/dita-extension/templates/ folder.

  • The content completion configuration extension file custom-settings/frameworks/dita-extension/resources/cc_config_ext.xml allows you to customize various aspects of the content completion feature.

  • You can add custom Schematron validation rules in the custom-settings/frameworks/dita-extension/resources/customRules.sch Schematron file.

  • You can also customize the visual editing by modifying the CSS custom-settings/frameworks/dita-extension/css/custom.css.

The framework extension for editing DITA Maps is defined in the custom-settings/frameworks/dita-map-extension/dita-map-extension.exf framework script file and can me customized in a similar way. You can customize the existing DITA Map file templates by making changes to the custom-settings/frameworks/dita-map-extension/templates/ folder.

Renaming/Moving Topics and Other Resources

The project has a logical folder named Main Files with a reference to the main DITA map. This enables the Main Files support in the project, allowing you to rename or move files while the references to those files are automatically updated.

Terminology Checking

For checking terminology, you can use the Oxygen Terminology Checker add-on. You can add terminology rules to the oxygen-term-checker folder. For example, the Oxygen user manual uses a set of Vale rules to check for common terminology problems.


You can publish the content of the project.ditamap in two ways:

  • You can open the DITA-OT project file named publish-project.xml from the publishing subfolder and two predefined publishing scenarios become available. You can read more about DITA-OT project files in the user manual.
  • You can also open the project.ditamap file in the DITA Maps Manager view, invoke the "Configure Transformation Scenario(s)" dialog box, and in the Project section, there are two predefined transformation scenarios (one for WebHelp, the other for PDF) that use the publishing template archived in the zip file. This past webinar shows more details about creating and customizing a publishing template.

Starting with Oxygen XML Editor version 24, the Startup DITA Project will be available as a new project template in the Project > New Project dialog box. If you want to try it with Oxygen XML Editor version 23 you should download the project template (.zxpr file) from the project releases page and set it as a new document template.