Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thlorenz/doctoc

📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.
https://github.com/thlorenz/doctoc

Last synced: 10 days ago
JSON representation

📜 Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated by github or other sites.

Awesome Lists containing this project

README 

        
# DocToc [![Node.js CI](https://github.com/thlorenz/doctoc/actions/workflows/node.js.yml/badge.svg)](https://github.com/thlorenz/doctoc/actions/workflows/node.js.yml)



Generates table of contents for markdown files inside local git repository. Links are compatible with anchors generated

by github or other sites via a command line flag.



**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*



- [Installation](#installation)

- [Usage](#usage)

  - [Adding toc to all files in a directory and sub directories](#adding-toc-to-all-files-in-a-directory-and-sub-directories)

  - [Update existing doctoc TOCs effortlessly](#update-existing-doctoc-tocs-effortlessly)

  - [Adding toc to individual files](#adding-toc-to-individual-files)

    - [Examples](#examples)

  - [Using doctoc to generate links compatible with other sites](#using-doctoc-to-generate-links-compatible-with-other-sites)

    - [Example](#example)

  - [Specifying location of toc](#specifying-location-of-toc)

  - [Specifying a custom TOC title](#specifying-a-custom-toc-title)

  - [Specifying a maximum heading level for TOC entries](#specifying-a-maximum-heading-level-for-toc-entries)

  - [Printing to stdout](#printing-to-stdout)

  - [Usage as a `git` hook](#usage-as-a-git-hook)

  - [Docker image](#docker-image)



## Installation



    npm install -g doctoc



## Usage



In its simplest usage, you can pass one or more files or folders to the

`doctoc` command. This will update the TOCs of each file specified as well as of

each markdown file found by recursively searching each folder. Below are some

examples.



### Adding toc to all files in a directory and sub directories



Go into the directory that contains you local git project and type:

    

    doctoc .



This will update all markdown files in the current directory and all its

subdirectories with a table of content that will point at the anchors generated

by the markdown parser. Doctoc defaults to using the GitHub parser, but other

[modes can be

specified](#using-doctoc-to-generate-links-compatible-with-other-sites).



### Ignoring individual files

In order to ignore a specific file when running `doctoc` on an entire directory, just add `` to the top of the file you wish to ignore.



### Update existing doctoc TOCs effortlessly



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.



### Adding toc to individual files



If you want to convert only specific files, do:



    doctoc /path/to/file [...]



#### Examples



    doctoc README.md



    doctoc CONTRIBUTING.md LICENSE.md



### Using doctoc to generate links compatible with other sites



In order to add a table of contents whose links are compatible other sites add the appropriate mode flag:



Available modes are:



```

--bitbucket bitbucket.org

--nodejs    nodejs.org

--github    github.com

--gitlab    gitlab.com

--ghost     ghost.org

```



#### Example



    doctoc README.md --bitbucket



### Specifying location of toc



By default, doctoc places the toc at the top of the file. You can indicate to have it placed elsewhere with the following format:



```



```



You place this code directly in your .md file. For example:



```

// my_new_post.md

Here we are, introducing the post. It's going to be great!

But first: a TOC for easy reference.



# Section One



Here we'll discuss...



```



Running doctoc will insert the toc at that location.



### Specifying a custom TOC title



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.



Alternatively, to blank out the title, use the `--notitle` option. This will simply remove the title from the TOC.



### Specifying a maximum heading level for TOC entries



Use the `--maxlevel` option to limit TOC entries to headings only up to the specified level; e.g., `doctoc --maxlevel 3 .`



By default,



- no limit is placed on Markdown-formatted headings,

- whereas headings from embedded HTML are limited to 4 levels.



### Printing to stdout



You can print to stdout by using the `-s` or `--stdout` option.



[ack]: http://beyondgrep.com/



### Only update existing ToC



Use `--update-only` or `-u` to only update the existing ToC. That is, the Markdown files without ToC will be left untouched. It is good if you want to use `doctoc` with `lint-staged`.



### Usage as a `git` hook



doctoc can be used as a [pre-commit](http://pre-commit.com) hook by using the

following configuration:



```yaml

repos:

-   repo: https://github.com/thlorenz/doctoc

    rev: ...  # substitute a tagged version

    hooks:

    -   id: doctoc

```



This will run `doctoc` against markdown files when committing to ensure the

TOC stays up-to-date.



### Docker image



There's an unofficial Docker image project for doctoc, if you'd like to use doctoc via Docker or other container based CI/CD pipeline, you can take a look at [PeterDaveHello/docker-doctoc](https://github.com/PeterDaveHello/docker-doctoc)