feat: add skip feature (#93)

Author: technote-space

__tests__/file.test.ts

@@ -26,6 +26,10 @@ describe('findMarkdownFiles', () => {
         'name': 'readme-not-updated.md',
         'path': resolve(__dirname, 'fixtures/readme-not-updated.md'),
       },
+      {
+        'name': 'readme-skipped.md',
+        'path': resolve(__dirname, 'fixtures/readme-skipped.md'),
+      },
       {
         'name': 'readme-update-only.md',
         'path': resolve(__dirname, 'fixtures/readme-update-only.md'),

__tests__/fixtures/readme-skipped.md

@@ -0,0 +1,14 @@
+<!-- DOCTOC SKIP -->
+# Hello, world!
+
+> You can make code blocks with three back ticks:
+>
+> ```
+
+# Add this header
+
+<h1>And also this one</h1>
+
+> ```
+
+

__tests__/transform-not-transformed.test.ts

@@ -20,4 +20,12 @@ describe('transform', () => {
     expect(headers.transformed).toBe(false);
     expect(headers.reason).toBe('not updated');
   });
+
+  it('skipped', () => {
+    const content = readFileSync(resolve(__dirname, 'fixtures/readme-skipped.md'), 'utf8');
+    const headers = transform(content);
+
+    expect(headers.transformed).toBe(false);
+    expect(headers.reason).toBe('skipped');
+  });
 });

__tests__/transform.test.ts

@@ -2,7 +2,7 @@
 import { describe, expect, it } from 'vitest';
 import { transform } from '../src/index.js';
 import { OPENING_COMMENT, CLOSING_COMMENT } from '../src/index.js';
-import { getLinesToToc, matchesStart, matchesEnd } from '../src/lib/transform.js';
+import { getLinesToToc, matchesStart, matchesEnd, matchesSkip } from '../src/lib/transform.js';
 
 const check = (
   name: string,
@@ -620,3 +620,15 @@ describe('matchesEnd', () => {
     expect(matchesEnd(['<!-- test '])('<!-- END doctoc -->')).toBe(false);
   });
 });
+
+describe('matchesSkip', () => {
+  it('should return true', () => {
+    expect(matchesSkip()('<!-- DOCTOC SKIP -->')).toBe(true);
+    expect(matchesSkip(['<!-- test '])('<!-- test abc -->')).toBe(true);
+  });
+
+  it('should return false', () => {
+    expect(matchesSkip()('<!-- doctoc -->')).toBe(false);
+    expect(matchesSkip(['<!-- test '])('<!-- DOCTOC SKIP -->')).toBe(false);
+  });
+});

src/constant.ts

@@ -3,6 +3,7 @@ export const OPENING_COMMENT         = '<!-- START doctoc generated TOC please k
 export const CLOSING_COMMENT         = '<!-- END doctoc generated TOC please keep comment here to allow auto update -->';
 export const CHECK_OPENING_COMMENT   = '<!-- START doctoc ';
 export const CHECK_CLOSING_COMMENT   = '<!-- END doctoc ';
+export const CHECK_SKIP_COMMENT      = '<!-- DOCTOC SKIP ';
 export const DEFAULT_TITLE           = '**Table of Contents**  *generated with [DocToc](https://github.com/technote-space/doctoc)*';
 export const MARKDOWN_EXTENSIONS     = ['.md', '.markdown'];
 export const IGNORED_DIRS            = ['.', '..', '.git', 'node_modules'];

src/lib/transform.ts

@@ -8,6 +8,7 @@ import {
   CLOSING_COMMENT,
   CHECK_OPENING_COMMENT,
   CHECK_CLOSING_COMMENT,
+  CHECK_SKIP_COMMENT,
   DEFAULT_TITLE,
   DEFAULT_CUSTOM_TEMPLATE,
   DEFAULT_ITEM_TEMPLATE,
@@ -27,6 +28,7 @@ const getTargetComments = (checkComments: Array<string>, defaultComments: string
 
 export const matchesStart = (checkOpeningComments?: Array<string>) => (line: string): boolean => getTargetComments(checkOpeningComments ?? [], CHECK_OPENING_COMMENT).some(comment => new RegExp(comment).test(line));
 export const matchesEnd   = (checkClosingComments?: Array<string>) => (line: string): boolean => getTargetComments(checkClosingComments ?? [], CHECK_CLOSING_COMMENT).some(comment => new RegExp(comment).test(line));
+export const matchesSkip  = (checkSkipComments?: Array<string>) => (line: string): boolean => getTargetComments(checkSkipComments ?? [], CHECK_SKIP_COMMENT).some(comment => new RegExp(comment).test(line));
 const addAnchor           = (mode: string, moduleName: string | undefined, header: HeaderWithRepetition): HeaderWithAnchor => {
   return {
     ...header,
@@ -185,7 +187,11 @@ export const transform = (
   content: string,
   options: TransformOptions = {},
 ): TransformResult => {
-  const lines             = content.split('\n');
+  const lines = content.split('\n');
+  if (lines.some(matchesSkip(options.checkSkipComments))) {
+    return getResult({ transformed: false, reason: 'skipped' });
+  }
+
   const info: SectionInfo = updateSection.parse(lines, matchesStart(options.checkOpeningComments), matchesEnd(options.checkClosingComments));
 
   const startSection     = getStartSection(lines, info, matchesEnd(options.checkClosingComments));

src/types.ts

@@ -14,6 +14,7 @@ export type TransformOptions = Partial<{
   closingComment: string;
   checkOpeningComments: Array<string>;
   checkClosingComments: Array<string>;
+  checkSkipComments: Array<string>;
   isCustomMode: boolean;
   customTemplate: string;
   itemTemplate: string;