Convert Word documents to DITA

Learn how to convert Microsoft Word documents into DITA documents and map.

FrameMaker allows you to migrate your existing Word documents (.docx) into DITA topic type documents. You need to specify the input and output folder locations along with other parameters and the document gets converted into DITA document. Depending on the content, you could have a .dita file and a .ditamap file.

To be able to convert a Word document successfully, your document should be well structured. For example, your document should have a Title, followed by Heading 1, Heading 2, and so on. Each of the headings should have some content in it. If your document is not well structured, the process might not work as expected.

By default, FrameMaker uses the Word-to-DITA (Word2DITA) transformation framework. This transformation depends on the style-to-tag mapping configuration file. To be able to use the Word2DITA transformation successfully, you must consider the following guidelines for preparing your Word document for conversion:

• Ensure that your document starts with a Title; this Title is mapped to the DITA map title. Also, the Title must be followed by some regular content.

• After the Title, there should be Heading 1, Heading 2, and so on. Each Heading must have some content in it. The Headings are converted into new Concept type topics. The hierarchy of the generated topics is as per the Heading levels in the document, for example, Heading 1 will precede Heading 2, and Heading 2 will precede Heading 3 content.

• The document must have at least one Heading type content.

• Ensure that you do not have any grouped images. In case you have grouped images in your document, ungroup all such images.

• Remove all headers and footers.

• Inline styles such as bold, italics, and underline are converted into <b>, <i>, and <u> elements.

• All ordered and unordered lists are converted into <ol> and <ul> elements. This also applies to nested lists, lists within tables, notes, or footnotes.

• All hyperlinks are converted into <xref>.

• The filename of the converted files is based on the heading text followed by a file number.

To convert a Word document to DITA, perform the following steps:

1. Choose Structure > Utilities > Convert Word (.docx) to DITA.

   The Convert Word (.docx) to DITA dialog box appears.

   Figure 1. Word to DITA conversion dialog box
   
   

2. In the Convert Word (.docx) to DITA dialog box, provide the following:

   • File: Path of the source Word file that you want to convert.

   • Style to Tag Map: The mapping file used for conversion. The default mapping file is available at the following location:

     C:\Users\<username>\AppData\Roaming\Adobe\FrameMaker\17\X2DITA\Word2DITA\style2tagMap.xml

     You can add your customizations to the default mapping file. If you are using a file different from the source mapping file, then update the path of the file in the Style to Tag Map location.

   • Output DITA Files > Directory: Output location to save the converted DITA document. By default, a DITA map file is created with the name of the source Word document. The topics folder contains .dita files, which are created on the basis of the mapping file’s configurations. The topics directory contains a media subdirectory, which contains all media files used in the source Word document.