Table of Contents & Sidebar Menu
Add items and adjust the styles of Quire’s auto-generated contents lists
Table of Contents
To create a Table of Contents (TOC), add a
.md file to your project with
layout: table-of-contents specified.
title: Contents order: 2 layout: table-of-contents
From there, Quire will automatically generate the TOC based on the structure of the files in your
content directory including assigned page order and the metadata of each page (the title, subtitle, contributors, etc.) If you add any Markdown to the
.md file, it will be displayed as formatted text above the contents list. Please see the Page Types & Structure section of our documentation for more information.
There are several different ways you can style your TOC’s appearance. TOC styles can be defined by adding the attribute
presentation to the page YAML of your contents
.md file. The default TOC style is
list. The three other styles available are
|The default style. Can include |
|Will only show |
|Includes everything in |
|A graphic layout. Will show a “card” for each page. For |
TOCs for Individual Sections
In Quire you can include multiple levels of sub-sections. Add sections by creating new directories within existing directories. For example, catalogue entries in a collection catalogue would appear within a
/content/catalogue/ directory. You could create additional directories within the
/content/catalogue/ directory to further organize your content. You would also need to include an
index.md file in each sub-section to act as a section landing page and TOC. This can be useful in collection catalogues where you want a
grid TOC displaying the objects in that catalogue section or for a collected papers volume where you want to show the abstracts for the pages in the section.
Once you have created your sub-section add an
index.md file with
layout: table-of-contents included in the page YAML. This will create a landing page that serves as the TOC for that particular sub-section. The TOC name will match the title used in the page YAML of the
title: Catalogue layout: table-of-contents presentation: grid order: 9
As mentioned in Pages Types & Structures, files named
index.md always inherit the URL of their parent directory. Using the example above, the URL for the
content/catalogue/index.md file would be
Removing Pages from the TOC
While the TOC is generated automatically by Quire based on the
.md pages in your
content directory, you can remove or hide pages from the TOC by adding
toc: false to the page YAML. This might be done, for example, for the project’s cover page, which would not typically be included in a traditional book TOC. Or for sub-section pages deep in the book that may clutter the TOC. In any case, hiding the page from the TOC will not change how the page appears when navigating by the Next and Previous buttons and links. Nor will it keep the page from otherwise being linked to or viewed.
toc: falsewill only remove the page’s listing in the TOC. To entirely hide a page from Quire’s multiple formats use the
outputsattribute and list the formats where you want that page to appear (
Page Numbering in the PDF
When you output your project as a PDF, page numbers will automatically be added to the pages and to the corresponding entries in the Table of Contents.
Traditionally, the frontmatter pages of books are numbered in lowercase Roman numerals (i, ii, iii, iv, etc.). The Arabic numeral 1 is then assigned to the first page of true “content” for the book. Usually the first chapter, or an introduction. Quire handles things the same way.
To assign a particular
.md file to be page 1 of your project, add
class: page-one to the page YAML. This tag defines that page as page 1 (in Arabic numerals), and everything before it is frontmatter and will be numbered in lowercase Roman.
Like the TOC, the sidebar Menu is generated automatically by Quire based on the structure of the files in your
content directory and the metadata of each page. Unlike the TOC, the Menu is a built-in part of every Quire project and does not have a corresponding
Removing Pages from the Menu
As described with the TOC above, you can remove or hide pages from the Menu by adding
menu: false to the YAML for that page.
Menu Other Formats & Footer Links
Following the list of contents in the sidebar Menu is a section with download links for the other formats of your Quire project. These are listed in the
publication.yaml file of your project in the
resource_link list. Any link listed here with a
type: other-format will show up in the “Other Formats” link list in the Menu. The
name attribute provides the text for the link as it appears.
- type: other-format name: PDF media_type: application/pdf link_relation: alternate url: /downloads/output.pdf
Similarly, links in the bottom footer of the Menu, are also created from links listed in the
resource_link list, but with
Read more about resource links in the Metadata & Configuration chapter of this guide.
Other Menu Items
The publisher logo, copyright statement, and license information found in the Menu are all generated from YAML in the
publication.yaml file of your project.
Read more about copyright and licenses in the Metadata & Configuration chapter of this guide.
Similarly, the “Cite This Page” feature in the Menu generates Chicago- and MLA-style citations for the current page based on YAML in the individual page itself, as well as that from the
Read more about citation-related YAML in the Copyright & About Pages chapter of this guide.