Github GitHub - ardumont/markdown-toc: Generate a TOC in markdown file
source link: https://github.com/ardumont/markdown-toc
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.
markdown-toc
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).
Create
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)
User toc manipulation
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)))
Update
To update the existing TOC, simply execute: M-x markdown-toc-refresh-toc
This will update the current TOC.
Create elsewhere
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.
Remove
To remove a TOC, execute M-x markdown-toc-delete-toc.
Customize
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))
Minor mode
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.
Install
emacs package repository
You need to add melpa or melpa-stable package repository before installing it.
Setup
melpa stable
(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.
melpa
(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.
Install
M-x package-install RET markdown-toc RET
emacs-lisp file
Retrieve the markdown-toc.el https://github.com/ardumont/markdown-toc/releases.
Then hit M-x package-install-file RET markdown-toc.el RET
Inspiration
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.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK