From 84543e04738d19c7fbb1782b2594bcba27b0cf09 Mon Sep 17 00:00:00 2001 From: w-bonelli Date: Fri, 21 Jul 2023 19:23:20 -0400 Subject: [PATCH] docs: add install and usage docs for node and doctoc --- docs/md/doctoc.md | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/md/doctoc.md b/docs/md/doctoc.md index 927368d2..ec752632 100644 --- a/docs/md/doctoc.md +++ b/docs/md/doctoc.md @@ -1,11 +1,46 @@ # Generating TOCs -The [`doctoc`](https://www.npmjs.com/package/doctoc) tool can be used to automatically generate table of contents sections for markdown files. `doctoc` is distributed with the [Node Package Manager](https://docs.npmjs.com/cli/v7/configuring-npm/install). With Node installed use `npm install -g doctoc` to install `doctoc` globally. Then just run `doctoc `, e.g.: +The [`doctoc`](https://www.npmjs.com/package/doctoc) tool generates table of contents sections for markdown files. + +## Installing Node.js, `npm` and `doctoc`` + +`doctoc` is distributed with the [Node Package Manager](https://docs.npmjs.com/cli/v7/configuring-npm/install). [Node](https://nodejs.org/en) is a JavaScript runtime environment. + +On Ubuntu, Node can be installed with: + +```shell +sudo apt update +sudo apt install nodejs +``` + +On Windows, with [Chocolatey](https://community.chocolatey.org/packages/nodejs): + +```shell +choco install nodejs +``` + +Installers and binaries for Windows and macOS are [available for download](https://nodejs.org/en/download). + +Once Node is installed, install `doctoc` with: + +```shell +npm install -g doctoc +``` + +## Using `doctoc` + +Then TOCs can be generated with `doctoc `, e.g.: ```shell doctoc DEVELOPER.md ``` -This will insert HTML comments surrounding an automatically edited region, scanning for headers and creating an appropriately indented TOC tree. Subsequent runs are idempotent, updating if the file has changed or leaving it untouched if not. +This will insert HTML comments surrounding an automatically edited region, in which `doctoc` will create an appropriately indented TOC tree. Subsequent runs are idempotent, scanning for headers and only updating the TOC if the file header structure has changed. + +To run `doctoc` for all markdown files in a particular directory (recursive), use `doctoc some/path`. + +By default `doctoc` inserts a self-descriptive comment + +> **Table of Contents** *generated with DocToc* -To run `doctoc` for all markdown files in a particular directory (recursive), use `doctoc some/path`. \ No newline at end of file +This can be removed (and other content within the TOC region edited) — `doctoc` will not overwrite it, only the table.