Skip to content

Commit

Permalink
update tableofcontents docs describing scrollParent options
Browse files Browse the repository at this point in the history
  • Loading branch information
bdbch committed Jul 16, 2024
1 parent 8c82e02 commit f649211
Showing 1 changed file with 32 additions and 20 deletions.
52 changes: 32 additions & 20 deletions src/content/editor/extensions/functionality/table-of-contents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,16 @@ title: Table of Contents extension
tags:
- type: pro
meta:
title: Contents extension | Tiptap Editor Docs
description: Integrate a list of anchors to your document and collect all headlines in a nice TOC (Table of Contents). Learn more in the docs!
category: Editor
title: Contents extension | Tiptap Editor Docs
description: Integrate a list of anchors to your document and collect all headlines in a nice TOC (Table of Contents). Learn more in the docs!
category: Editor
extension:
name: Table of contents
description: Add a table of contents of all your anchors or headlines.
type: extension
icon: List
name: Table of contents
description: Add a table of contents of all your anchors or headlines.
type: extension
icon: List
---

import { CodeDemo } from '@/components/CodeDemo'
import { Callout } from '@/components/ui/Callout'

Expand All @@ -20,10 +21,11 @@ The `TableOfContents` extension lets you get a list of anchors from your documen
<CodeDemo isPro path="/Extensions/TableOfContents" />

## Install

<Callout title="Set up access to Tiptap's private repository" variant="info">
Integrate this pro extension by registering for a free [Tiptap
account](https://cloud.tiptap.dev/register) and following our [access
guide](/guides/pro-extensions) to Tiptap’s private repository.
Integrate this pro extension by registering for a free [Tiptap
account](https://cloud.tiptap.dev/register) and following our [access
guide](/guides/pro-extensions) to Tiptap’s private repository.
</Callout>

Once done, you can install the extension from our private registry:
Expand All @@ -35,6 +37,7 @@ npm install @tiptap-pro/extension-table-of-contents
## Settings

### anchorTypes

The types of the nodes you want to use for your Table of Content. By default this is `["heading"]` but in case you create your own custom Heading extension OR extend the existing one and use a different name, you can pass that name here.

Default: `["heading"]`
Expand All @@ -46,14 +49,15 @@ TableOfContents.configure({
```

### getIndex

This option can be used to customize how the item indexes are calculated. By default this is using an internal function but it can be overwritten to do some custom logic.

```js
TableOfContents.configure({
getIndex: (anchor, previousAnchors, level) => {
// do some custom logic, but for this example we will just return 1
return 1
}
},
})
```

Expand All @@ -74,18 +78,20 @@ TableOfContents.configure({
```

### getLevel

This option can be used to customize how item levels are generated. By default the normal level generation is used that checks for heading element level attributes. If you want to customize this because for example you want to include custom anchors in your heading generation, you can use this to do so.

```js
TableOfContents.configure({
getLevel: (anchor, previousAnchors) => {
// do some custom logic, but for this example we will just return 1
return 1
}
},
})
```

### getId

A builder function that returns a unique ID for each heading. Inside the argument you get access to the headings text content (for example you want to generate IDs based on the text content of the heading).

By default this is a function that uses the [uuid](https://www.npmjs.com/package/uuid) package to generate a unique ID.
Expand All @@ -96,23 +102,25 @@ Default: `() => uuid()`
// here we use an imaginary "slugify" function
// you should probably also add a unique identifier to the slug
TableOfContents.configure({
getId: (content) => slugify(content)
getId: (content) => slugify(content),
})
```

### scrollParent
The scroll parent you want to attach to. This is used to determine which heading currently is active or was already scrolled over. By default this is the window but you can pass any HTML element here.

Default: `window`
The scroll parent you want to attach to. This is used to determine which heading currently is active or was already scrolled over. By default this is a callback function that returns the window but you can pass a callback that returns any HTML element here.

Default: `() => window`

```js
// For example the editors DOM element itself is the scrolling element
TableOfContents.configure({
scrollParent: editor.view.dom
scrollParent: () => editor.view.dom,
})
```

### onUpdate

The most important option that you must set to use this extension. This is a callback function that gets called whenever the Table of Content updates. You get access to an array of heading data (see below) which you can use to render your own Table of Content.

To render the table of content you can render it by any means you want. You can use a framework like Vue, React or Svelte or you can use a simple templating engine like Handlebars or Pug. You can also use a simple `document.createElement` to render the table of content.
Expand Down Expand Up @@ -145,7 +153,7 @@ TableOfContents.configure({

tocElement.appendChild(anchorElement)
})
}
},
})
```

Expand All @@ -157,7 +165,7 @@ const [anchors, setAnchors] = useState([])
TableOfContents.configure({
onUpdate: (anchors) => {
setAnchors(anchors)
}
},
})
```

Expand All @@ -168,27 +176,30 @@ const anchors = ref([])
TableOfContents.configure({
onUpdate: (anchors) => {
anchors.value = anchors
}
},
})
```

## Storage

### content

The heading content of the current document

```js
editor.storage.tableOfContents.content
```

### anchors

An array of HTML nodes

```js
editor.storage.tableOfContents.anchors
```

### scrollHandler

The scrollHandler used by the scroll function. Should not be changed or edited but
could be used to manually bind this function somewhere else

Expand All @@ -197,6 +208,7 @@ editor.storage.tableOfContents.scrollHandler()
```

### scrollPosition

The current scrollPosition inside the scrollParent.

```js
Expand All @@ -223,4 +235,4 @@ The array returned by the storage or the `onUpdate` function includes objects st
}
```

This should give you enough flexibility to render your own table of content.
This should give you enough flexibility to render your own table of content.

0 comments on commit f649211

Please sign in to comment.