43

GitHub - snosov1/toc-org: toc-org is an Emacs utility to have an up-to-date tabl...

 6 years ago
source link: https://github.com/snosov1/toc-org
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

README.org

https://api.travis-ci.org/snosov1/toc-org.svg?branch=master

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

http://melpa.org/packages/toc-org-badge.svg

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

report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK