About
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
Installation
via package.el
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-mode)
(warn "toc-org not found"))Manual
- 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-mode) (warn "toc-org not found"))
Use
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 org-set-tags-command (C-c C-q).
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 _.
Follow links
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 org-link-translation-function
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.
Exclude headings
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_2:,
:noexport_3:, etc. for children of deeper levels). Note, though, :noexport:
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. #+BEGIN_QUOTE / #+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 T:
(add-to-list 'org-tag-alist '("TOC" . ?T))Now C-c C-q T RET and you are done putting the :TOC: entry.
Different href styles
Currently, only 2 href styles are supported: gh and org. You can easily
define your own styles. If you use the tag :TOC_2_STYLE: (STYLE being a
style name), then the package will look for a function named
toc-org-hrefify-STYLE.
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.
E.g. for 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))Example
* 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