Guide pages

Guide pages are navigational guides to topic pages. They are like indexes in books. There is very little actual content on a guide page, since it is merely a container for links to topic pages. A guide page is usually separated into topic-based sections and unordered links that may lead to a topic page or a sub-guide page. Each guide page should be specified with the type="guide" attribute and should (like all pages) be assigned a unique identifier in the id="" attribute that ideally matches the filename of the page. Guide pages list all topic pages in a smaller project or other guide pages and topics in larger projects.

A guide page is the starting point for the reader. It lists all topic pages in a smaller project or other guide pages and topics in larger projects.

Every project must have a special guide page named index.page to generate HTML documentation and to allow the Mallard document to be integrated into your application:

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

  <title>Beanstalk Help</title>

</page> 

Unlike other web or book indexes, Mallard guide pages are always up-to-date. Mallard guide pages normally do not themselves list all relevant topic pages. Instead, Mallard guide pages are informed of relevant topic pages or sub-guide pages by links placed directly in the topic or sub-guide page. This means that there is usually no need to revise a guide page. It also means that if a topic page has yet to be written, the guide page will contain no link rather than a broken link.

You can use several sub-guide pages, that act as landing pages, to help keep the index.page well organized. This is especially useful if you are working with many topic pages.