├── .mds-list ├── .gitignore ├── sync-en.sh ├── readme.md └── en.md /.mds-list: -------------------------------------------------------------------------------- 1 | ./source/README.md -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .DS_Store 3 | fork 4 | source 5 | hub-create.sh -------------------------------------------------------------------------------- /sync-en.sh: -------------------------------------------------------------------------------- 1 | cat './.mds-list' | while read line 2 | do 3 | testseq="zh.md" 4 | if [[ $line =~ $testseq || "$line" == "" ]]; then 5 | echo "skip $line" 6 | else 7 | lowline=`echo "$line" | awk '{print tolower($0)}'` 8 | # lowwer string 9 | zh=${line//source\//} 10 | dir=$(dirname $zh) 11 | 12 | source_readme="./source/readme.md" 13 | if [[ $lowline == $source_readme ]];then 14 | # source/[readme|REAMDE].md => en.md 15 | filename="en.md" 16 | else 17 | # source/other.md => ./other.md 18 | filename=$(basename $zh) 19 | fi 20 | echo "$line >> $dir/$filename" 21 | mkdir -p $dir && cp $line "$_/$filename" 22 | fi 23 | done -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # thlorenz/doctoc [![translate-svg]][translate-list] 2 | 3 | 4 | 5 | [explain]: http://llever.com/explain.svg 6 | [source]: https://github.com/chinanf-boy/Source-Explain 7 | [translate-svg]: http://llever.com/translate.svg 8 | [translate-list]: https://github.com/chinanf-boy/chinese-translate-list 9 | 10 | 「 生成，markdown 文件(`*.md`)的超链接目录 」 11 | 12 | [中文](./readme.md) | [english](https://github.com/thlorenz/doctoc) 13 | 14 | --- 15 | 16 | ## 校对 ✅ 17 | 18 | 19 | 20 | 21 | 22 | 翻译的原文 | 与日期 | 最新更新 | 更多 23 | ---|---|---|--- 24 | [commit] | ⏰ 2018-11-21 | ![last] | [中文翻译][translate-list] 25 | 26 | [last]: https://img.shields.io/github/last-commit/thlorenz/doctoc.svg 27 | [commit]: https://github.com/thlorenz/doctoc/tree/164f78e6452413a9717f58df8cf9dcb200b6c0f7 28 | 29 | 30 | 31 | ### 贡献 32 | 33 | 欢迎 👏 勘误/校对/更新贡献 😊 [具体贡献请看](https://github.com/chinanf-boy/chinese-translate-list#贡献) 34 | 35 | ## 生活 36 | 37 | [If help, **buy** me coffee —— 营养跟不上了，给我来瓶营养快线吧! 💰](https://github.com/chinanf-boy/live-need-money) 38 | 39 | --- 40 | 41 | # DocToc [![build status](https://secure.travis-ci.org/thlorenz/doctoc.svg)](http://travis-ci.org/thlorenz/doctoc) 42 | 43 | become a patron 44 | 45 | 生成，markdown 文件(`*.md`)的超链接目录 46 | 47 | 48 | 49 | 50 | **Contents** 51 | 52 | - [安装](#%E5%AE%89%E8%A3%85) 53 | - [用法](#%E7%94%A8%E6%B3%95) 54 | - [将 TOC 添加到目录和子目录中的所有文件](#%E5%B0%86-toc-%E6%B7%BB%E5%8A%A0%E5%88%B0%E7%9B%AE%E5%BD%95%E5%92%8C%E5%AD%90%E7%9B%AE%E5%BD%95%E4%B8%AD%E7%9A%84%E6%89%80%E6%9C%89%E6%96%87%E4%BB%B6) 55 | - [毫不费力地更新现有的 Doctoc TOCs](#%E6%AF%AB%E4%B8%8D%E8%B4%B9%E5%8A%9B%E5%9C%B0%E6%9B%B4%E6%96%B0%E7%8E%B0%E6%9C%89%E7%9A%84-doctoc-tocs) 56 | - [将 TOC 添加到单个文件中](#%E5%B0%86-toc-%E6%B7%BB%E5%8A%A0%E5%88%B0%E5%8D%95%E4%B8%AA%E6%96%87%E4%BB%B6%E4%B8%AD) 57 | - [使用 Doctoc 生成与其他站点兼容的超链接](#%E4%BD%BF%E7%94%A8-doctoc-%E7%94%9F%E6%88%90%E4%B8%8E%E5%85%B6%E4%BB%96%E7%AB%99%E7%82%B9%E5%85%BC%E5%AE%B9%E7%9A%84%E8%B6%85%E9%93%BE%E6%8E%A5) 58 | - [指定 TOC 的位置](#%E6%8C%87%E5%AE%9A-toc-%E7%9A%84%E4%BD%8D%E7%BD%AE) 59 | - [指定自定义 TOC 标题](#%E6%8C%87%E5%AE%9A%E8%87%AA%E5%AE%9A%E4%B9%89-toc-%E6%A0%87%E9%A2%98) 60 | - [指定 TOC 条目的最大 heading 级别](#%E6%8C%87%E5%AE%9A-toc-%E6%9D%A1%E7%9B%AE%E7%9A%84%E6%9C%80%E5%A4%A7-heading-%E7%BA%A7%E5%88%AB) 61 | - [打印到标准输出](#%E6%89%93%E5%8D%B0%E5%88%B0%E6%A0%87%E5%87%86%E8%BE%93%E5%87%BA) 62 | - [作为一个`git`钩子来使用](#%E4%BD%9C%E4%B8%BA%E4%B8%80%E4%B8%AAgit%E9%92%A9%E5%AD%90%E6%9D%A5%E4%BD%BF%E7%94%A8) 63 | 64 | 65 | 66 | ## 安装 67 | 68 | ``` 69 | npm install -g doctoc 70 | ``` 71 | 72 | ## 用法 73 | 74 | 在最简单的用法中，一个或多个文件，或文件夹使用`doctoc`命令。这会更新每个指定(md)文件的 TOC(超链接目录)。下面是一些例子. 75 | 76 | ### 将 TOC 添加到目录和子目录中的所有文件 77 | 78 | 进入目录: 79 | 80 | ``` 81 | doctoc . 82 | ``` 83 | 84 | 这将用 md 解析器，生成标点(`#`)超链接的目录表，更新当前目录及其所有子目录中的所有 md 文件。Doctoc 默认使用 Github 解析器,但可以[可以指定其他模式](#using-doctoc-to-generate-links-compatible-with-other-sites). 85 | 86 | ### 毫不费力地更新现有的 Doctoc TOCs 87 | 88 | 如果您已经通过 doctoc 插入了 TOC 注释，那么它将通过运行命令(而不是插入重复的 toc)自动更新。Doctoc 通过 89 | 90 | - ``和 91 | - ``注释 92 | 93 | 定位 TOC，因此您还可以将生成的 TOC 移动到文档的任何其他部分。 94 | 95 | ### 将 TOC 添加到单个文件中 96 | 97 | 如果希望只转换特定的文件,请执行: 98 | 99 | ``` 100 | doctoc /path/to/file [...] 101 | ``` 102 | 103 | #### 实例 104 | 105 | ``` 106 | doctoc README.md 107 | 108 | doctoc CONTRIBUTING.md LICENSE.md 109 | ``` 110 | 111 | 你可以使用这个特性来做更复杂的事情.例如,如果你安装[ack][ack],您可以添加``到特定文件， 然后使用 112 | 113 | ``` 114 | ack -L 'Doctoc SKIP' | xargs doctoc 115 | ``` 116 | 117 | 这命令只会重新编译那些没有``的文件. 118 | 119 | ### 使用 Doctoc 生成与其他站点兼容的超链接 120 | 121 | 为了添加，兼容的超链接目录表,可添加其他站点的适当参数: 122 | 123 | 可用模式是: 124 | 125 | ``` 126 | --bitbucket bitbucket.org 127 | --nodejs nodejs.org 128 | --github github.com 129 | --gitlab gitlab.com 130 | --ghost ghost.org 131 | ``` 132 | 133 | #### 例子 134 | 135 | ``` 136 | doctoc README.md --bitbucket 137 | ``` 138 | 139 | ### 指定 TOC 的位置 140 | 141 | 默认情况下,Doctoc 将 TOC 置于文件的顶部。可用以下格式放置在别处: 142 | 143 | ``` 144 | 145 | 146 | ``` 147 | 148 | 将此代码直接放在 `.md`文件中.例如: 149 | 150 | ``` 151 | // my_new_post.md 152 | Here we are, introducing the post. It's going to be great! 153 | But first: a TOC for easy reference. 154 | 155 | 156 | 157 | 158 | # Section One 159 | 160 | Here we'll discuss... 161 | ``` 162 | 163 | 运行 Doctoc 将在注释之间的位置插入 TOC. 164 | 165 | ### 指定自定义 TOC 标题 166 | 167 | 使用`--title`选项指定一个(markdown 格式的)自定义 TOC 标题;`doctoc --title '**Contents**' .` 。从此,你可以简单`doctoc `，就让 Doctoc 保留您指定的标题。(正如这个 readme 文件) 168 | 169 | 或者,你通过使用`--notitle`选项，用换行符将标题省略。简单地从 TOC 中删除标题. 170 | 171 | ### 指定 TOC 条目的最大 heading 级别 172 | 173 | > 如 `#` == **1**, `##` == **2** ... 174 | 175 | 使用`--maxlevel`将 TOC 项 限制为指定级别; 176 | 177 | - `doctoc --maxlevel 3 .` (比如该 readme 的`#### 实例`并没有超链接) 178 | 179 | 默认情况下, 180 | 181 | - 没有限制标题, 182 | - 而来自嵌入式 HTML 的标题(heading)限于 第 4 级. 183 | 184 | ### 打印到标准输出 185 | 186 | 您可以使用`-s`或`--stdout`选项。 187 | 188 | [ack]: http://beyondgrep.com/ 189 | 190 | ### 作为一个`git`钩子来使用 191 | 192 | 把 Doctoc 作为一个[pre-commit](http://pre-commit.com)钩子来使用，以下配置: 193 | 194 | ```yaml 195 | repos: 196 | - repo: https://github.com/thlorenz/doctoc 197 | sha: ... # substitute a tagged version 198 | hooks: 199 | - id: doctoc 200 | ``` 201 | 202 | 这将在 git commit 文件时，运行`doctoc`,确保 TOC 保持最新. 203 | -------------------------------------------------------------------------------- /en.md: -------------------------------------------------------------------------------- 1 | # DocToc [![build status](https://secure.travis-ci.org/thlorenz/doctoc.svg)](http://travis-ci.org/thlorenz/doctoc) 2 | 3 | become a patron 4 | 5 | Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated 6 | by github or other sites via a command line flag. 7 | 8 | 9 | 10 | **Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* 11 | 12 | - [Installation](#installation) 13 | - [Usage](#usage) 14 | - [Adding toc to all files in a directory and sub directories](#adding-toc-to-all-files-in-a-directory-and-sub-directories) 15 | - [Update existing doctoc TOCs effortlessly](#update-existing-doctoc-tocs-effortlessly) 16 | - [Adding toc to individual files](#adding-toc-to-individual-files) 17 | - [Examples](#examples) 18 | - [Using doctoc to generate links compatible with other sites](#using-doctoc-to-generate-links-compatible-with-other-sites) 19 | - [Example](#example) 20 | - [Specifying location of toc](#specifying-location-of-toc) 21 | - [Specifying a custom TOC title](#specifying-a-custom-toc-title) 22 | - [Specifying a maximum heading level for TOC entries](#specifying-a-maximum-heading-level-for-toc-entries) 23 | - [Printing to stdout](#printing-to-stdout) 24 | - [Usage as a `git` hook](#usage-as-a-git-hook) 25 | 26 | 27 | 28 | 29 | ## Installation 30 | 31 | npm install -g doctoc 32 | 33 | ## Usage 34 | 35 | In its simplest usage, you can pass one or more files or folders to the 36 | `doctoc` command. This will update the TOCs of each file specified as well as of 37 | each markdown file found by recursively searching each folder. Below are some 38 | examples. 39 | 40 | ### Adding toc to all files in a directory and sub directories 41 | 42 | Go into the directory that contains you local git project and type: 43 | 44 | doctoc . 45 | 46 | This will update all markdown files in the current directory and all its 47 | subdirectories with a table of content that will point at the anchors generated 48 | by the markdown parser. Doctoc defaults to using the GitHub parser, but other 49 | [modes can be 50 | specified](#using-doctoc-to-generate-links-compatible-with-other-sites). 51 | 52 | 53 | ### Update existing doctoc TOCs effortlessly 54 | 55 | If you already have a TOC inserted by doctoc, it will automatically be updated by running the command (rather than inserting a duplicate toc). Doctoc locates the TOC by the `` and `` comments, so you can also move a generated TOC to any other portion of your document and it will be updated there. 56 | 57 | ### Adding toc to individual files 58 | 59 | If you want to convert only specific files, do: 60 | 61 | doctoc /path/to/file [...] 62 | 63 | #### Examples 64 | 65 | doctoc README.md 66 | 67 | doctoc CONTRIBUTING.md LICENSE.md 68 | 69 | You can use this feature to do more sophisticated things. For example, if you 70 | have [ack][ack] installed, you could add `` to specific 71 | files and then use 72 | 73 | ack -L 'DOCTOC SKIP' | xargs doctoc 74 | 75 | to recompile only those files which don't have the DOCTOC SKIP comment. 76 | 77 | ### Using doctoc to generate links compatible with other sites 78 | 79 | In order to add a table of contents whose links are compatible other sites add the appropriate mode flag: 80 | 81 | Available modes are: 82 | 83 | ``` 84 | --bitbucket bitbucket.org 85 | --nodejs nodejs.org 86 | --github github.com 87 | --gitlab gitlab.com 88 | --ghost ghost.org 89 | ``` 90 | 91 | #### Example 92 | 93 | doctoc README.md --bitbucket 94 | 95 | ### Specifying location of toc 96 | 97 | By default, doctoc places the toc at the top of the file. You can indicate to have it placed elsewhere with the following format: 98 | 99 | ``` 100 | 101 | 102 | ``` 103 | 104 | You place this code directly in your .md file. For example: 105 | 106 | ``` 107 | // my_new_post.md 108 | Here we are, introducing the post. It's going to be great! 109 | But first: a TOC for easy reference. 110 | 111 | 112 | 113 | 114 | # Section One 115 | 116 | Here we'll discuss... 117 | 118 | ``` 119 | 120 | Running doctoc will insert the toc at that location. 121 | 122 | ### Specifying a custom TOC title 123 | 124 | Use the `--title` option to specify a (Markdown-formatted) custom TOC title; e.g., `doctoc --title '**Contents**' .` From then on, you can simply run `doctoc ` and doctoc will will keep the title you specified. 125 | 126 | Alternatively, to blank out the title with a newline, use the `--notitle` option. This will simply remove the title from the TOC. 127 | 128 | ### Specifying a maximum heading level for TOC entries 129 | 130 | Use the `--maxlevel` option to limit TOC entries to headings only up to the specified level; e.g., `doctoc --maxlevel 3 .` 131 | 132 | By default, 133 | 134 | - no limit is placed on Markdown-formatted headings, 135 | - whereas headings from embedded HTML are limited to 4 levels. 136 | 137 | ### Printing to stdout 138 | 139 | You can print to stdout by using the `-s` or `--stdout` option. 140 | 141 | [ack]: http://beyondgrep.com/ 142 | 143 | ### Usage as a `git` hook 144 | 145 | doctoc can be used as a [pre-commit](http://pre-commit.com) hook by using the 146 | following configuration: 147 | 148 | ```yaml 149 | repos: 150 | - repo: https://github.com/thlorenz/doctoc 151 | sha: ... # substitute a tagged version 152 | hooks: 153 | - id: doctoc 154 | ``` 155 | 156 | This will run `doctoc` against markdown files when committing to ensure the 157 | TOC stays up-to-date. 158 | --------------------------------------------------------------------------------