mktoc

图形设计是我的激情 ✨

目录

• 关于
• 安装
  • Cargo
  • 二进制文件
• 用法
  • 更新 Markdown 文件
    • 内联配置
      • min_depth
      • max_depth
      • wrap_in_details
  • 命令行
  • 环境配置
• 与 VSCode 自动运行
• 性能
• 贡献
  • 从哪里开始？
  • 工具
  • 安装开发版本
• 许可证

关于

⬆️ 返回顶部

mktoc 解析 markdown 文件并生成一个目录，链接到最深的标题级别 6，或者根据命令行参数、环境变量或内联 JSON 配置（见 用法）指定的标题。

安装

⬆️ 返回顶部

mktoc 可以使用 Cargo，Rust 软件包管理器进行安装。

Cargo

安装

$ cargo install mktoc

更新

$ cargo install --force mktoc

二进制文件

Linux 和 MacOS 的二进制文件可以从 发布页面 下载。

Windows 的二进制文件尚未自动构建，请参阅 #7。

用法

更新 Markdown 文件

⬆️ 返回顶部

将以下 HTML 注释添加到 Markdown 文件中，其中应渲染目录。

<!-- BEGIN mktoc -->
<!-- END mktoc -->

这些注释之间的所有内容都将被替换！

内联配置

⬆️ 返回顶部

从版本 3.0.0 开始，可以设置内联值，这对于与可能具有个人设置的团队合作非常有用。

<!-- BEGIN mktoc {"min_depth": 2, "max_depth": 4, "wrap_in_details": false} -->
<!-- END mktoc -- >

这等同于运行 mktoc -m 2 -M 4 或设置以下环境变量 MKTOC_MIN_DEPTH=2 和 MKTOC_MAX_DEPTH=4。

内联配置优先于环境或命令行参数。

min_depth

查找的最小深度，默认为1，等同于 <h1> 或 #。

max_depth

查找的最大深度，默认为6，等同于 <h6> 或 ######。

wrap_in_details

如果设置为true，目录将包含在 <details> 元素中。

命令行

⬆️ 返回顶部

指定 --stdout 或 -s 将生成的内容输出到 stdout 而不是覆盖文件。默认情况下将覆盖指定的文件。

$ mktoc -h
Generate Table of Contents from Markdown files

Usage: mktoc [OPTIONS] [FILE]

Arguments:
  [FILE]  [default: README.md]

Options:
  -s, --stdout                 If set will output to stdout instead of replacing content in file
  -m, --min-depth <MIN_DEPTH>  Minimum heading level [env: MKTOC_MIN_DEPTH=] [default: 1]
  -M, --max-depth <MAX_DEPTH>  Maximum heading level [env: MKTOC_MAX_DEPTH=] [default: 6]
  -w, --wrap-in-details        Wrap ToC in details html element [env: MKTOC_WRAP_IN_DETAILS=]
  -h, --help                   Print help
  -V, --version                Print version

$ mktoc -s README.md
$ mktoc -m 2 -M 4 README.md
$ mktoc

如果没有提供参数，则使用默认或配置的（通过环境）值。

有关所有参数和标志的列表，请参阅 mktoc --help。

mktoc

USAGE:
mktoc [FLAGS] [OPTIONS] [file]

FLAGS:
-h, --help       Prints help information
-s, --stdout     If set will output to stdout instead of replacing content in file
-V, --version    Prints version information

OPTIONS:
-M, --max-depth <max-depth>    Maximum heading level [env: MKTOC_MAX_DEPTH=]  [default: 6]
-m, --min-depth <min-depth>    Minimum heading level [env: MKTOC_MIN_DEPTH=2]  [default: 1]

ARGS:
<file>     [default: README.md]

环境配置

⬆️ 返回顶部

mktoc 可以通过环境变量进行配置，即

• MKTOC_MIN_DEPTH 等于 -m
• MKTOC_MAX_DEPTH 等于 -M

将这些变量放在shell环境文件中，如 ~/.bashrc 或 ~/.zshrc，然后只需运行mktoc而无需 -m 和 -M

# The following in ~/.bashrc|~/.zshrc configures mktoc to render headings from level 2 to
# level 4
# 
# MKTOC_MIN_DEPTH=2
# MKTOC_MAX_DEPTH=4
# MKTOC_WRAP_IN_DETAILS=true

$ mktoc README.md

与 VSCode 自动运行

⬆️ 返回顶部

对于VSCode，可以使用 Run on save 扩展来触发mktoc。

安装扩展后，将以下配置添加到工作区或用户的 settings.json。

"emeraldwalk.runonsave": {
    "commands": [
        {
            "match": "\\.md$",
            "cmd": "mktoc ${file}"
        }
    ]
}

这将在安全的情况下为每个markdown文件运行命令。如果Markdown文件中没有mktoc注释，则不会发生任何操作。

性能

⬆️ 返回顶部

mktoc 很快，但可能更快！欢迎Pull Requests和错误报告！

贡献

⬆️ 返回顶部

我们热爱并欢迎所有形式的贡献。

从哪里开始？

以下是一些开始的好地方

• 标签为 Good first issue 的问题
• 标签为 Documentation 的问题
• 提供示例实现或使用演示

工具

• mktoc 用于README.md中的目录生成（很棒！）
• criterion 用于基准测试

安装开发版本

有时安装mktoc的特定版本是很有用的，可以使用以下命令完成

# install specific commit
cargo install --git https://github.com/KevinGimbel/mktoc --force --rev $COMMIT_ID
# install branch
cargo install --git https://github.com/KevinGimbel/mktoc --force --branch $BRANCH_NAME

许可证

⬆️ 返回顶部

MIT，请参阅LICENSE文件。