HTML to DITA migration checklist
for using the DITA Toolkit Migration Transform

(NOTE: This is a general list; your files may require different changes and the migration transform
might be updated to support additional features. The latest version of this checklist can be found on /xml.coverpages.org/DITA-MigrationChecklist.html)

Tidy processing

tidy -c -n -m --output-xml yes --doctype omit myfile.html

Removes DOCTYPE tag

Adds ending tags (especially the link tag)

Verifies all lists items encapsulated with <li></li>

Verifies definition <dl> lists formatted correctly

Converts a <span style=xx> to a style entry (inline CSS) and adds a class attribute to the span.

Removes comments (most HTML editors add comments). If you want to save the comments, you need a customization.

Other pre-migration processing (may be automated in some cases)

Topic type

Ranking

Area

Description

All

Recommended

Metadata

Remove any HTML-editor-specific or unneeded meta data. Metadata migrates to <meta> elements in the <prolog>.

All

Strongly Recommended

Short descriptions

Add a short description as the first paragraph. This paragraph should not have tables, lists, or links. This becomes the first paragraph of the topic when it is generated.

All

Required

Headings

Verify that all headings in topics are in order, are at most two levels, and are one level apart. For example, h1 and h2, or h2 and h3.

Tasks can only have one heading.

All

Required

Anchor names and references

Remove special characters and blanks from anchor names.

All

Recommended

Graphics links

Verify they are in <img src=> format. It is recommended to add <alt> text to all graphics if missing.

All

Recommended

Search title

If you want a special search title, put the search title in <title> and the topic title in <h1>. If you dont want a search title, the h1 and title text need to match.

All

Recommended

Class attributes

If you use class attributes on certain HTML tags, you need to plan the migration, and it may require a customization.

All

Required

Manual line breaks (<br>)

Delete manual breaks either before or after migration. These are migrated as XML comment with the text: A br tag was used here in the original source.

All

Required

Single-sourcing

Verify that formatting is consistent in HTML and customize the migration process to retain the values.

All

Recommended

Notices

.

Verify notices migrated correctly to <note> elements, which has type attribute to indicate notice severity and set notice label.

All

Required

<blockquote> elements

Determine why it is used and if not needed, remove before or after migration. If you need it, migrate, then customize.

Migrates to <lq>, but not good use of DITA.

All

Recommended

<span> tag use

If using <span> for context tagging, review transform to verify the different forms of the span (such as span for bold) get migrated to the correct DITA element for you files.

All

Required

Code tagging

Verify code in procedures uses <pre> and not <blockquote> so that it migrates to <codeblock>.

Code snippets within a paragraph that are tagged as <tt> migrate to <codeph>.

All

Required

Special characters

  • If you use UTF-8: OK
  • If you use numeric entities (&#137;): OK
  • If you use the character entities that are not XML entities (&mdash;): Needs verification
  • If it is not an XML entity (&amp;, &gt;, &lt; and &quot;) it does not migrate correctly. Tidy may convert all your non-XML character entities to numeric entities.

Task

Optional

Task prerequisite

If migrating to a prerequisite element, set up customization and tagging.

For example add <p class=prereq> as first paragraph, if it is a prerequisite and customize to migrate to the <prereq> element.

Task

Optional

Multiple option steps

Format multiple option steps as a nested list.

Task

Optional

Step results

If creating elements other than cmd and info, then you must customize.

Task

Required

Only one task per Task topic

If topic contains multiple tasks, must break information up into separate tasks or use the tutorial override, which allows subtasks.

The Task topic type supports having only one task per Task topic.

Task

Recommended

Task results

Verify overall task result is outside of the ordered list of steps.

Task

Recommended

Single-step tasks

Verify single-step tasks are in a list with a bullet.

All

Optional

Index entries

Plan index migration.

All

Recommended

Multimedia elements

Verify that all multimedia elements are within <object> elements.

 

Post-migration DITA Checklist

Topic type

Ranking

Area

Description

All

Required

Valid DITA

Verify that each topic is a valid DITA topic. Some editors provide XML/DITA validations.

All

Strongly Recommended

Required Cleanup

Review and remove any items that are tagged with Required Cleanup. The migration transform did not know what to do the these constructs since they are not supported in DITA.

All

Recommended

GUI items

Verify use of uicontrol and menucascade is correct (if customized to use these elements)

All

Required

Cross References

Verify cross referenced files that are NOT in DITA do not have the .dita extension.

All

Recommended

Notes

Verify Notes elements are correct