# Table of Contents

The headings of the current page, as a rail beside it or a folded list above it.

The table of contents lists the second and third level headings of a page. From 1200px it is a rail right of the content that marks the heading the reader has scrolled to. Below that, it folds into a list at the top of the page.

::component-preview{src="~/demos/TableOfContentsDemo.vue"}
::

## Anatomy

The layer renders both versions on every page. Each shows its own width and hides at the other.

::component-anatomy
---
parts:
  - name: DocsToc
    description: The rail. Follows the scroll position and keeps the marked heading in view.
    children:
      - name: DocsTocList
        required: true
        description: The headings, nested by level.
      - name: DocsTocFooter
        description: Renders nothing until you replace it.
  - name: DocsTocInline
    description: The folded list above the content.
    children:
      - name: DocsTocList
        required: true
        description: The same headings, without a marked one.
---
::

## Usage

Both versions take the links Nuxt Content writes into a page’s body.

```vue
<template>
  <docs-toc :links="page?.body?.toc?.links ?? []" />
</template>
```

The layer lists headings down to the third level. To change that, set `content.build.markdown.toc.depth` in `nuxt.config.ts`.

`DocsTocList` renders the links without the rail, so it works anywhere a page needs its headings. The heading named by `active-id` is marked with `aria-current`.

```vue
<template>
  <docs-toc-list :links="links" active-id="usage" />
</template>
```

## Under the rail

`DocsTocFooter` sits under the rail and renders nothing. Replace it with a component of the same name in your app to fill the space, for a list of sponsors for example.

```vue [app/components/DocsTocFooter.vue]
<template>
  <p class="docs-caption text-surface-muted mt-10 px-2">
    Sponsored by Magic as a Service™
  </p>
</template>
```

## API reference

### `DocsToc`

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Default
rows:
  - items:
      - label: links
        description: The page’s headings, from `body.toc.links`.
      - label: Array<TocLink>
      - label: none
        plaintext: true
---
::

### `DocsTocInline`

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Default
rows:
  - items:
      - label: links
        description: The page’s headings, from `body.toc.links`.
      - label: Array<TocLink>
      - label: none
        plaintext: true
---
::

### `DocsTocList`

::docs-table
---
columns:
  - label: Prop
  - label: Type
  - label: Default
rows:
  - items:
      - label: links
        description: The headings to list. Their `children` nest one level in.
      - label: Array<TocLink>
      - label: none
        plaintext: true
  - items:
      - label: activeId
        description: The `id` of the heading to mark as the current one.
      - label: string
      - label: none
        plaintext: true
---
::

### `DocsTocFooter`

Takes no props.