/org-make-toc

Automatic tables of contents for Org files

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

org-make-toc

https://melpa.org/packages/org-make-toc-badge.svg https://stable.melpa.org/packages/org-make-toc-badge.svg

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

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.

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-pre

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.

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