Automatic Links

Insert all topic links for a page or section:

<links type="topic"/>

Separate topic links by group, giving a title to each group:

<links type="topic" groups="#first">
  <title>First Things First</title>
</links>
<links type="topic" groups="#default">
  <title>Topics</title>
</links>
<links type="topic" groups="#last">
  <title>In Other News</title>
</links>

Provide quick links to the sections in a page:

<page id="index">
  <links type="section"/>
  <section id="first">
    <title>First</title>
  </section>
  <section id="second">
    <title>Second</title>
  </section>
  <section id="third">
    <title>Third</title>
  </section>
</page>

A links element with type "topic" inserts topic links from a guide page or section. Guides may also have topic links to external resources using an href attribute. A guide has a topic link to an external resource or to another node if one of the following conditions is true:

Topic links are the inverse of guide links for internal links using the xref attribute.

There may be more than one topic links element in a single guide, each one displaying links from a different list of groups. The groups for a links element are taken from the groups attribute, which is treated as a space-separated list. The groups are then augmented as follows:

Each topic link for the guide has an associated group, taken from the group attribute of the link element that declared the link. If the link element does not declare a group, or if its group is not in the list of all groups for the guide, its group is #default.

A topic links element shows only those links with a group that matches one of the values in its groups list. Links are sorted first by the position of their group in the groups list for the links element. They are then sorted by their sort titles.

The link text for a topic link is taken from the title of the target node, or from the link element itself for external links, as follows:

Topic links are valid for guide pages and sections in guide pages. If a guide page or section has topic links, but does not have a topic links element, the topic links are inserted implicitly as if there were a topic links element after all child block content, but before any subsections. The implicit links element has the default groups list "#first #default #last".

A links element with type "guide" inserts guide links to guide pages or sections. A node may also have guide links to external resources using an href attribute. A node has a guide link to an external resource or to a guide if any of the following conditions is true:

Guide links are the inverse of topic links for internal links using the xref attribute.

If a node has a guide link to another page or section, that link is shown even if the target is not a guide. This allows guide links to be used for upwards navigation to different types of collection pages, such as those defined by extensions.

A guide links element shows all guide links for the enclosing page or section. Links are sorted by the sort title of their target guides.

The link text for a guide link is taken from the title of the target node, or from the link element itself for external links, as follows:

Guide links are valid on all pages and sections. If a node has guide links, but does not have a guide links element, the guide links are inserted implicitly as if there were a guide links element at the end of the node, after any block content and subsections.

See-also links are links from nodes to any other nodes. Nodes may also have see-also links to external resources using an href attribute. A node has a see-also link to an external resource or to another node if any of the following two conditions is true:

Internal see-also links always reciprocate; that is, if A has a see-also link to B, B always has a see-also link back to A.

A links element with type "seealso" inserts the see-also links for the containing node. Links are sorted by the sort title of their target nodes.

The link text for a see-also link is taken from the title of the target node, or from the link element itself for external links, as follows:

See-also links are valid on all pages and sections. If a node has see-also links, but does not have a see-also links element, the see-also links are inserted implicitly as if there were a see-also links element at the end of the node, after any block content and subsections.

Previous and next links are links between pages that allow you to create simple linear series of pages within a Mallard document. Previous and next links are only expected to be supported on pages. Previous and next links may not reference external resources with the href attribute.

A page has a next link to another page if it has an informational link with type "next" whose xref attribute points to that target page. Previous links are not declared explicitly. Instead, a page implicitly has a a previous link to a target page if the target page has a next link to it. If more than one page declares a next link to the same target, the behavior is undefined.

A links element with type "prevnext" inserts previous and next links for the containing page. Link text may be standard strings like “Previous” and “Next”. When link text is taken from the title of the target page, it is taken as follows:

No link title roles are currently recommended for previous and next links.

Previous and next links are valid for all pages. If a page has previous or next links, but does not have a links element with type "prevnext", the previous and next links are inserted implicitly. Previous and next links may be displayed in a navigation bar in a header or footer. Some implementations may have other presentations.

A links element with type "series" inserts links to all pages within a linear series created by next links. The sequence of links is such that each target page has a next link to the next target. The current page is shown at its place in the series without being linked to, to give users context. Implementations should be careful to detect cycles in next links.

The link text for a series link is taken from the title of the target node, as follows:

Since next links are only valid on pages, series links are also only valid on pages. If a page does not contain a series links element, the series links are not displayed. Series links are not implicit.

A links element with type "section" inserts links to the child sections of the containing node. By default, only the direct child sections should be shown, but tools may use a style hint to create a tree of links to nested sections.

The link text for a section link is taken from the title of the target section, as follows:

No link title roles are currently recommended for section links.

Section links are valid for any page or section that contains child sections. If a page or section does not contain a section links element, the section links are not displayed. Section links are not implicit.

A links element is displayed as a block, usually with each link as a block or list item. Some types of links may be formatted differently, and formatting may depend on style hints. Links should be clearly formatted to separate them from surrounding content and other types of links.

When present, the title element should be displayed in a way that makes it clear that it is the title of the links element. If a title element is not present, a title may be automatically generated for certain types of links.

If there are no links to display for a links element, then the element as a whole is not displayed, including its title.

If links for a node are displayed after child sections of that node, they should be separated using a header or other formatting to make it clear that they do not belong to the child section.

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the links element. The namespace declarations for this definition are on the page Pages.

mal_links = element links {
  mal_links_attr,
  mal_block_title ?,
  mal_links_content *
}
mal_links_attr = (
  attribute type { xsd:NMTOKEN },
  attribute style { xsd:NMTOKENS } ?,
  attribute role { text } ?,
  attribute groups { text } ?,
  mal_attr_external *
)
mal_links_content = mal_external