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

关于

=toc-org= 可以帮助你在不导出的情况下，在org文件中保持一个最新的目录（主要用于GitHub上的readme文件）。

它类似于 [[https://github.com/ardumont/markdown-toc][markdown-toc]] 包，但适用于org文件。最近，=toc-org= 实际上也可以在 [[#markdown-support][markdown]] 中使用了！

注意： 该包的之前名称是 =org-toc=。由于与一个org contrib模块名称冲突，所以改名了。

目录 :TOC:QUOTE: #+BEGIN_QUOTE

[[#about][关于]]
[[#installation][安装]]
- [[#via-packageel][通过package.el]]
- [[#manual][手动]]
[[#use][使用]]
- [[#follow-links][跟随链接]]
- [[#exclude-headings][排除标题]]
- [[#quote-table-of-contents][引用目录]]
- [[#shortcut-for-toc-tag][TOC标签的快捷方式]]
[[#markdown-support][Markdown支持]]
[[#different-href-styles][不同的href样式]]
[[#example][示例]] #+END_QUOTE

安装 ** 通过package.el

[[https://elpa.nongnu.org/nongnu/toc-org.html][https://elpa.nongnu.org/nongnu/toc-org.svg]] [[http://melpa.org/#/toc-org][file:http://melpa.org/packages/toc-org-badge.svg]]

如果你有package.el模块（Emacs 24.1以后内置），这是最简单的方法。在设置好[[http://melpa.org/#/getting-started][MELPA]]仓库后，你可以简单地使用 =M-x package-install=，然后在你的~/.emacs文件中添加以下代码片段

#+BEGIN_SRC elisp (if (require 'toc-org nil t) (progn (add-hook 'org-mode-hook 'toc-org-mode)

    ;; 在markdown中也启用
    (add-hook 'markdown-mode-hook 'toc-org-mode)
    (define-key markdown-mode-map (kbd "\C-c\C-o") 'toc-org-markdown-follow-thing-at-point))
(warn "toc-org not found"))

#+END_SRC

** 手动

如果没有的话，创建~/.emacs.d文件夹
进入该文件夹并克隆toc-org #+BEGIN_SRC sh git clone https://github.com/snosov1/toc-org.git #+END_SRC

在你的~/.emacs文件中添加以下内容 #+BEGIN_SRC elisp (if (require 'toc-org nil t) (progn (add-hook 'org-mode-hook 'toc-org-mode)

    ;; 在markdown中也启用
    (add-hook 'markdown-mode-hook 'toc-org-mode)
    (define-key markdown-mode-map (kbd "\C-c\C-o") 'toc-org-markdown-follow-thing-at-point))
(warn "toc-org not found"))

#+END_SRC

使用

安装后，每次保存org文件时，带有 =:TOC:= 标签的第一个标题将会用当前的目录更新。

要添加TOC标签，你可以使用 =org-set-tags-command= 命令（=C-c C-q=）。

除了简单的:TOC:标签，你还可以使用以下标签格式：

:TOC_2: - 将目录中标题的最大深度设置为2（默认值）
:TOC_2_gh: - 设置最大深度如上，并在目录中使用GitHub风格的hrefs（这是默认风格）。另一种支持的href风格是'org'，这是默认的org风格。

你也可以使用 =@= 作为分隔符，而不是 =_=。

可以通过 =toc-org-max-depth= 和 =toc-org-hrefify-default= 变量设置最大深度和hrefify函数的默认值。但请注意，如果你在org文件之外进行这些设置，当你与他人协作同一文件时可能会遇到冲突，因为你们的默认配置可能不同。

** 跟随链接

如果你在TOC条目上调用 =M-x org-open-at-point=（=C-c C-o=），光标将跳转到相应的标题。

注意，这个功能利用了 =org-link-translation-function= 变量。因此，如果你将这个变量用于其他目的（即它不为nil），这个功能将不起作用。

你可以通过将 =toc-org-enable-links-opening= 设置为nil来手动禁用此功能。

** 排除标题带有 =:noexport:= 标签的标题将被排除在目录之外。如果你想保留标题，但去掉其子项（例如用于变更日志条目），可以使用 =:noexport_1:= 标签（类似地，你可以使用 =:noexport_2:=、=:noexport_3:= 等标签来处理更深层级的子项）。需要注意的是，=:noexport:= 在 =org-mode= 中有类似的含义，我希望这是一件好事（tm）。然而，=:noexport_1:= 及其相关标签不会被 =org-mode= 识别为特殊标记。更多详情请参阅 =org-export-exclude-tags= 变量。

** 引用目录

出于展示目的，你可能想将目录放在引用块中（即 =#+BEGIN_QUOTE= / =#+END_QUOTE=）。在这种情况下，例如 GitHub 会在目录左侧添加一条垂直线，使其与正文区分开来。要做到这一点，只需在目录标题上添加 =:QUOTE:= 标签。

** 目录标签快捷方式

在你的 Emacs 设置中，你可以将标签 =:TOC:= 绑定到快捷键 =T=：

#+BEGIN_SRC emacs-lisp (add-to-list 'org-tag-alist '("TOC" . ?T)) #+END_SRC

现在只需按 =C-c C-q T RET=，你就完成了 =:TOC:= 条目的添加。

Markdown 支持

你也可以在 Markdown 文件中启用此模式，并获得几乎相同的功能。该包会：

寻找 '#' 而不是 '*' 作为标题标记。
期望 =:TOC:= 标签以注释形式出现，如 ==
根据 Markdown 语法格式化链接和引用块

示例：

#+BEGIN_SRC markdown

关于

目录

关于
安装
- 通过 package.el
- 手动安装
使用
示例

安装

通过 package.el

手动安装

使用

示例

#+END_SRC

不同的 href 样式

目前只支持两种 href 样式：=gh= 和 =org=。你可以轻松定义自己的样式。如果你使用标签 =:TOC_2_STYLE:=（STYLE 为样式名称），那么该包将寻找名为 =toc-org-hrefify-STYLE= 的函数。

该函数应接受一个标题字符串和一个先前生成的 href 哈希表。该表可用于维护 href 的唯一性（例如，参见 =toc-org-hrefify-gh=）。返回值应为对应该标题的 href。

例如，对于 =org= 样式，它使链接与其可见文本相同：

#+BEGIN_SRC emacs-lisp (defun toc-org-hrefify-org (str &optional hash) "给定一个标题，使用 org-mode 规则将其转换为 href。" (toc-org-format-visible-link str)) #+END_SRC

示例 #+BEGIN_SRC org
- 关于
- 目录 :TOC:
- [[#关于][关于]]
- [[#安装][安装]]
  - [[#通过-packageel][通过 package.el]]
  - [[#手动安装][手动安装]]
- [[#使用][使用]]
- [[#示例][示例]]
- 安装 ** 通过 package.el ** 手动安装
- 使用
- 示例 #+END_SRC