feat: skip機能を追加

README.md

@@ -48,6 +48,7 @@ transform(readFileSync('README.md', {
   // closingComment: '<!-- tocstop --> ',
   // checkOpeningComments: ['<!-- toc '],
   // checkClosingComments: ['<!-- tocstop '],
+  // checkSkipComments: ['<!-- toc skip '],
   // isCustomMode: false,
   // customTemplate: '<p align="center">${ITEMS}</p>',
   // itemTemplate: '<a href="${LINK}">${TEXT}</a>',

__tests__/file.test.ts

@@ -1,7 +1,7 @@
 /* eslint-disable no-magic-numbers */
 import { resolve } from 'path';
 import { describe, expect, it, vi } from 'vitest';
-import { findMarkdownFiles } from '../src';
+import { findMarkdownFiles } from '../src/index.js';
 
 describe('findMarkdownFiles', () => {
   it('should find markdown files', () => {
@@ -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__/params.test.ts

@@ -1,7 +1,7 @@
 /* eslint-disable no-magic-numbers */
 import { describe, expect, it } from 'vitest';
-import { CLOSING_COMMENT, OPENING_COMMENT } from '../src';
-import { extractParams, getStartSection, getParamsSection } from '../src/lib/params';
+import { CLOSING_COMMENT, OPENING_COMMENT } from '../src/index.js';
+import { extractParams, getStartSection, getParamsSection } from '../src/lib/params.js';
 
 describe('extractParams', () => {
   const opening = OPENING_COMMENT.replace('\n', ' ');

__tests__/transform-custom-mode.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('run in html mode', () => {

__tests__/transform-footer.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('add footer', () => {

__tests__/transform-html.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('given a file that includes html with header tags and maxHeaderLevel 8', () => {

__tests__/transform-nested-markdown.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('\nhandle inline links and images', () => {

__tests__/transform-not-transformed.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('update only', () => {
@@ -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-override-params.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('override params (empty toc)', () => {

__tests__/transform-title.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('overwrite existing title', () => {

__tests__/transform-weird-headers.test.ts

@@ -2,7 +2,7 @@
 import { readFileSync } from 'fs';
 import { resolve } from 'path';
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
+import { transform } from '../src/index.js';
 
 describe('transform', () => {
   it('given a file with edge-case header names', () => {

__tests__/transform.test.ts

@@ -1,8 +1,8 @@
 /* eslint-disable no-magic-numbers */
 import { describe, expect, it } from 'vitest';
-import { transform } from '../src';
-import { OPENING_COMMENT, CLOSING_COMMENT } from '../src';
-import { getLinesToToc, matchesStart, matchesEnd } from '../src/lib/transform';
+import { transform } from '../src/index.js';
+import { OPENING_COMMENT, CLOSING_COMMENT } from '../src/index.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);
+  });
+});

__tests__/utils.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable no-magic-numbers */
 import { describe, expect, it } from 'vitest';
-import { replaceVariables } from '../src/lib/utils';
+import { replaceVariables } from '../src/lib/utils.js';
 
 describe('replaceVariables', () => {
   it('should replace variables', () => {

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;