#### 24.5.12 Specifying DITA element levels

To specify the level at which a block element should appear in DITA output, you can assign a level number to any paragraph formats that are mapped to the element (see §24.4.3 Mapping paragraph formats to DITA block elements). However, for most nesting issues, you should use settings that specify ancestry rather than level; see §24.5.2 Designating DITA ancestor elements.

Assign levels only for the following purposes:

- to identify paragraph formats mapped to <title> that should start new topics; assign level 1 to each such format
- to handle unusual situations that cannot be addressed any other way.

To specify the level of a DITA block element:

    [DITALevels]
    ; Frame para format (wildcards OK) = level in DITA (not Frame) file
    ;  required for the DITAParaTag specified for this element.
    FmtName = N

The lower the level number, the higher the level; <topic> is level 0, the root. You cannot put anything else at level 0. The topic title is at level 1. The first heading in the topic body is at level 3 (a title below <topic>, <body>, and <section>).

Specify level 1 for each paragraph format that starts a topic. For example:

    [DITALevels]
    Title = 1
    Heading* = 1
    GlossItem = 1

Assign level 1 only to topic-title formats. If you assign level 1 to a paragraph format that does not start a topic, each topic in which such a paragraph occurs will end prematurely, and a new topic will start at the level-1 paragraph. Probably not what you want.

Do not try to use DITA levels to achieve nested lists; instead see §24.5.8 Configuring nested lists.

To override the assigned level of a particular paragraph, place a DITALevel PI marker in the paragraph. A DITALevel PI marker specifies the level at which the current block element should appear in the DITA file, overriding whatever is specified for the format in [DITALevels]. The content of a DITALevel PI marker is a single integer.

See also:

§25.1.2 Specifying topic levels in ditamaps

Previous Topic: 24.5.11 Configuring multi-paragraph list items

Next Topic: 24.6 Specifying options for tables in DITA XML

Parent Topic: 24.5 Nesting DITA block elements

Sibling Topics:

24.5.1 Understanding how DITA2Go determines element nesting

24.5.2 Designating DITA ancestor elements

24.5.3 Fixing up interpolated ancestries

24.5.4 Deciding when to fully specify ancestry

24.5.5 Specifying alternate ancestries for the same element

24.5.6 Avoiding invalid ancestries

24.5.7 Specifying first-child status for nested elements

24.5.8 Configuring nested lists

24.5.9 Closing DITA ancestor elements

24.5.10 Opening DITA ancestor elements

24.5.11 Configuring multi-paragraph list items