#+PROPERTY: LOGGING nil

#+BEGIN_HTML #+END_HTML

• org-make-toc :PROPERTIES: :TOC: ignore :END:

[[https://melpa.org/#/org-make-toc][file:https://melpa.org/packages/org-make-toc-badge.svg]] [[https://stable.melpa.org/#/org-make-toc][file: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 :noexport: :PROPERTIES: :TOC: :include siblings :depth 0 :ignore this :END: :CONTENTS:

• [[#installation][Installation]]
• [[#usage][Usage]]
• [[#changelog][Changelog]] :END:

• 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:

#+BEGIN_SRC elisp (require 'org-make-toc) #+END_SRC

• 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:

#+BEGIN_SRC org ,* Heading :PROPERTIES: :TOC: :include all :END:

This text appears before the TOC.

:CONTENTS:

• [[#heading][Heading]]
  • [[#subheading][Subheading]] :END:

This text appears after it.

,** Subheading #+END_SRC

** 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 [[https://github.com/alphapapa/org-make-toc/blob/master/example.org][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:

#+BEGIN_SRC elisp (add-hook 'org-mode-hook #'org-make-toc-mode) #+END_SRC

** Known Issues

Unfortunately, due to 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. See [[https://github.com/wallyqs/org-ruby/issues/11][org-ruby issue #11]]. =toc-org= provides a workaround using =org-link-translation-function= to change how Org handles =#heading=-style links, but, of course, that breaks compatibility with such links that aren't intended to be rendered by GitHub, so it must be manually enabled in each document as appropriate.

• Changelog :PROPERTIES: :TOC: :depth 0 :END:

** 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 [[https://github.com/akirak][Akira Komamura]].)
• Filename prefix order in links. (Thanks to [[https://github.com/dakra][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 [[https://github.com/alphapapa/org-make-toc/pull/2][issue 2]]. Thanks to [[https://github.com/dakra][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 :PROPERTIES: :TOC: :ignore this :END:

This package was inspired by Sergei Nosov's [[https://github.com/snosov1/toc-org][toc-org]] package.

• Development :PROPERTIES: :TOC: :ignore this :END:

Bug reports, feature requests, suggestions — /oh my/!

• License :PROPERTIES: :TOC: :ignore this :END:

GPLv3

Local Variables:

eval: (require 'org-make-toc)

before-save-hook: org-make-toc

org-export-with-properties: ()

org-export-with-title: t

End: