Table of Contents
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-startmarkdown-toc-header-toc-titlemarkdown-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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent