Automatic Table Of Contents

An Obsidian plugin to create a table of contents in a note, that updates itself when the note changes

• Installation
  • From Obsidian (easiest)
  • From git
  • From source
• Usage and options
  • Available options
• Limitations and known bugs
• Publish a new version
• Changelog
• License
• Contributing

Installation

From Obsidian (easiest)

Install the plugin from the Community plugins section in the app settings.

From git

Clone the plugin in your .obsidian/plugins directory:

cd /path/to/your/vault/.obsidian/plugins
git clone [email protected]:johansatge/obsidian-automatic-table-of-contents.git

From source

Download the latest release and unzip it in the .obsidian/plugins/automatic-table-of-contents directory.

Usage and options

Insert a codeblock with the table-of-contents (or its short version toc) syntax.

```table-of-contents
option1: value1
option2: value2
```

Alternatively, two commands are available in the command palette:

• Insert table of contents
• Insert table of contents (with available options)

Available options

Most options can have a default value configured in the plugin settings (Settings → Community plugins → Automatic Table of Contents). These defaults will be used for all tables of contents in your vault, unless overridden in individual codeblocks.

The following options are available:

Limitations and known bugs

• The table of contents may not be generated correctly if the document doesn't implement a correct titles hierarchy (level 1 title then level 3 without a level 2 in between, for instance)
• HTML & markdown that may be in the document headings are stripped when includeLinks: true (see #24 & #27)
• LaTeX equations are not rendered correctly when includeLinks: true (see #13)
• Links might not behave correctly if the same title is present several times on the page (see #57)
• Generated table of contents is not foldable (see #23)
• The table of contents is based on a codeblock so it can be updated; it doesn't generate real Markdown in the document (see #10) so it won't be visible when exporting, or on Obsidian Publish (see #31) and links might not work in PDFs (see #12)

Publish a new version

• Build the plugin with npm run build (--watch during dev)
• Push a commit with the new version number as message with:
  • The relevant changelog in README.md
  • The new version number in manifest.json
  • The updated main.js (with npm run build)
• Tag the commit with the version number
• Publish a new GitHub release with:
  • The version number as title
  • The changelog from README.md as description
  • main.js and manifest.json from as attachments
  • Set as the latest release checked

Changelog

This project uses semver.

License

This project is released under the MIT License.

Contributing

Bug reports and feature requests are welcome! More details in the contribution guidelines.