Table of Contents

• Use
  • Create
  • User toc manipulation
  • Update
  • Create elsewhere
  • Remove
  • Customize
  • Minor mode
• Install
  • emacs package repository
    • Setup
      • melpa stable
      • melpa
    • Install
  • emacs-lisp file
• Inspiration

A simple mode to create TOC in a well-formed markdown file.

Note that the TOC is well-formed if the markdown is (cf. #15).

Inside a markdown file, the first time, place yourself where you want to insert the TOC:

M-x markdown-toc-generate-toc

This will compute the TOC and insert it at current position.

You can also execute: M-x markdown-toc-generate-or-refresh-toc to either gnerate a TOC when none exists or refresh the currently existing one.

Here is one possible output:

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->**Table of Contents**-[Use](#use)-[Create](#create)-[Update](#update)-[Create elsewhere](#create-elsewhere)-[Install](#install)-[emacs package repository](#emacs-package-repository) - [Setup](#setup) - [melpa stable](#melpa-stable) - [melpa](#melpa) - [marmalade](#marmalade) - [Install](#install)-[emacs-lisp file](#emacs-lisp-file)-[Inspiration](#inspiration)

If the user would want to enhance the generated toc, (s)he could use the following function markdown-toc-user-toc-structure-manipulation-fn:

It expects as argument the toc-structure markdown-toc uses to generate the toc. The remaining code expects a similar structure.

Example:

'((0."some markdown page title") (0."main title") (1."Sources") (2."Marmalade (recommended)") (2."Melpa-stable") (2."Melpa (~snapshot)") (1."Install") (2."Load org-trello") (2."Alternative") (3."Git") (3."Tar") (0."another title") (1."with") (1."some") (1."heading"))

So for example, as asked in #16, one could drop the first element:

(custom-set-variables '(markdown-toc-user-toc-structure-manipulation-fn 'cdr))

Or drop all h1 titles... or whatever:

(require'dash) (custom-set-variables '(markdown-toc-user-toc-structure-manipulation-fn (lambda (toc-structure) (-filter (lambda (l) (let ((index (car l))) (<=1 index))) toc-structure)))

To update the existing TOC, simply execute: M-x markdown-toc-refresh-toc

This will update the current TOC.

To create another updated TOC elsewhere, execute M-x markdown-toc-generate-toc again, this will remove the old TOC and insert the updated one from where you stand.

To remove a TOC, execute M-x markdown-toc-delete-toc.

Currently, you can customize the following:

• markdown-toc-header-toc-start
• markdown-toc-header-toc-title
• markdown-toc-header-toc-end
• markdown-toc-indentation-space

Customize them as following format:

(custom-set-variables '(markdown-toc-header-toc-start "<!-- customized start-->") '(markdown-toc-header-toc-title "**customized title**") '(markdown-toc-header-toc-end "<!-- customized end -->") '(markdown-toc-indentation-space 4))

markdown-toc-mode provides a minor mode with the following default binding:

(setq markdown-toc-mode-map (let ((map (make-sparse-keymap))) (define-key map (kbd "C-c m .") 'markdown-toc-follow-link-at-point) (define-key map (kbd "C-c m t") 'markdown-toc-generate-or-refresh-toc) (define-key map (kbd "C-c m d") 'markdown-toc-delete-toc) (define-key map (kbd "C-c m v") 'markdown-toc-version) map)) 

To (de)activate this in an org file: /M-x markdown-toc-mode/

You can also use emacs to setup your own bindings.

You need to add melpa or melpa-stable package repository before installing it.

(require'package) (add-to-list 'package-archives '("melpa-stable"."http://melpa-stable.milkbox.net/packages/")) (package-initialize)

Then hit M-x eval-buffer to evaluate the buffer's contents.

(require'package) (add-to-list 'package-archives '("melpa"."http://melpa.milkbox.net/packages/")) (package-initialize)

Then hit M-x eval-buffer to evaluate the buffer's contents.

M-x package-install RET markdown-toc RET

Retrieve the markdown-toc.el https://github.com/ardumont/markdown-toc/releases.

Then hit M-x package-install-file RET markdown-toc.el RET

https://github.com/thlorenz/doctoc

The problem I had with doctoc is the installation process. I do not want to install the node tools just for this.