Linking pages

About

One of the greatest benefits of Mallard is automatic linking. Pages and sections are able to declare links to and from other pages and sections. Links are added to the <info> element.

Example

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="page-create">

  <info>
    <link type="guide" xref="index"/>
    <link type="seealso" xref="guide-create"/>
  </info>

  <title>Create a topic page</title>

  <p>Use topic pages to write instructions. These pages should usually contain tasks, but can also contain other documentation.</p>

</page>

Link a topic to a guide

The most basic type of linking is a topic page linked to a guide page. This is done using a <link> element inside the <info> element of the topic page, which is a type="guide".

Use the guide type when the link is going to point to a guide page. In other words, if you want your page to be listed in a guide page you can include a link to the guide page in it.

This type of linking is very useful as it allows you to add and delete pages without needing to worry about updating links.

If you want to link to a section in the page, you just need to specify the section in the xref. For example, to link to a section in the index which has an ID topics:

<info>
  <link type="guide" xref="index#topics"/>
</info>

Link a guide to a topic

If you prefer a more traditional style linking system, you can add the link to the page on which it appears. These links are still automatic, and will not be shown if the target of the link cannot be found. This is especially useful when creating a pool of reusable content, as any broken links will automatically disappear when the documentation is viewed.

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

  <info>
    <link type="topic" xref="page-create"/> 
  </info>

  <title>Welcome to your application help</title>

</page>

Reference another page

Use seealso type links to link related topic and guide pages. When you use a seealso link on a certain page, it is automatically duplicated on the page to which it is linked. This means that if you use a seealso link to page B on page A, a seealso link to page A is automatically included on page B.

A topic page with a seealso link to a guide page

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="topic-create">

  <info>
    <link type="seealso" xref="guide-create"/>
  </info>

  <title>Create a topic page</title>

  <p>Use topic pages to write instructions. These pages should usually contain tasks, but can also contain other documentation.</p>

</page>

A guide page with a seealso backlink from a topic page

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

  <title>Create a guide page</title>

  <p>Use guide pages to list topic pages.</p>

</page>

Learn more

For more about Mallard links, including specifying link groups, setting link order, and creating other kinds of links, see http://projectmallard.org/1.0/mal_links#section