Content Portal Layout and Navigation

Sitemaps and their elements define and enforce content structures, layout, and navigation for your Content Portal.

Basic Site Section

Basic site sections contain content in a single version.

Basic site sections are useful if you publish simple content or if you want to publish multiple maps on the same navigational level.

Basic Site Section with a Map

The following example shows the site output results of a sitemap with a basic site section that references a single DITA map.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <!-- Tile title -->
            <navtitle>Basic Site Section</navtitle>
            <!-- Tile short description -->
            <shortdesc>Short Description</shortdesc>
            <!-- Tile icon -->
            <data href="media/portal_icon_blue.png" name="thumbnail"/>
        </topicmeta>
        <!-- Referenced DITA content -->
        <mapref href="content/map_a.ditamap"/>
    </sitesection>
</sitemap>

Basic Site Section with Nested Topics

This example shows the site output results of a basic site section that references a structure of nested DITA topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <navtitle>Basic Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_a.dita">
            <topicref href="content/task_a.dita"/>
            <topicref href="content/reference_a.dita"/>
        </topicref>
        <topicref href="content/concept_b.dita">
            <topicref href="content/task_b.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topicref>
    </sitesection>
</sitemap>

Basic Site Section with Nested Topics and Chunking

This example shows the site output results of a basic site section that references a structure of nested DITA topics. The children topics are chunked to the parent topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <navtitle>Basic Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_a.dita" chunk="to-content">
            <topicref href="content/task_a.dita"/>
            <topicref href="content/reference_a.dita"/>
        </topicref>
        <topicref href="content/concept_b.dita" chunk="to-content">
            <topicref href="content/task_b.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topicref>
    </sitesection>
</sitemap>

Site Section with Subsections

Site sections can contain up to five levels of nested subsections.

Tip: Site sections with subsections are useful if you publish complex content that may require additional levels of navigation.

Site Section with Subsections

The following example shows the site output results of a sitemap with a site section that contains two subsections. “Subsection A” references a DITA map and “Subsection B” references three DITA topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A sitesection with subsections -->
    <sitesection>
        <topicmeta>
            <navtitle>Site Section with Subsections</navtitle>
            <shortdesc>Short Description</shortdesc>
            <data href="media/portal_icon_yellow.png" name="thumbnail"/>
        </topicmeta>
        <!-- Subsection #1 -->
        <sitesection outputclass="view-tiles">
            <topicmeta>
                <navtitle>Subsection A</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_yellow.png" name="thumbnail"/>
            </topicmeta>
            <mapref href="content/map_b.ditamap"/>
        </sitesection>
        <!-- Subsection #2 -->
        <sitesection outputclass="view-tiles"> 
            <topicmeta>
                <navtitle>Subsection B</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_yellow.png" name="thumbnail"/>
            </topicmeta>
            <topicref href="content/concept_a.dita"/>
            <topicref href="content/concept_b.dita"/>
            <topicref href="content/concept_c.dita"/>
        </sitesection>
    </sitesection>
</sitemap>

Site Section with Content and Subsections

This example shows the site output results of a sitemap with a site section that references a DITA topic and contains two subsections. “Subsection A” references a DITA map and “Subsection B” references three DITA topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A basic sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <navtitle>Basic Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_a.dita"/>
        <!-- Sitesection tile #1 -->
        <sitesection>
            <topicmeta>
                <navtitle>Subsection A</navtitle>
            </topicmeta>
            <mapref href="content/map_a.ditamap"/>
        </sitesection>
        <!-- Sitesection tile #2 -->
        <sitesection>
            <topicmeta>
                <navtitle>Subsection B</navtitle>
            </topicmeta>
            <mapref href="content/map_b.ditamap"/>
        </sitesection>
        <!-- Referenced DITA content -->
        <topicref href="content/concept_b.dita"/>
    </sitesection>
</sitemap>

Site Section with Topicheads

Site sections (<sitesection> elements) can contain <topichead> elements.

Tip: <topichead> elements are useful for semi-complex content that may require some organization in the main table of contents.

They provide a non-linking title or heading.

Site Section with Content and Topicheads

This example shows the site output results of a sitemap with a <sitesection> element that contains a topic reference and two <topichead> elements. Each <topichead> element contains two DITA topics.

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <sitesection>
        <topicmeta>
            <navtitle>Site Section</navtitle>
        </topicmeta>
        <!-- Referenced DITA Content -->
        <topicref href="content/concept_a.dita"/>
        <!-- Topichead #1 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead A</navtitle>
            </topicmeta>
            <topicref href="content/task_a.dita"/>
            <topicref href="content/task_b.dita"/>
        </topichead>
        <!-- Topichead #2 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead B</navtitle>
            </topicmeta>
            <topicref href="content/reference_a.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topichead>
    </sitesection>
</sitemap>

Site Section with Topicheads Only

This example shows the site output results of a sitemap with a site section that contains two <topichead> elements. Each <topichead> element contains two DITA topics.

Note: In this case, the <sitesection> element behaves like a <topichead> element.

In other words, in the output, when you click the <sitesection> element, you are moved to the first element with content (“Task A”).

<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <sitesection>
        <topicmeta>
            <navtitle>Site Section</navtitle>
        </topicmeta>
        <!-- Topichead #1 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead A</navtitle>
            </topicmeta>
            <topicref href="content/task_a.dita"/>
            <topicref href="content/task_b.dita"/>
        </topichead>
        <!-- Topichead #2 -->
        <topichead>
            <topicmeta>
                <navtitle>Topichead B</navtitle>
            </topicmeta>
            <topicref href="content/reference_a.dita"/>
            <topicref href="content/reference_b.dita"/>
        </topichead>
    </sitesection>
</sitemap>

Sitemap Elements Reference

Sample Sitemap Structure

The following example shows a sitemap that contains a:

  • Site section with a map
  • Site section with subsections
  • Site section with topicheads
  • Versioned site section

Sitemap Elements

<!-- Model sitemap -->
<sitemap>
    <!-- Sitemap title -->
    <title>Sitemap</title>
    <!-- A basic sitesection that renders as a tile on the home page -->
    <sitesection>
        <!-- Site section details container -->
        <topicmeta>
            <!-- Tile title -->
            <navtitle>Basic Site Section</navtitle>
            <!-- Tile short description -->
            <shortdesc>Short Description</shortdesc>
            <!-- Tile icon -->
            <data href="media/portal_icon_blue.png" name="thumbnail"/>
        </topicmeta>
        <!-- Referenced DITA content -->
        <mapref href="content/map_a.ditamap"/>
    </sitesection>
    <!-- A sitesection with subsections -->
    <sitesection>
        <topicmeta>
            <navtitle>Site Section with Subsections</navtitle>
            <shortdesc>Short Description</shortdesc>
            <data href="media/portal_icon_yellow.png" name="thumbnail"/>
        </topicmeta>
        <!-- Subsection #1 -->
        <sitesection outputclass="view-tiles">
            <topicmeta>
                <navtitle>Subsection A</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_green.png" name="thumbnail"/>
            </topicmeta>
            <mapref href="content/map_b.ditamap"/>
        </sitesection>
        <!-- Subsection #2 -->
        <sitesection outputclass="view-tiles">
            <topicmeta>
                <navtitle>Subsection B</navtitle>
                <shortdesc>Short Description</shortdesc>
                <data href="media/portal_icon_green.png" name="thumbnail"/>
            </topicmeta>
            <topicref href="content/concept_a.dita"/>
            <topicref href="content/concept_b.dita"/>
            <topicref href="content/concept_c.dita"/>
        </sitesection>
    </sitesection>
<!-- A sitesection with topicheads -->
    <sitesection>
            <topicmeta>
                <navtitle>Site Section</navtitle>
            </topicmeta>
            <!-- Topichead #1 -->
            <topichead>
                <topicmeta>
                    <navtitle>Topichead A</navtitle>
                </topicmeta>
                <topicref href="content/task_a.dita"/>
                <topicref href="content/task_b.dita"/>
            </topichead>
            <!-- Topichead #2 -->
            <topichead>
                <topicmeta>
                    <navtitle>Topichead B</navtitle>
                </topicmeta>
                <topicref href="content/reference_a.dita"/>
                <topicref href="content/reference_b.dita"/>
            </topichead>
    </sitesection>
    <!-- A sitesection with versioned content -->
    <sitesection>
        <topicmeta>
            <navtitle>Versioned Site Section</navtitle>
            <shortdesc>Short Description</shortdesc>
            <data href="media/portal_icon_navy.png" name="thumbnail"/>
        </topicmeta>
        <!-- Version #1 container -->
        <version>
            <!-- Version details -->
            <topicmeta>
                <!-- Version information that will be visible in the version drop-down menu -->
                <navtitle>v1.0</navtitle>
            </topicmeta>
            <!-- Referenced DITA content -->
            <mapref href="content/map_c_v1_0.ditamap"/>
        </version>
        <!-- Version #2 container -->
        <version>
            <topicmeta>
                <navtitle>v2.0</navtitle>
            </topicmeta>
            <mapref href="content/map_c_v2_0.ditamap"/>
        </version>
    </sitesection>
</sitemap>
<sitemap> [required]
The root sitemap element.

Can contain the following elements:

  • <title>
  • <sitesection>
<title> [required]
The title of the sitemap.
<sitesection> [required]
By default a <sitesection> element is:
  • Rendered as a navigational tile
  • Present in the main table of contents

A container element for the following elements:

  • <topicmeta>
  • <version>
  • <mapref>
  • <topicref>
  • <topichead>
<topichead> [optional]
By default a <topichead> element is:
  • Not rendered as a navigational tile
  • Present only in the main table of contents

A container element for the following elements:

  • <mapref>
  • <topicref>
<topicmeta> [required]
A container element for the following elements:
  • <navtitle>
  • <shortdesc>
  • <data>
<navtitle> [required]
A site section, subsection, or topichead title.
<shortdesc> [optional]
A short description for site section or subsection rendered in a navigation tile.
Figure 1. Navigation Tiles.

The following example shows two navigation tiles: “Tile A” and “Tile B”.

<data> [optional]
An element that references an icon associated with a site section or subsection navigation tile.
<version> [optional]
An element that specifies the version of your content. Each version appears as a separate entry in the version drop-down list.

Can contain the following elements:

  • <topicmeta>
  • <mapref>
  • <topicref>
<mapref> or <topicref> [required]
An element that refers to either a DITA map or a DITA topic that contains the content that you want to publish to the site.
  • You can reference both regular DITA maps and sitemaps.
  • The referenced maps can contain <codeblock> elements.
  • You can nest <topicref> elements

Sitemap Attributes Reference

To modify the site layout, you can apply specific @outputclass attributes in the associated sitemap.

<sitesection> attributes and <topichead> attributes

Note: <sitesection> elements are specialized <topichead> elements.
@outputclass="view-tiles"

Default for <sitesection> elements.

  • Rendered as a navigation tile
  • Present in the main Table of Contents (TOC)
@outputclass="hidden"

Default for <topichead> elements.

  • Not rendered as a navigation tile
  • Present in the main TOC
Tip: The following element pairs render in the same way:
  • <sitesection outputclass="hidden"> and <topichead>
  • <sitesection> and <topichead outputclass="tile">

<topicref> attributes

@toc="no"
Hide a topic and its children from the main (left) TOC.
@chunk="to-content"
Chunk children topics to the parent topic. The parent topic displays as a single entry in the main (left) TOC.
@outputclass="full-content"

Default and exclusive for <topicref> elements.

  • Rendered in the central content area