Creating a New DITA Topic

The basic building block for DITA information is the DITA topic. DITA provides a variety of specialized topic types, the most common of which are:
  • Concept - For general, conceptual information such as a description of a product or feature.
  • Task - For procedural information such as how to use a dialog box.
  • Reference - For reference information.
  • Topic - The base topic type from which all other topic types are specialized. Typically, it is used when a more specialized topic type is inappropriate.
To add a new topic to a DITA map, follow these steps:
  1. Select a node of a map open in the DITA Maps Manager View.
  2. To insert the topic as a child of the selected node, right-click that node and choose Append Child > New. To insert the topic as a sibling to the current node, choose Insert After > New.
    A dialog box is displayed that allows you to create a new DITA topic using various types of DITA file templates and provides some options that help you to configure the new topic.

    Figure: New DITA Topic Dialog Box

    Note: The templates that appear in this dialog box include all templates that have an associated .properties file and the type property is set to dita, as well as templates that do not have an associated properties file or the type property is not defined. It will also include custom templates that you create using the procedures presented in the Creating New Document Templates topic.
  3. Select the appropriate DITA topic type from the list templates. You can use the filter text field to search for a template.
  4. You can use the following options to preconfigure some topic creation tasks:
    1. Title - The text entered in this field will be used as the value of the root title element for the new topic. The title is set only if the selected template contains a root with a title element as its first child.
    2. Use the title to generate the file name - Select this option to use the text entered in the Title field to automatically generate a file name. The generated name will transform spaces into underscores (_), all illegal characters will be removed, and all upper case characters changed to lower case (the generated name can be seen in the Save as field).
    3. Save as - Select a file name and path in this field.
    4. Use the file name as the value of the root ID attribute - Select this option to use the file name (without the file extension) in the Save as field as the value of the root id attribute for the new topic.
  5. Click the Create button.
    A reference (topicref) to the new topic is added to the current map and the new topic is opened in the editor.