Implicit Link Groups

This page outlines a mechanism for using groups on the links element that implicitly match metadata on the target node, rather than matching an explicit group attribute. The current proposal includes matching on id attributes and style hints, but it can be extended to other metadata in the future.

Authors: Shaun McCance
Created: 2020-02-22
Status: proposed (2020-02-22)
Target: 1.2
show history
hide history
2020-02-22 1.2 proposed

This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.


Topic links elements allow you to specify a list of groups, where each group is matched against the group attribute of a link element. This allows you to override the default order. It also allows you to segment the topic links for a guide page into multiple link lists, with potentially block content between lists, or different styling for different lists.

People currently use this in three ways:

  1. Using the implicit #first, #default, and #last groups to move specific lists to the top and bottom.

  2. Creating a few logical groups of links, sometimes giving each group a title or introductory text.

  3. Manually specifying the exact order of links.

The first use case works very well, thanks to the inclusion of the implicit groups. Without the implicit groups, this would be somewhat more tedious, though no moreso than the second use case.

The second use case works reasonably well. Groups can have logical, semantic names. Having link targets include these semantic groups feels natural, but sometimes it duplicates other metadata. For example, you might group all tutorials together using a tutorial group, then specify on the link target that it belongs to the group. In this case, tutorials might already use style="tutorial", which leads to a duplication of information.

The third case works very poorly. Each link target ends up declaring a unique group, which is usually just the same as the id attribute.


This page proposes adding special groups that match existing metadata on the link target. A special group would always contain a colon character and be of the form key:value. The key indicates what metadata is being matched against, while the value indicates the value to match.

This page proposes two special group types: id and style. More special group types could be added in the future.

An id group matches against the fully qualified ID of the target. For a page, that is simply the value of the id attribute. For anything inside a page, it is the containing page id and the target id, combined with the # character. This is the same form you would use to link to the target.

A style group matches a style hint on the target node. For this group type, the style hint is always taken from the style attribute of the page, section, or formal block element being linked to. The style attribute is a space-separated list of style hints. The group matches if it is the same as any style hint in the list of style hints on the link target.


Explicitly order links based on their id attributes:

<links type="topic" groups="id:firstpage id:secondpage id:thirdpage"/>

Group tutorials first based on style hints:

<links type="topic" groups="style:tutorial">
<links type="topic" groups="#first #default #last">
  <title>All Other Topics</title>


No alternatives were considered, but there are two further group types that were considered but deferred for this MEP:

  • Matching against tags. Tags are still an open enhancement proposal, and that could complicate an initial implementation of this proposal.

  • Matching against Version Information. Revisions are tricky, because you might want to select based on a current version number. Furthermore, there are plans to change the revision element (MEP-0006: More Flexible version Attribute and Issue #33). Any special revision matching should take those developments into account.

Compatibility and Fallback

This proposal could potentially create backwards compatibility issues if anybody is using explicit groups that look like the new implicit groups. For example, if a writer defines the group style:tutorial with the intention of using an explicit group="style:tutorial" attribute on informational link elements, with this proposal implemented, that group would start matching elements with the tutorial style hint. It's unlikely this affects any real-world documents.

The fallback behavior for any link targets that should be matched with special groups is that they would be placed in #default by any tool that doesn't support this proposal. There is no loss information, but the presentation would be imperfect.

Comparison to Other Formats

The link grouping mechanism is unique to Mallard's method of collecting and organizing links, so no comparisons can be made.

© 2020 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by