Although the DITA standard itself does not set rules about file and folder naming, the DITA Open Toolkit has strict requirements for file and folder names. Problems with file and folder names may cause publishing to fail.

It is best to set guidelines about file and folder naming conventions before you start creating references such as <topicref>s in maps, as references include file names and folder paths.

File naming rules

The following rules apply to DITA topic files, map files, and all files referenced into a project such as image files. The DITA Open Toolkit does not support file names that contain:

• Punctuation except for the dot before the file extension (punctuation is generally problematic but I'm not sure exactly what the rules are - can anyone give the exact rules?)
• In older versions of the Toolkit, spaces in filenames also caused publishing to fail. This seems to have been addressed as of Open Toolkit version 1.4.

Topic files must have the extension .xml or .dita . The Open Toolkit cannot handle a mixture of topic files with .xml and .dita extensions, so organizations should pick one and standardize on it.

DITA map files must have the extension .ditamap .

Folder naming

References, such as <xref>, <image> and <topicref> elements, include folder paths. All folder names in these paths must not contain spaces or punctuation.

File locations