Documentation

outlineElement
Question mark

A table of contents, figures, or other elements.

This function generates a list of all occurrences of an element in the document, up to a given depth. The element's numbering and page number will be displayed in the outline alongside its title or caption. By default this generates a table of contents.

Example

#outline()

= Introduction
#lorem(5)

= Prior work
#lorem(10)
Preview

Alternative outlines

By setting the target parameter, the outline can be used to generate a list of other kinds of elements than headings. In the example below, we list all figures containing images by setting target to figure.where(kind: image). We could have also set it to just figure, but then the list would also include figures containing tables or other material. For more details on the where selector, see here.

#outline(
  title: [List of Figures],
  target: figure.where(kind: image),
)

#figure(
  image("tiger.jpg"),
  caption: [A nice figure!],
)
Preview

Styling the outline

The outline element has several options for customization, such as its title and indent parameters. If desired, however, it is possible to have more control over the outline's look and style through the outline.entry element.

Parameters
Question mark

title
none or auto or content
Settable
Question mark

The title of the outline.

The outline's heading will not be numbered by default, but you can force it to be with a show-set rule: show outline: set heading(numbering: "1.")

Default: auto

target
label or selector or location or function
Settable
Question mark

The type of element to include in the outline.

To list figures containing a specific kind of element, like a table, you can write figure.where(kind: table).

Default: heading.where(outlined: true)

View example
#outline(
  title: [List of Tables],
  target: figure.where(kind: table),
)

#figure(
  table(
    columns: 4,
    [t], [1], [2], [3],
    [y], [0.3], [0.7], [0.5],
  ),
  caption: [Experiment results],
)
Preview

depth
none or int
Settable
Question mark

The maximum level up to which elements are included in the outline. When this argument is none, all elements are included.

Default: none

View example
#set heading(numbering: "1.")
#outline(depth: 2)

= Yes
Top-level section.

== Still
Subsection.

=== Nope
Not included.
Preview

indent
none or auto or bool or relative or function
Settable
Question mark

How to indent the outline's entries.

Migration hints: Specifying true (equivalent to auto) or false (equivalent to none) for this option is deprecated and will be removed in a future release.

Default: none

View example
#set heading(numbering: "1.a.")

#outline(
  title: [Contents (Automatic)],
  indent: auto,
)

#outline(
  title: [Contents (Length)],
  indent: 2em,
)

#outline(
  title: [Contents (Function)],
  indent: n => [] * n,
)

= About ACME Corp.
== History
=== Origins
#lorem(10)

== Products
#lorem(10)
Preview

fill
none or content
Settable
Question mark

Content to fill the space between the title and the page number. Can be set to none to disable filling.

Default: repeat(body: [.])

View example
#outline(fill: line(length: 100%))

= A New Beginning
Preview

Definitions
Question mark

entryElement
Question mark

Represents each entry line in an outline, including the reference to the outlined element, its page number, and the filler content between both.

This element is intended for use with show rules to control the appearance of outlines. To customize an entry's line, you can build it from scratch by accessing the level, element, body, fill and page fields on the entry.

#set heading(numbering: "1.")

#show outline.entry.where(
  level: 1
): it => {
  v(12pt, weak: true)
  strong(it)
}

#outline(indent: auto)

= Introduction
= Background
== History
== State of the Art
= Analysis
== Setup
Preview

level
int
RequiredPositional
Question mark

The nesting level of this outline entry. Starts at 1 for top-level entries.

element
content
RequiredPositional
Question mark

The element this entry refers to. Its location will be available through the location method on content and can be linked to.

body
content
RequiredPositional
Question mark

The content which is displayed in place of the referred element at its entry in the outline. For a heading, this would be its number followed by the heading's title, for example.

fill
none or content
RequiredPositional
Question mark

The content used to fill the space between the element's outline and its page number, as defined by the outline element this entry is located in. When none, empty space is inserted in that gap instead.

Note that, when using show rules to override outline entries, it is recommended to wrap the filling content in a box with fractional width. For example, box(width: 1fr, repeat[-]) would show precisely as many - characters as necessary to fill a particular gap.

page
content
RequiredPositional
Question mark

The page number of the element this entry links to, formatted with the numbering set for the referenced page.