I'm unable to find the time to keep this repository well maintained, and up-to-date with Obsidian. Life gets in the way. This plugin should be forked/rebuilt by someone who is willing to find the time to build a plugin that the Obsidian community deserves.
An Obsidian plugin to generate Tables of Contents that stay up to date with your document outline. Heavily inspired from hipstersmoothie/obsidian-plugin-toc
This plugin attempts to parse your document headings and generate a markdown table of contents for them. There have been a handful of issues raised which are due to how people are using headings. Headings offer a lexical structure to a document, they are not intended to be used for style.
The following is an example of inconsistent heading depth. Instead of a level 4 heading it should be a level 3 heading.
## Level 2
#### Level 4The following is an example of consistent heading depth. After a level 2 heading the next level is 3
## Level 2
### Level 3👉 You can of course choose to structure your documents as you wish, but this plugin may not work effectively. I do attempt to make some exceptions but I will hide them behind settings to not interfere with peoples work flows, reduce stability, and to keep development time low. See Inconsistent Heading Depth
It's really simple to use, just add a code block to your document:
👉YAML does not support tabs, only use spaces (source)
Defaults
```toc
style: bullet | number | inline (default: bullet)
min_depth: number (default: 2)
max_depth: number (default: 6)
title: string (default: undefined)
allow_inconsistent_headings: boolean (default: false)
delimiter: string (default: |)
varied_style: boolean (default: false)
```Example
```toc
style: number
min_depth: 1
max_depth: 6
```You can specify the options on a case-by-case basis in your documents, or you can override the defaults in settings. If you have settings you always want to use, your usage just becomes:
```toc
```Inline styles render the highest level of heading such as H2 ## Heading 2, you can couple this with the delimiter option to generate a breadcrumbs like effect for your headings.
See Feature Request: Inline Links
Varied style allows for setting the topmost level of your headings, and the rest of the levels to the opposite style.
For example if you have varied_style set to true and your list style is bullet, the first level will be bullet and the subsequent headings will be number style.
Style: Bullet
Style: Number
See Feature Request: Mixed List Style
You can also add custom injection for compatibility with markdown readers such as Markor or Gitlab with the External Rendering Support setting. Such as:
[toc]/[TOC]- Or
[[_TOC_]]
This feature is to allow for consistency with another tool of your choice such as GitLab.
If you have another convention that is required for a markdown reader of your choosing. Create an issue with the name of the viewer and the convention that's used.
You can skip individual selection and support all renderers by checking "Support all external renderers" in settings.
! If you add a new line between each identifier, you will get a new table of contents for each
[/toc/]
{{toc}}
[[__TOC__]]
[toc]! If you add them all next to each other you will get a single block
[/toc/]
{{toc}}
[[__TOC__]]
[toc]You can insert a table of contents by using the command palette and selecting "Insert table of contents" and selecting the table of contents to insert
Insert command
Table of contents options. Note that you will only see:
- "Code Block" if you have no external renderers set in settings
- "Code Block" and a single external renderer if set in settings
- All possible options if you have "Support all external renderers" set in settings
Remember you can set a hotkey in Obsidian for this command for even faster access.
You can add a title to every injected table of contents by using the Title option in setttings or inline inside a codeblock for example:
```toc
title: "## Table of Contents"
```
⚠️ If you are adding Markdown syntax to your title in the code block, you must wrap it in double quotes.
As mentioned in the foreword above, this is not recommended, but there is a setting you can enable which will try and support you the best it can.
Given a heading structure such as:
## Level 2
#### Level 4
##### Level 5
## Level 2
### Level 3With this option enabled, it will produce the following table of contents:
⚠️ Notice that the Level 4 and Level 3 headings are at the same depth
yarn installTo start building the plugin with what mode enabled run the following command:
yarn devTo start a release build run the following command:
yarn release
git push --follow-tags origin main