Insta TOC Plugin

A plugin to dyamically generate and maintain a table of contents for you in real time.

Table of Contents

• Demonstration
• Features: Insta TOC vs Other ToC Plugins
• Usage
• Installation
  • Obsidian
  • BRAT
  • npm
  • Manual
• Contributing
• Road Map

Demonstration

Features: Insta TOC vs Other ToC Plugins

There are various other ToC plugins for Obsidian, however, they come with certain limitations which this plugin aims to mitigate and improve upon which includes:

Seamless Integration & Dynamic Generation

• Just insert the code block and start typing. There's nothing more to it.
• Other ToC plugins generate the ToC via command activation.
• This plugin is designed for performance and simplicity for maximum convenience and organization.

Omit Specific Headings

• Exclude any heading you want from the ToC by simply adding <!-- omit --> to the end of the heading.
• Alternatively, utilize the local settings to omit specific headings.

HTML & Special Symbols

• Feel free to include HTML or any kind of special symbols within headings. This plugin will handle these cases elegantly.
• You can additionally specify which characters should be escaped within the local settings.

Heading Hierarchy Handling

• Include any type of heading hierarchy you want. Your heading structure doesn't have to be any certain way.
• Other plugins will prohibit the ToC insertion if the heading hierachy is not in a particular optimal format.

Markdown Links & Wiki-Links

• This plugin will handle multiple of both markdown links ([Title]\(https://link)) and wiki-links ([[file-name.md]]) within headings.

Settings

• Bullet Style - Select your preferred list-bullet style within the settings tab.
• Update Delay - Configure the delay between ToC updates.
• Exclusions - You will have multiple custimization choices pertaining to exlcuding specific heading text, individual characters, and heading levels.
• Indentation Width - Determine your preferred amount of indentation spacing.
• Local File Settings

Usage

General Usage

• Insert the insta-toc code block:

  ```insta-toc
  ```

Omit Specific Headings

• If you want to omit a specific heading from the ToC, simply add <!-- omit --> to the end of the heading.

  # Heading 1 <!-- omit -->
  

• Alternatively, utilize the local settings:

  ---
  omit: [
    "Heading 1",
    "Heading 2"
  ]
  ---

  ↕️    ↕️    ↕️    ↕️

  ---
  omit:
    - Heading 1
    - Heading 2
  ---

---

Local ToC Settings Guide

⚠️ FORMAT CAUTION ⚠️

The local settings use YAML formatting, which is a format that is very particular about perfect spacing. I'll be implementing auto-correction logic soon to account for this, but for the time being ensure that you are only indenting with 2 spaces, otherwise you will get errors.

• Type Guide:

  ---
  title:
    name: [string: any]
      - The title of the ToC.
    level: [number: 1 | 2 | 3 | 4 | 5 | 6]
      - The heading level of the title.
    center: [boolean: true | false]
      - Optionally center position of the title.
  exclude: [string: any | RegExp: /.../]
    - Exclude specific headings based on a string of characters (e.g., ",._-+=") or a regular expression (e.g., /[^a-zA-Z0-9]/).
    - NOTE: Currently, this will include global excluded characters as well.
  style:
    listType: [string: "number" | "dash"]
      - The type of list-bullet style.
  omit: [string[]: any[]]
    - Omit specific headings from the ToC.
  levels:
    min: [number: 1 | 2 | 3 | 4 | 5 | 6]
      - The minimum heading level to include in the ToC.
    max: [number: 1 | 2 | 3 | 4 | 5 | 6]
      - The maximum heading level to include in the ToC.
  ---

• Example 1:

  ---
  title:
    name: "Table of Contents"
    level: 2
    center: false
  exclude: ",._-+"
  style:
    listType: "dash"
  omit: [
    "Heading 1",
    "Heading 2"
  ]
  levels:
    min: 1
    max: 3
  ---

• Example 2:

  ---
  title:
    name: "Table of Contents"
    level: 1
    center: true
  exclude: /[^a-zA-Z0-9]/
  style:
    listType: number
  omit:
    - Heading 3
    - Heading 4
  levels:
    min: 2
    max: 6
  ---

Installation

Obsidian

1. Open Obsidian and press CMD+,.
2. Navigate to the Community plugins tab and click the Browse button.
3. Navigate to the search bar and type Insta TOC
4. Click the install button.

BRAT

1. Install BRAT community plugin.
2. Open Obsidian and press CMD+SHIFT+P.
3. Type >BRAT: Plugins: Add a beta plugin for testing and select the option.
4. Insert https://github.com/iLiftALot/insta-toc and submit.

npm

npm install insta-toc

Manual

1. Download the latest release.
2. Extract the insta-toc folder from the zip to your vault's plugins folder: /path/to/<vault>/.obsidian/plugins/. Note: On some machines the .obsidian folder may be hidden. On MacOS you should be able to press CMD+SHIFT+. to show the folder in Finder.
3. Reload Obsidian.

Contributing

• Report a Bug
• Suggest a Feature
• Suggest Documentation
• Submit a Pull Request

---

Road Map

• Handle various heading formats
• Markdown Links
• Wiki-Links
• HTML
• Tags
• Special Characters
• ...
• Configure Settings Tab
• Indentation
• Bullet types
• Number
• Dash
• ...
• ToC Update Delay
• Special Character Specificatio
• Preferences for customized TOC appearance
• ...
• Improve ToC Interaction/Interface
• Add folding capabilities
• Add ability to exclude specific headings
• Add local setting capabilities
• ...
• Configure specific formatting for various exporting circumstances
• PDF
• HTML
• Markdown
• ...