Homepage: http://github.com/alphapapa/org-make-toc
Author: Adam Porter
Updated:
Automatic tables of contents for Org files
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.
Installation
Install the packages `dash' and `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 go to it.
2. Press `C-c C-x p' (`org-set-property'), add a `TOC' property, and
set its value to `:include all'.
3. Run command `org-make-toc-insert' to insert the `:CONTENTS:' drawer,
which will contain the TOC entries.
4. 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.
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.
[example.org]
https://github.com/alphapapa/org-make-toc/blob/master/example.org
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)
└────