Edit online

Automation - Using DITA XML Topic Titles to Generate File Names

4 Dec 2023
Read time: 3 minute(s)

When you create a new DITA topic in Oxygen XML Editor, you can usually specify the title of the topic and that title is used by the application to propose a file name. For example, for a topic title like WebHelp Output, the file name could be webhelp_output.dita.

In general, I think having file names that match the topic titles seems like a best practice technique to identify each topic based solely on the file name. However, there are cases where the file names do not match the topic or map titles and for such cases, I created a free-to-use Python script to update the file names of all topics and maps based on the titles specified inside them. The script should also update any link or conref references to reflect the file name changes it makes.

I think this script that updates file names based on titles for an entire DITA XML project could be useful in these cases:
  • There are content management systems (CMSs) that use unique IDs as file names (for example, abc434243243.xml). When such projects are exported from the CMS, the file names look quite ugly on disk and also when publishing the projects to HTML-based outputs, you might get links to HTML files like abc434243243.html, which are ugly and hard to remember.
  • In time, from one version of the user's guide to another, the titles of certain topics may change and having a way to update the file names based on titles in the entire project may be useful.
  • Sometimes after migrating another file format like Microsoft Word to a DITA Map using the Oxygen Batch Documents Converter add-on, you may want to make sure the topic file names reflect their titles.

Below, you can leave feedback or comments about such a practice or about using the script for your project.