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)
  └────