blob: d9de7fc38905b04424e947ce76e639fb729acce6 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
# `mktoc`
> Markdown Table of Content generator
<!-- BEGIN mktoc -->
- [About](#about)
- [Installation](#installation)
- [Cargo](#cargo)
- [Binary](#binary)
- [Usage](#usage)
- [Update Markdown file](#update-markdown-file)
- [Command line](#command-line)
- [Environment configuration](#environment-configuration)
- [Performance](#performance)
- [License](#license)
<!-- END mktoc -->
## About
`mktoc` parses markdown files and generates a Table Of Content linking all headlines up to heading level 6 deep, or as specified by command line arguments. A start depth and maximum depth can be specified.
## Installation
`mktoc` can be installed using Cargo, the Rust package manager.
### Cargo
```sh
$ cargo install mktoc
```
#### Update
```
$ cargo install --force mktoc
```
### Binary
Binaries are actually not available yet. If you know how releasing binaries with Rust can be implemented, please let me know!
## Usage
### Update Markdown file
Add the following HTML comment into the Markdown file where the Table of Contents should be rendered.
```
<!-- BEGIN mktoc -->
<!-- END mktoc -->
```
Everything between those comments will be replaced!
### Command line
Specify `--stdout` or `-s` to output generated content to `stdout` instead of overwriting file. By default the specified file will be overwritten.
```
# mktoc [FLAGS] [OPTIONS] [file]
$ mktoc -s README.md
$ mktoc -m 2 -M 4 README.md
$ mktoc
```
If no arguments are given the default or configured (via environment) values are
used.
See `mktoc --help` for list of all arguments and flags.
```
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]
```
### Environment configuration
mktoc can be configured with environment variables, namely:
- `MKTOC_MIN_DEPTH` equal to `-m`
- `MKTOC_MAX_DEPTH` equal to `-M`
Place these variables in a shell environment file such as `~/.bashrc` or
`~/.zshrc`, then just run mktoc without `-m` and `-M`
```sh
# The following in ~/.bashrc configures mktoc to render headings from level 2 to
# level 4
#
# MKTOC_MIN_DEPTH=2
# MKTOC_MAX_DEPTH=4
$ mktoc README.md
```
## Performance
`mktoc` is fast but can probably be even faster! Pull Requests and bug reports are appreciated!
## License
MIT, see LICENSE file.
|
