Flutter Markdown目录生成插件markdown_toc的使用

Flutter Markdown目录生成插件markdown_toc的使用

目录

1. 概述

这个工具用于为Markdown文件添加标题编号和目录。

它用于使长Markdown文件更易于导航和阅读。

例如，它将一个包含以下内容的Markdown文件：

文档标题

Alpha

Foo

Bar

Beta

Gamma


转换为：


# 文档标题

## 目录

1. Alpha
   - 1.1 Foo
   - 1.2 Bar
2. Beta
3. Gamma

## 1. Alpha

### 1.1 Foo

### 1.2 Bar

## 2. Beta

## 3. Gamma

注意：此README已通过该工具处理，以自动生成上述目录和编号标题。嵌入的Markdown示例开始于行首的额外“|”，以防止该工具将其识别为需要处理的标题。

这是一个简化示例：实际输出还包含目录条目到它们所引用部分的超链接。

该工具还可以更新编号和目录。它可以重新运行自己的输出，这对于添加、更改或删除标题非常有用。

它还可以用于删除目录和标题编号。即，将其恢复到原始输入的Markdown状态。

2. 使用

2.1. 概要

Usage: markdown_toc [options] {markdown-files}
Options:
-t | --top-level N  最低编号标题级别（默认：2）
-n | --num-level N  最高编号标题级别（默认：5）
-i | --toc-level N  最高包括在目录中的标题级别（默认：4）

-o | --output FILE  将结果写入指定输出文件（默认：stdout）
-r | --replace      替换输入文件而不是输出到文件

-s | --strip        移除目录和编号，而不是添加/更新它们

-v | --verbose      运行时输出更多信息
     --version      显示版本信息并退出
-h | --help         显示帮助信息并退出

2.2. 输出生成

默认情况下，结果会写入标准输出：

$ markdown_toc.dart example.md

但通常会用该工具替换输入文件以获得结果：

$ markdown_toc.dart --replace example.md

或者，可以指定不同的输出文件：

$ markdown_toc.dart --output example-with-toc.md example.md

2.3. 标题语法

该工具仅处理使用“#”前缀的Markdown标题。忽略使用下划线的标题。

2.4. 目录

目录插入在第一个识别的标题之前。

2.5. 标题级别

2.5.1. 默认处理2级及以上标题

如果它处理2级标题及更高（默认设置），这允许文档的标题使用下划线语法格式化。它会忽略标题（即不编号也不包括在目录中），并在第一个非忽略标题之前插入目录。

默认最高编号级别为5。6级及以上的标题（即那些以Markdown “######” 开始的）不会被编号。

最高包括在目录中的标题级别为4。5级及以上的标题（即那些以Markdown “#####” 开始的）不会被包括在目录中（即使它们被编号）。

例如，

标题

======

第一节

子节

第二节


将生成：


# 标题
======

## 目录

...

## 1. 第一节

### 1.1 子节

## 2. 第二节

2.5.2. 更改处理的标题级别

通过 --top-level、--num-level 和 --toc-level 选项更改处理的标题级别。

例如，一些Markdown文件使用元数据块作为文档标题，1级标题作为普通标题使用。

% 文档的标题 % 作者 % 版本 1.0.0

第一节

子节

第二节


使用 `--top-level` 选项来包含1级标题：

```shell
$ markdown_toc --top-level 1  example.md

生成：

% 文档的标题 % 作者 % 版本 1.0.0

目录

…

1. 第一节

1.1 子节

2. 第二节


### 2.6. 删除目录和编号

使用 `--strip` 选项移除由该工具添加的信息。

```shell
$ markdown_toc.dart --strip example-with-toc.md

3. 安装

markdown_toc 不应作为依赖项使用。相反，应该安装。

有许多方法可以安装。

3.1. Dart

当用于管理Dart项目中的Markdown文件时，可以将此工具作为项目的开发依赖项。

3.1.1. Dart项目的依赖

该工具旨在作为Dart项目的开发依赖项，以便可以在项目中使用它为长Markdown文档添加编号标题和目录。

在 pubspec.yaml 中添加：

dev_dependencies:
  markdown_toc: ^1.1.0

然后运行：

$ dart pub get

工具应使用 dart run 命令运行，以运行通过 dart pub get 安装的具体版本的工具。

$ dart run markdown_toc --help

3.1.2. 全局安装

或者，使用 dart pub global activate 安装，以便可以在任何Markdown文件上使用（不仅仅是用于记录Dart项目的Markdown文件）。

$ dart pub global activate markdown_toc

如果全局目录在PATH中，可以通过以下方式运行工具：

$ markdown_toc --help

或者，总是可以通过以下方式运行：

$ dart pub global run markdown_toc --help

3.1.3. 脚本在任何有Dart的地方运行

最后，该工具已编写为不使用任何pub包。因此，只要 dart 可执行文件可用，就可以在任何地方运行。无需在Dart项目内部，也无需有相关的 pubspec.yaml 文件。

将 markdown_toc.dart 文件复制到PATH上的某个位置：

$ cp markdown_toc.dart /usr/local/bin/markdown_toc

然后像正常命令一样运行它：

$ markdown_toc --help

3.1.4. 编译的可执行文件无需Dart即可运行

编译成自包含的可执行文件。可以在任何地方运行，而无需Dart可执行文件。

$ dart compile exe bin/markdown_toc.dart
$ bin/markdown_toc --help

3.2. 二进制文件

二进制文件可以从项目的GitHub releases 下载。

将其复制到你的PATH中的某个位置。

4. 限制

4.1. 可能错误地将围栏代码块视为标题

围栏代码块内的行（即在以


更多关于Flutter Markdown目录生成插件markdown_toc的使用的实战教程也可以访问 https://www.itying.com/category-92-b0.html

1 回复

更多关于Flutter Markdown目录生成插件markdown_toc的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


markdown_toc 是一个 Flutter 插件，用于在 Markdown 文档中生成目录。它可以帮助你快速生成并管理 Markdown 文档的目录结构。以下是使用 markdown_toc 插件的详细步骤：

1. 添加依赖

首先，你需要在 pubspec.yaml 文件中添加 markdown_toc 依赖：

dependencies:
  flutter:
    sdk: flutter
  markdown_toc: ^1.0.0

然后运行 flutter pub get 来获取依赖。

2. 导入包

在你的 Dart 文件中导入 markdown_toc 包：

import 'package:markdown_toc/markdown_toc.dart';

3. 使用 markdown_toc 生成目录

你可以使用 markdown_toc 来生成 Markdown 文档的目录。以下是一个简单的示例：

void main() {
  String markdownContent = '''
  # Title 1
  ## Subtitle 1.1
  ### Subtitle 1.1.1
  ## Subtitle 1.2
  # Title 2
  ## Subtitle 2.1
  ''';

  Toc toc = Toc();
  String tocContent = toc.addToc(markdownContent);

  print('Generated TOC:\n$tocContent');
}

4. 输出

运行上述代码后，tocContent 将包含生成的目录，输出如下：


### 5. 插入目录到 Markdown 文档
你可以将生成的目录插入到 Markdown 文档中：

```dart
String finalMarkdown = '''
# Table of Contents
$tocContent

$markdownContent
''';

print('Final Markdown:\n$finalMarkdown');

6. 高级配置

markdown_toc 支持一些高级配置，例如自定义目录的深度、是否包含标题等。你可以通过 TocOptions 进行配置：

TocOptions options = TocOptions(
  heading: '## Table of Contents', // 自定义目录标题
  depth: 2, // 只生成到二级标题
);

Toc toc = Toc(options: options);
String tocContent = toc.addToc(markdownContent);

print('Custom TOC:\n$tocContent');
回到顶部