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

All files must be stored on the same drive letter. The DITA Open Toolkit cannot resolve references across drive letters.

Some rules for content that will be published to a website

Use underscore to separate all-lower-case words in filenames and in folder names. Although the underscores disappear when shown as a hyperlink, this is still quite readable. (Amazon now links to its books this way. And the BBC follows this convention for their thousands of websites.)

Arrange folders to match the navigation scheme in a web site. Top-level landing pages should be in the main folder, section pages in folders with section name, etc. Then the path names for hyperlinks have a 1-to-1 mapping with the website information architecture. Users can see where they are from the hyperlink path.