toc-org helps you to have an up-to-date table of contents in org files without exporting (useful primarily for readme files on GitHub).
It is similar to the markdown-toc package, but works for org files.
NOTE: Previous name of the package is
org-toc. It was changed because of a
name conflict with one of the org contrib modules.
Table of Contents
This is the simplest method if you have the package.el module (built-in since
Emacs 24.1) you can simply use
M-x package-install after setting up the MELPA
repository and then put the following snippet in your ~/.emacs file
(if (require 'toc-org nil t) (add-hook 'org-mode-hook 'toc-org-enable) (warn "toc-org not found"))
- Create folder ~/.emacs.d if you don’t have it
- Go to it and clone toc-org there
git clone https://github.com/snosov1/toc-org.git
- Put this in your ~/.emacs file
(add-to-list 'load-path "~/.emacs.d/toc-org") (if (require 'toc-org nil t) (add-hook 'org-mode-hook 'toc-org-enable) (warn "toc-org not found"))
After the installation, every time you’ll be saving an org file, the first
headline with a
:TOC: tag will be updated with the current table of contents.
To add a TOC tag, you can use the command
In addition to the simple :TOC: tag, you can also use the following tag formats:
- :TOC_2: - sets the max depth of the headlines in the table of contents to 2 (the default)
- :TOC_2_gh: - sets the max depth as in above and also uses the GitHub-style hrefs in the table of contents (this style is default). The other supported href style is ‘org’, which is the default org style.
You can also use
@ as separator, instead of
If you call
M-x org-open-at-point (
C-c C-o) when you’re at a TOC entry, the
point will jump to the corresponding heading.
Notice, that this functionality exploits the
variable. So, it won’t work if you use this variable for other purposes (i.e. it
is not nil).
You can manually disable this functionality by setting
toc-org-enable-links-opening to nil.
Headings tagged with
:noexport: will be excluded from the TOC. If you want to
preserve the heading, but strip its children (for changelog entries, for
example), you can tag it
:noexport_1: (by analogy, you can use
:noexport_3:, etc. for children of deeper levels). Note, though,
has a similar meaning in
org-mode, which I hope is a Good Thing (tm). However,
:noexport_1: and friends won’t be recognized by
org-mode as anything
special. Look at
org-export-exclude-tags variable for more details.
Quote table of contents
For presentation purposes, you might want to put the table of contents in a
quote block (i.e.
#+END_QUOTE). In that case, GitHub, for
example, will add a vertical line to the left of the TOC that makes it distinct
from the main text. To do this, just add a
:QUOTE: tag to the TOC heading.
Shortcut for TOC tag
In your emacs’ setup, you can bind a tag
:TOC: to a binding
(add-to-list 'org-tag-alist '("TOC" . ?T))
C-c C-q T RET and you are done putting the
Different href styles
Currently, only 2 href styles are supported:
org. You can easily
define your own styles. If you use the tag
STYLE being a
style name), then the package will look for a function named
It should accept a heading string and a hash table of previously generated
hrefs. The table can be used to maintain href uniqueness (see
toc-org-hrefify-gh, for example). Return value should be a href corresponding
to that heading.
org style it makes links to be the same as their visible text:
(defun toc-org-hrefify-org (str &optional hash) "Given a heading, transform it into a href using the org-mode rules." (toc-org-format-visible-link str))
* About * Table of Contents :TOC: - [[#about][About]] - [[#installation][Installation]] - [[#via-packageel][via package.el]] - [[#manual][Manual]] - [[#use][Use]] - [[#example][Example]] * Installation ** via package.el ** Manual * Use * Example