# 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) - [Configuration](#configuration) - [CLI Options](#cli-options) - [Logging level](#logging-level) - [Dry run](#dry-run) - [Stdout](#stdout) - [Update only](#update-only) - [Document Options](#document-options) - [Min. Document Lines](#min-document-lines) - [Renderers](#renderers) - [Source Options](#source-options) - [Heading](#heading) - [Table of Contents Options](#table-of-contents-options) - [General](#general) - [Header](#header) - [Title](#title) - [List Options](#list-options) - [TOC Items](#toc-items) - [Footer](#footer) - [Usage](#usage) - [Adding toc to all files in a directory and sub directories](#adding-toc-to-all-files-in-a-directory-and-sub-directories) - [Ignoring individual files](#ignoring-individual-files) - [Update existing doctoc TOCs effortlessly](#update-existing-doctoc-tocs-effortlessly) - [Adding toc to individual files](#adding-toc-to-individual-files) - [Examples](#examples) - [Specifying location of toc](#specifying-location-of-toc) - [Usage as a `git` hook](#usage-as-a-git-hook) - [Docker image](#docker-image) ## Installation npm install -g doctoc ## Configuration ### CLI Options #### Logging level Use the `--loglevel` option to configure the log level used; e.g., `doctoc --loglevel warn .` By default, - LogLevel is set to info. Supported values are in order from lowest to highest, - trace - debug - info - warn - error #### Dry run Use the `--dryrun` option to not write changes to files but instead return an exit code of 1 to indicate files are out of date and should be updated. This is useful in CI environments where you want to check if your docs are up to date as part of your build process. #### Stdout You can print to stdout by using the `-s` or `--stdout` option. This option is only applicable when specifying a single filename which doctoc is to run on. If you are specifying a folder or multiple files, the dry run option should be used instead. #### Update only 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`. ### Document Options #### Min. Document Lines Use the `--document-lines-min` option to specify the minimum lines required to be in a document for the document to have a table of contents; e.g., `doctoc --document-lines-min 200 .`. By default, - The min Lines is set to 0 > [!NOTE] > It is assumed that if you are using this option, you are using another tool such as > MarkdownLint or Prettier to limit the length of lines to what is usually visible in a renderer. > [!TIP] > > If your document contains images, those images will not be counted any different to how plain text is, > as doctoc is processing your document as a text processor. > This also means repeated newlines will also be considered should your document contain them. #### Renderers In order to add a table of contents whose links are compatible with 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 ``` An example is: doctoc README.md --bitbucket ### Source Options #### Heading ##### Min. level Use the `--minlevel` option to limit TOC entries to headings only at or above the specified level; e.g., `doctoc --minlevel 2 .` By default, - the min level used is 1 if it is not set Note: Currently supported values are only 1 and 2. ##### Max. level 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. ##### Scope Use the `--all` option to include all headings in the TOC regardless of their location By default, - Only headings below the TOC will be included ### Table of Contents Options #### General ##### TOC Pragma style The pragma is the opening and closing comment blocks to mark the location of the doctoc contents, i.e. `` The default option, `legacy`, produces the following: ```markdown {{toc}} ``` You can choose `compact` to make the pragma more succinct: ```markdown {{toc}} ``` ##### TOC Location Use the `--toc-location` option to configure the location of automatically inserted toc e.g. `doctoc --toc-location before .` which will add the toc before the first heading used in the toc. > [!TIP] > > If you want to move an already inserted toc, this can be done by moving the toc block including pragma to the desired location. The supported options are: - **top**: inserts the toc at the top of the document before any markdown content but after any frontmatter if defined. - **before**: inserts the toc just before the first heading which appears in the toc. By default, the toc will be inserted using the top option and in v3 it will change to before. > [!NOTE] > > This option works in conjunction with the minlevel option. > For instance to insert the toc before the first level 2 heading use, > `doctoc --toc-location before --minlevel 2 .` #### Header ##### TOC Header Content Additional text can be added to the toc header using the `--toc-header-content` option. The text will appear below the pragma (``). For example, running `doctoc --toc-header-content 'My Header' .` would produce: ```markdown My Header {{toc}} ``` If you will be using the toc header option but without a toc title it is required that when updating the toc, you always include the --notitle argument. #### Title ##### TOC title content 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 keep the title you specified. ##### TOC title hidden Alternatively, to blank out the title, use the `--notitle` option. This will simply remove the title from the TOC. It is recommended to also include this argument when performing an update on an existing toc. ##### TOC title padding Use the `--toc-title-padding-before` option to add padding line/s above the TOC which ensures formatters such as prettier will pass; e.g., `doctoc --toc-title-padding-before 1 .` NOTE: Currently it is only supported to add one line before the title. By default, - no padding is added above the table of contents title In all cases there will be padding present after the title due to the toc items always having padding before the list of items. #### List Options ##### Min. Length Use the `--mintocitems` option to specify the minimum items required to be in a table of contents for it to be included in the page; e.g., `doctoc --mintocitems 3 .`. By default, - The min items is set to 1 #### TOC Items ##### Item Symbol Use the `--entryprefix` option to configure the symbol used in unordered toc, e.g., `doctoc --entryprefix * .` to use the `*` rather than the default, which is `-`. This option also supports customising each level of the list, which can be done by using a comma separated list of symbols, i.e. `doctoc --entryprefix="-,*,+" .`. ##### Indentation Width Use the `--toc-items-indentation-width` option to customise the indentation width e.g. `doctoc --toc-items-indentation-width 4 .` will set the width to 4. By default, a width of 4 will be used if mode is gitlab or bitbucket, otherwise 2 will be used. #### Footer ##### TOC Footer Content Additional text can be added to the toc footer using the `--toc-footer-content` option. The text will appear below the pragma (``). For example, running `doctoc --toc-footer-content 'My Footer' .` would produce: ```markdown {{toc}} My Footer ``` ## 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 your 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](#renderers). ### 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 ### 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: ```markdown ``` You place this code directly in your .md file. For example: ```markdown // 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 the specified location as illustrated below. ```markdown // my_new_post.md Here we are, introducing the post. It's going to be great! But first: a TOC for easy reference. **Contents** - [Section One](#section-one) # Section One Here we'll discuss... ``` ### 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)