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

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

A document may have any number of tables of contents (TOCs), each of which may list entries in a highly configurable way.

To make a basic TOC, follow these steps:

1. Choose a heading to contain a TOC and move the point to it.
2. Run command org-make-toc-insert, which inserts a :CONTENTS: drawer and sets TOC properties. Set the include property to all.
3. Run the command org-make-toc to update all TOCs in the document.

Use command org-make-toc-set to change TOC properties for the entry at point with completion.

Example

Here’s a simple document containing a simple TOC:

* Heading
:PROPERTIES:
:TOC:      :include all
:END:

This text appears before the TOC.

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

This text appears after it.

** Subheading

Advanced

The :TOC: property is a property list which may set these keys and values.

These keys accept one setting, like :include all:

• :include Which headings to include in the TOC.
  • all Include all headings in the document.
  • descendants Include the TOC’s descendant headings.
  • siblings Include the TOC’s sibling headings.
• :depth A number >= 0 indicating a depth relative to this heading. Descendant headings at or above this relative depth are included in TOCs that include this heading.

These keys accept either one setting or a list of settings, like :force depth or :force (depth ignore):

• :force Heading-local settings to override when generating the TOC at this heading.
  • depth Override :depth settings.
  • ignore Override :ignore settings.
• :ignore Which headings, relative to this heading, to exclude from TOCs.
  • descendants Exclude descendants of this heading.
  • siblings Exclude siblings of this heading.
  • this Exclude this heading (not its siblings or descendants).
• :local Heading-local settings to ignore when generating TOCs at higher levels.
  • depth Ignore :depth settings.

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

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)

Making links work in both Emacs/Org and on GitHub

Because of the way GitHub renders Org documents and links, it’s not possible to make links which work in both Org itself and the GitHub-rendered HTML unless headings have CUSTOM_ID properties. If the option org-make-toc-insert-custom-ids is enabled, this package will automatically add them as needed.

Changelog

0.6

Compatibility

• Org 9.3 or later is now required.

Additions

• Option org-make-toc-insert-custom-ids automatically adds CUSTOM_ID properties to headings so links can work on both GitHub-rendered Org files and in Emacs. (Thanks to Fox Kiester.)

Fixes

• Tolerate whitespace before drawer opening/closing lines. (#15, #17. Thanks to Nicholas Vollmer.)
• Link-type function called with position as argument. (Fixes occasional bugs with heading IDs.)
• Mode org-make-toc-mode now adds to the before-save-hook in the local buffer rather than globally. (#24. Thanks to Akira Komamura.)

0.5

This version is a major rewrite that requires reconfiguring existing TOCs. Please see the usage instructions anew. Users who don’t want to convert to 0.5-style TOCs may continue using version 0.4.

Changes

• TOCs are now contained in :CONTENTS: drawers, which allows them to co-exist with entry content and be placed flexibly.
• The :TOC: property, which contains all TOC settings, is now formatted like a Lisp property list, and the settings have been redesigned to be clearer, more concise, more flexible, and more powerful.

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