org-make-toc

This package makes it easy to have one or more customizable tables of contents in Org files. They can be updated manually, or automatically when the file is saved. Links to headings are created compatible with GitHub’s Org renderer.

Contents

• Installation
• Usage
• Changelog
• Credits
• Development

Installation

MELPA

If you installed from MELPA, you’re done.

Manual

Install these required packages:

• dash
• s

  Then put this file in your load-path, and put this in your init file:

(require 'org-make-toc)

Usage

1. Make a heading in the Org file where you want the table of contents, and give it the Org property TOC with the value this.
2. Run the command org-make-toc to update all TOCs in the document, or org-make-toc-at-point to update the TOC for the entry at point.

Drawers

When using :TOC: this, the TOC replaces the entry’s contents. Alternatively, when a :CONTENTS: drawer is present in the entry, the TOC will be placed in the drawer, which co-exists with the entry’s text, like this:

* Heading
:PROPERTIES:
:TOC:      this
:END:

:CONTENTS:
-  [[#subheading][Subheading]]
:END:

This is non-TOC text that remains in the entry.

** Subheading

Advanced

A document may contain multiple tables of contents. Tables of contents can be customized by setting the TOC property of headings to these values:

• all: Include all headings in the file, except ignored headings.
• children: Include only child headings of this ToC.
• siblings: Include only sibling headings of this ToC.
• ignore: Omit a heading from the TOC.
• ignore-children or 0: Omit a heading’s child headings from the TOC.
• a number N: Include child headings up to N levels deep in the TOC.

Automatically update on save

To automatically update a file’s TOC when the file is saved, use the command add-file-local-variable to add org-make-toc to the Org file’s before-save-hook.

Or, you may activate it in all Org buffers like this:

(add-hook 'org-mode-hook #'org-make-toc-mode)

Example

See example.org for a comprehensive example of the features described above.

Changelog

0.4

Additions

• Omit invisible characters from link titles (e.g. Org markup characters like = and ~).
• Option org-make-toc-link-type-fn allows choosing GitHub-compatible or regular Org-style links.
• Command org-make-toc-at-point, which updates the TOC at the current entry.
• Optionally place TOC in a :CONTENTS: drawer which co-exists with entry content.

Changes

• Changed no-TOC-node-found error to a message, so e.g. when org-make-toc-mode is active in a buffer without a TOC, saving will not signal an error.

Fixes

• Remove excess indentation from TOC while preserving list structure.
• Don’t insert a blank line when TOC is empty.
• Autoload minor mode. (Thanks to Akira Komamura.)
• Filename prefix order in links. (Thanks to Daniel Kraus.)

0.3.1

Fixes

• Use cadr instead of second.

0.3

Additions

• Option org-make-toc-filename-prefix to add the filename before the anchor in links. This allows a ToC to refer to entries in another file by manually copying a ToC from one file into another. See issue 2. Thanks to Daniel Kraus.

Changes

• Minor refactoring.

0.2

Additions

• Multiple tables of contents are now supported in a single document.
• Entries’ TOC property can now also be set to the values all, children, and siblings, which allow tables of contents to be created for only parts of a document.
  • all includes all entries in a document, including other tables of contents, except ignored entries.
  • children includes only child entries, except ignored entries.
  • siblings includes only sibling entries, except ignored entries.
• The command org-make-toc-mode toggles org-make-toc on the before-save-hook in the current buffer. This may be added to the global org-mode-hook to activate it in every Org buffer.
• The examples.org file shows an example of all of the options used together in a complex, book-like document.

0.1

Initial release.

Credits

This package was inspired by Sergei Nosov’s toc-org package.

Development

Bug reports, feature requests, suggestions — oh my!

License

GPLv3