Struct OutlineElem

pub struct OutlineElem { /* private fields */ }

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.

Example

#set heading(numbering: "1.")
#outline()

= Introduction
#lorem(5)

= Methods
== Setup
#lorem(10)

Alternative outlines

In its default configuration, this function generates a table of contents. 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)}. Just the same, we could have set it to {figure.where(kind: table)} to generate a list of tables.

We could also set it to just figure, without using a where selector, but then the list would contain all figures, be it ones containing images, tables, or other material.

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

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

Styling the outline

At the most basic level, you can style the outline by setting properties on it and its entries. This way, you can customize the outline’s title, how outline entries are indented, and how the space between an entry’s text and its page number should be filled.

Richer customization is possible through configuration of the outline’s entries. The outline generates one entry for each outlined element.

Spacing the entries { #entry-spacing }

Outline entries are blocks, so you can adjust the spacing between them with normal block-spacing rules:

#show outline.entry.where(
  level: 1
): set block(above: 1.2em)

#outline()

= About ACME Corp.
== History
=== Origins
= Products
== ACME Tools

Building an outline entry from its parts { #building-an-entry }

For full control, you can also write a transformational show rule on outline.entry. However, the logic for properly formatting and indenting outline entries is quite complex and the outline entry itself only contains two fields: The level and the outlined element.

For this reason, various helper functions are provided. You can mix and match these to compose an entry from just the parts you like.

The default show rule for an outline entry looks like this¹:

#show outline.entry: it => link(
  it.element.location(),
  it.indented(it.prefix(), it.inner()),
)

• The indented function takes an optional prefix and inner content and automatically applies the proper indentation to it, such that different entries align nicely and long headings wrap properly.

• The prefix function formats the element’s numbering (if any). It also appends a supplement for certain elements.

• The inner function combines the element’s body, the filler, and the page number.

You can use these individual functions to format the outline entry in different ways. Let’s say, you’d like to fully remove the filler and page numbers. To achieve this, you could write a show rule like this:

#show outline.entry: it => link(
  it.element.location(),
  // Keep just the body, dropping
  // the fill and the page.
  it.indented(it.prefix(), it.body()),
)

#outline()

= About ACME Corp.
== History

---

1. The outline of equations is the exception to this rule as it does not have a body and thus does not use indented layout. ↩

Implementations

impl OutlineElem

pub fn new() -> Self

Create a new instance of the element.

pub fn with_title(self, title: Smart<Option<Content>>) -> Self

Builder-style setter for the title field.

pub fn with_target(self, target: LocatableSelector) -> Self

Builder-style setter for the target field.

pub fn with_depth(self, depth: Option<NonZeroUsize>) -> Self

Builder-style setter for the depth field.

pub fn with_indent(self, indent: Smart<OutlineIndent>) -> Self

Builder-style setter for the indent field.

pub fn push_title(&mut self, title: Smart<Option<Content>>)

Setter for the title field.

pub fn push_target(&mut self, target: LocatableSelector)

Setter for the target field.

pub fn push_depth(&mut self, depth: Option<NonZeroUsize>)

Setter for the depth field.

pub fn push_indent(&mut self, indent: Smart<OutlineIndent>)

Setter for the indent field.

pub fn title(&self, styles: StyleChain<'_>) -> Smart<Option<Content>>

The title of the outline.

• When set to {auto}, an appropriate title for the text language will be used.
• When set to {none}, the outline will not have a title.
• A custom title can be set by passing content.

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.")}

pub fn target<'a>(&'a self, styles: StyleChain<'a>) -> &'a LocatableSelector

The type of element to include in the outline.

To list figures containing a specific kind of element, like an image or a table, you can specify the desired kind in a where selector. See the section on alternative outlines for more details.

#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],
)

pub fn depth(&self, styles: StyleChain<'_>) -> Option<NonZeroUsize>

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

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

= Yes
Top-level section.

== Still
Subsection.

=== Nope
Not included.

pub fn indent(&self, styles: StyleChain<'_>) -> Smart<OutlineIndent>

How to indent the outline’s entries.

• {auto}: Indents the numbering/prefix of a nested entry with the title of its parent entry. If the entries are not numbered (e.g., via heading numbering), this instead simply inserts a fixed amount of {1.2em} indent per level.

• Relative length: Indents the entry by the specified length per nesting level. Specifying {2em}, for instance, would indent top-level headings by {0em} (not nested), second level headings by {2em} (nested once), third-level headings by {4em} (nested twice) and so on.

• Function: You can further customize this setting with a function. That function receives the nesting level as a parameter (starting at 0 for top-level headings/elements) and should return a (relative) length. For example, {n => n * 2em} would be equivalent to just specifying {2em}.

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

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

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

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

== Products
#lorem(10)

pub fn title_in(styles: StyleChain<'_>) -> Smart<Option<Content>>

Access the title field in the given style chain.

pub fn target_in(styles: StyleChain<'_>) -> &LocatableSelector

Access the target field in the given style chain.

pub fn depth_in(styles: StyleChain<'_>) -> Option<NonZeroUsize>

Access the depth field in the given style chain.

pub fn indent_in(styles: StyleChain<'_>) -> Smart<OutlineIndent>

Access the indent field in the given style chain.

pub fn set_title(title: Smart<Option<Content>>) -> Property

Create a style property for the title field.

pub fn set_target(target: LocatableSelector) -> Property

Create a style property for the target field.

pub fn set_depth(depth: Option<NonZeroUsize>) -> Property

Create a style property for the depth field.

pub fn set_indent(indent: Smart<OutlineIndent>) -> Property

Create a style property for the indent field.

Trait Implementations

impl Capable for OutlineElem

fn vtable(capability: TypeId) -> Option<NonNull<()>>

Get the pointer to the vtable for the given capability / trait.

impl Clone for OutlineElem

fn clone(&self) -> OutlineElem

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Construct for OutlineElem

fn construct(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Content>

Construct an element from the arguments.

impl Debug for OutlineElem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Fields for OutlineElem

type Enum = Fields

An enum with the fields of the element.

fn has(&self, id: u8) -> bool

Whether the element has the given field set.

fn field(&self, id: u8) -> Result<Value, FieldAccessError>

Get the field with the given field ID.

fn field_with_styles( &self, id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID in the presence of styles.

fn field_from_styles( id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID from the styles.

fn materialize(&mut self, styles: StyleChain<'_>)

Resolve all fields with the styles and save them in-place.

fn fields(&self) -> Dict

Get the fields of the element.

impl Hash for OutlineElem

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for OutlineElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for OutlineElem

fn data() -> &'static NativeElementData

Get the element data for the native Rust element.

fn elem() -> Element

where Self: Sized,

Get the element for the native Rust element.

fn pack(self) -> Content

where Self: Sized,

Pack the element into type-erased content.

impl NativeScope for OutlineElem

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl PartialEq for OutlineElem

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Repr for OutlineElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for OutlineElem

fn set(engine: &mut Engine<'_>, args: &mut Args) -> SourceResult<Styles>

Parse relevant arguments into style properties for this element.