Introduction to Mallard

Titles

The <title> element is used to mark up the title for a <page>, <section>, <list>, <table> or formal block element.

Primary title

The primary title of a page or section is the one specified in the block context and used for display purposes. While this title is not an informational title, it is used as fallback for all informational titles.

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">

  <title>User help for my application</title>

</page>

Informational titles

Informational titles are used to specify alternative titles for pages or sections, and appear inside the <info> element of each. The type attribute specifies the purpose of the informational title, and can be link, sort or text.

`link`

Link titles are used as alternate title text for automatic links. Pages and sections can have multiple link titles, up to one for each type of backlink. When automatic text must be generated for a <link> element, it is taken first from the link titles, falling back to the primary title if no suitable link title is found.

If you do not specify a role for the link title, it will be used for all link types.

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">

  <info>
    <title type="link">My application help</title>
  </info>

  <title>User help for my application</title>

</page>

If you want a specific link title to be used only for a guide, topic, seealso, series or trail, you can specify it in the role:

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">

  <info>
    <title type="link" role="seealso">Application help</title>
  </info>

  <title>User help for my application</title>

</page>

`sort`

Sort titles allow you to specify an alternate title to be used when sorting the page or section. This is useful for excluding leading articles such as “an” and “the”.

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">

  <info>
    <title type="sort">Application help</title>
  </info>

  <title>User help for my application</title>

</page>

text

Text titles are used wherever a plain text string without formatting is required. This is useful for window titles or labels in user interfaces where formatting and inline images are difficult or impossible. This is particularly useful when a title contains an image with fallback text, but you do not want the fallback text to appear in places such as window titles.

<page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">

  <info>
    <title type="text">Application Help</title>
  </info>

  <title>This is the primary title</title>

</page>

Learn more

For more on Mallard titles, see http://projectmallard.org/1.0/mal_block_title and http://projectmallard.org/1.0/mal_info_title.