GithubHelp home page GithubHelp logo

alexxnica / doctoc Goto Github PK

View Code? Open in Web Editor NEW

This project forked from thlorenz/doctoc

0.0 1.0 0.0 108 KB

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

Home Page: https://www.npmjs.com/package/doctoc

License: MIT License

JavaScript 100.00%

doctoc's Introduction

DocToc build status

NPM

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

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.

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 <!-- START doctoc --> and <!-- END doctoc --> 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

You can use this feature to do more sophisticated things. For example, if you have ack installed, you could add <!-- DOCTOC SKIP --> to specific files and then use

ack -L 'DOCTOC SKIP' | xargs doctoc

to recompile only those files which don't have the DOCTOC SKIP comment.

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:

<!-- START doctoc -->
<!-- END doctoc -->

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.

<!-- START doctoc -->
<!-- END doctoc -->

# 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 <file> and doctoc will will keep the title you specified.

Alternatively, to blank out the title with a newline, 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.

Usage as a git hook

doctoc can be used as a pre-commit hook by using the following configuration:

repos:
-   repo: https://github.com/thlorenz/doctoc
    sha: ...  # substitute a tagged version
    hooks:
    -   id: doctoc

This will run doctoc against markdown files when committing to ensure the TOC stays up-to-date.

doctoc's People

Contributors

thlorenz avatar jez avatar miangraham-ss avatar peterdavehello avatar qubyte avatar raynos avatar sheriferson avatar plumlee avatar richardlitt avatar michelle avatar mklement0 avatar jmanuel1 avatar faheel avatar bitdeli-chef avatar asottile avatar andrewsouthpaw avatar a0viedo avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.