.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: thlorenz
+patreon: thlorenz
+custom: ['paypal.me/thlorenz']

.travis.yml

@@ -1,8 +1,16 @@
 language: node_js
+
+os: linux
+
+dist: bionic
+
 node_js:
-  - 0.10
-  - 0.12
-  - 4
-  - 6
-  - 8
-  - 9
+  - 10        # Previous LST
+  - 12.18.1   # Actual LTS
+  - 14.4.0    # Latest version
+
+install: npm install
+
+script: npm test
+
+cache: npm

README.md

@@ -123,7 +123,7 @@ Running doctoc will insert the toc at that location.
 
 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.
+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
 
@@ -140,6 +140,10 @@ 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
@@ -148,7 +152,7 @@ following configuration:
 ```yaml
 repos:
 -   repo: https://github.com/thlorenz/doctoc
-    sha: ...  # substitute a tagged version
+    rev: ...  # substitute a tagged version
     hooks:
     -   id: doctoc
 ```

doctoc.js

@@ -16,13 +16,21 @@ function cleanPath(path) {
   return homeExpanded.replace(/\s/g, '\\ ');
 }
 
-function transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, stdOut) {
+function transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, stdOut, updateOnly) {
+  if (processAll) {
+    console.log('--all flag is enabled. Including headers before the TOC location.')
+  }
+
+  if (updateOnly) {
+    console.log('--update-only flag is enabled. Only updating files that already have a TOC.')
+  }
+
   console.log('\n==================\n');
 
   var transformed = files
     .map(function (x) {
       var content = fs.readFileSync(x.path, 'utf8')
-        , result = transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix);
+        , result = transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, updateOnly);
       result.path = x.path;
       return result;
     });
@@ -54,7 +62,7 @@ function printUsageAndExit(isErr) {
 
   var outputFunc = isErr ? console.error : console.info;
 
-  outputFunc('Usage: doctoc [mode] [--entryprefix prefix] [--notitle | --title title] [--maxlevel level] <path> (where path is some path to a directory (e.g., .) or a file (e.g., README.md))');
+  outputFunc('Usage: doctoc [mode] [--entryprefix prefix] [--notitle | --title title] [--maxlevel level] [--all] [--update-only] <path> (where path is some path to a directory (e.g., .) or a file (e.g., README.md))');
   outputFunc('\nAvailable modes are:');
   for (var key in modes) {
     outputFunc('  --%s\t%s', key, modes[key]);
@@ -75,7 +83,7 @@ var modes = {
 var mode = modes['github'];
 
 var argv = minimist(process.argv.slice(2)
-    , { boolean: [ 'h', 'help', 'T', 'notitle', 's', 'stdout'].concat(Object.keys(modes))
+    , { boolean: [ 'h', 'help', 'T', 'notitle', 's', 'stdout', 'all' , 'u', 'update-only'].concat(Object.keys(modes))
     , string: [ 'title', 't', 'maxlevel', 'm', 'entryprefix' ]
     , unknown: function(a) { return (a[0] == '-' ? (console.error('Unknown option(s): ' + a), printUsageAndExit(true)) : true); }
     });
@@ -93,7 +101,9 @@ for (var key in modes) {
 var title = argv.t || argv.title;
 var notitle = argv.T || argv.notitle;
 var entryPrefix = argv.entryprefix || '-';
+var processAll = argv.all;
 var stdOut = argv.s || argv.stdout
+var updateOnly = argv.u || argv['update-only']
 
 var maxHeaderLevel = argv.m || argv.maxlevel;
 if (maxHeaderLevel && isNaN(maxHeaderLevel) || maxHeaderLevel < 0) { console.error('Max. heading level specified is not a positive number: ' + maxHeaderLevel), printUsageAndExit(true); }
@@ -110,7 +120,9 @@ for (var i = 0; i < argv._.length; i++) {
     files = [{ path: target }];
   }
 
-  transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, stdOut);
+  transformAndSave(files, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, stdOut, updateOnly);
 
   console.log('\nEverything is OK.');
 }
+
+module.exports.transform = transform;

lib/transform.js

@@ -85,8 +85,8 @@ function countHeaders (headers) {
   return headers;
 }
 
-function getLinesToToc (lines, currentToc, info) {
-  if (!currentToc) return lines;
+function getLinesToToc (lines, currentToc, info, processAll) {
+  if (processAll || !currentToc) return lines;
 
   var tocableStart = 0;
 
@@ -106,7 +106,7 @@ function determineTitle(title, notitle, lines, info) {
   return info.hasStart ? lines[info.startIdx + 2] : defaultTitle;
 }
 
-exports = module.exports = function transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix) {
+exports = module.exports = function transform(content, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll, updateOnly) {
   mode = mode || 'github.com';
   entryPrefix = entryPrefix || '-';
 
@@ -116,10 +116,16 @@ exports = module.exports = function transform(content, mode, maxHeaderLevel, tit
   var lines = content.split('\n')
     , info = updateSection.parse(lines, matchesStart, matchesEnd)
 
+  if (!info.hasStart && updateOnly) {
+    return { transformed: false };
+  }
+
   var inferredTitle = determineTitle(title, notitle, lines, info);
 
+  var titleSeparator = inferredTitle ? '\n\n' : '\n';
+
   var currentToc = info.hasStart && lines.slice(info.startIdx, info.endIdx + 1).join('\n')
-    , linesToToc = getLinesToToc(lines, currentToc, info);
+    , linesToToc = getLinesToToc(lines, currentToc, info, processAll);
 
   var headers = getMarkdownHeaders(linesToToc, maxHeaderLevel)
     .concat(getHtmlHeaders(linesToToc, maxHeaderLevelHtml))
@@ -139,7 +145,7 @@ exports = module.exports = function transform(content, mode, maxHeaderLevel, tit
 
   var toc =
       inferredTitle
-    + '\n\n'
+    + titleSeparator
     + linkedHeaders
         .map(function (x) {
           var indent = _(_.range(x.rank - lowestRank))

package.json

@@ -2,29 +2,29 @@
   "author": "Thorsten Lorenz <thlorenz@gmx.de> (thlorenz.com)",
   "name": "doctoc",
   "description": "Generates TOC for markdown files of local git repo.",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "repository": {
     "type": "git",
     "url": "git://github.com/thlorenz/doctoc.git"
   },
   "scripts": {
     "test": "set -e; for t in test/*.js; do node $t; done"
   },
+  "files": [
+    "lib"
+  ],
   "main": "doctoc.js",
   "bin": "doctoc.js",
-  "engines": {
-    "node": ">=0.4"
-  },
   "dependencies": {
-    "@textlint/markdown-to-ast": "~6.0.9",
-    "anchor-markdown-header": "^0.5.5",
-    "htmlparser2": "~3.9.2",
-    "minimist": "~1.2.0",
-    "underscore": "~1.8.3",
-    "update-section": "^0.3.0"
+    "@textlint/markdown-to-ast": "~6.1.7",
+    "anchor-markdown-header": "~0.5.7",
+    "htmlparser2": "~4.1.0",
+    "minimist": "~1.2.5",
+    "underscore": "~1.10.2",
+    "update-section": "~0.3.3"
   },
   "devDependencies": {
-    "tap": "~10.2.1"
+    "tap": "^14.10.7"
   },
   "license": "MIT",
   "keywords": [

test/transform-title.js

@@ -45,7 +45,6 @@ test('\nclobber existing title', function (t) {
   t.deepEqual(
       headers.toc.split('\n')
     , [ '',
-        '',
         '- [Installation](#installation)',
         '- [API](#api)',
         '- [License](#license)',

test/transform.js

@@ -8,9 +8,9 @@ function inspect(obj, depth) {
   console.log(require('util').inspect(obj, false, depth || 5, true));
 }
 
-function check(md, anchors, mode, maxHeaderLevel, title, notitle, entryPrefix) {
+function check(md, anchors, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll) {
   test('transforming', function (t) {
-    var res = transform(md, mode, maxHeaderLevel, title, notitle, entryPrefix)
+    var res = transform(md, mode, maxHeaderLevel, title, notitle, entryPrefix, processAll)
 
     // remove wrapper
     var data = res.data.split('\n');
@@ -284,6 +284,75 @@ test('transforming when old toc exists', function (t) {
   t.end()
 })
 
+test('transforming when old toc exists and --all flag is set', function (t) {
+  var md = [ 
+      '# Header above'
+    , ''
+    , 'The above header should be ignored since it is above the existing toc'
+    , ''
+    , '<!-- START doctoc generated TOC please keep comment here to allow auto update -->'
+    , '<!-- DON\'T EDIT THIS SECTION INSTEAD RE-RUN doctoc TO UPDATE -->'
+    , '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*'
+    , ''
+    , '- [OldHeader](#oldheader)'
+    , ''
+    , '<!-- END doctoc generated TOC please keep comment here to allow auto update -->' 
+    , '## Header'
+    , 'some content'
+    , ''
+    ].join('\n')
+
+  var res = transform(md, undefined, undefined, undefined, undefined, undefined, true)
+
+  t.ok(res.transformed, 'transforms it')     
+
+  t.deepEqual(
+      res.toc.split('\n')
+    , [ '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+      '',
+      '- [Header above](#header-above)',
+      '  - [Header](#header)',
+      '' ]
+    , 'replaces old toc' 
+  )
+
+  t.deepEqual(
+      res.wrappedToc.split('\n')
+    , [ '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+        '',
+        '- [Header above](#header-above)',
+        '  - [Header](#header)',
+        '',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->' 
+      ]
+    , 'wraps old toc'
+  )
+
+  t.deepEqual(
+      res.data.split('\n')
+    , [ '# Header above',
+        '',
+        'The above header should be ignored since it is above the existing toc',
+        '',
+        '<!-- START doctoc generated TOC please keep comment here to allow auto update -->',
+        '<!-- DON\'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->',
+        '**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*',
+        '',
+        '- [Header above](#header-above)',
+        '  - [Header](#header)',
+        '',
+        '<!-- END doctoc generated TOC please keep comment here to allow auto update -->',
+        '## Header',
+        'some content',
+        '' ]
+    , 'updates the content with the new toc and ignores header before existing toc'
+  ) 
+  t.end()
+})
+
+
 // bigbucket.org
 check(
     [ '# My Module'