README.org

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

• About
• Installation
  • via package.el
  • Manual
• Use
  • Follow links
  • Exclude headings
  • Shortcut for TOC tag
• Different href styles
• Example

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-enable)
  (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-enable)
    (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.

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