rehype-custom-toc 0.0.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +126 -122
  3. package/package.json +4 -1
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 roboin
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 roboin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,122 +1,126 @@
1
- # rehype-custom-toc
2
-
3
- rehype plugin to generate a customizable table of contents.
4
-
5
- ## Installation
6
-
7
- ```bash
8
- npm install rehype-custom-toc
9
- ```
10
-
11
- ## Example
12
-
13
- ```javascript
14
- import remarkComment from "remark-comment";
15
- import remarkParse from "remark-parse";
16
- import remarkRehype from "remark-rehype";
17
- import rehypeCustomToc from "./index";
18
- import rehypeStringify from "rehype-stringify";
19
- import { unified } from "unified";
20
-
21
- /**
22
- * A comment node generated by the `remark-comment` plugin.
23
- */
24
- interface Comment extends Node {
25
- type: "comment";
26
- value: "";
27
- commentValue: string;
28
- }
29
-
30
- const processor = unified()
31
- .use(remarkParse)
32
- .use(remarkComment, {
33
- ast: true
34
- })
35
- .use(remarkRehype, {
36
- handlers: {
37
- /**
38
- * Convert a mdast comment node to a hast comment node.
39
- * @param _ State
40
- * @param node mdast comment node
41
- * @returns hast comment node
42
- */
43
- comment: (_, node: Comment) => ({
44
- type: "comment",
45
- value: node.commentValue
46
- })
47
- }
48
- })
49
- .use(rehypeCustomToc)
50
- .use(rehypeStringify);
51
-
52
- const markdown = `
53
- # Title
54
-
55
- This is a sample markdown paragraph.
56
-
57
- <!-- toc -->
58
-
59
- ## Section 1
60
-
61
- ### Subsection 1.1
62
- `;
63
-
64
- processor.process(markdown).then((result) => {
65
- console.log(result.toString());
66
- });
67
- ```
68
-
69
- The above code will output the following (formatted for readability):
70
-
71
- ```html
72
- <h1 id="title">Title</h1>
73
- <p>This is a sample markdown paragraph.</p>
74
- <aside class="toc">
75
- <h2>Contents</h2>
76
- <nav>
77
- <ul>
78
- <li><a href="#title">Title</a></li>
79
- <ul>
80
- <li><a href="#section-1">Section 1</a></li>
81
- <ul>
82
- <li><a href="#subsection-11">Subsection 1.1</a></li>
83
- </ul>
84
- </ul>
85
- </ul>
86
- </nav>
87
- </aside>
88
- <h2 id="section-1">Section 1</h2>
89
- <h3 id="subsection-11">Subsection 1.1</h3>
90
- ```
91
-
92
- ## Options
93
-
94
- ### `template`
95
-
96
- A function that takes the generated HTML and returns the final HTML. This can be used to wrap the generated HTML in a custom template.
97
-
98
- Default:
99
-
100
- ```javascript
101
- const defaultTemplate = (html) => {
102
- return `
103
- <aside class="toc">
104
- <h2>Contents</h2>
105
- <nav>
106
- ${html}
107
- </nav>
108
- </aside>`.trim();
109
- };
110
- ```
111
-
112
- ### `maxDepth`
113
-
114
- The maximum depth of headings to include in the table of contents.
115
-
116
- Default: `3`
117
-
118
- ### `ordered`
119
-
120
- Whether to use an ordered list (`<ol>`) or an unordered list (`<ul>`).
121
-
122
- Default: `false`
1
+ # rehype-custom-toc
2
+
3
+ rehype plugin to generate a customizable table of contents.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install rehype-custom-toc
9
+ ```
10
+
11
+ ## Example usage
12
+
13
+ The table of contents will be inserted at the location of the `<!-- toc -->` comment or at the beginning of the file if no comment is found.
14
+
15
+ When parsing HTML with rehype, the `<!-- toc -->` comment is preserved as-is, but when converting from Markdown you need to convert Markdown comments to HTML comments (as shown below with `remark-comment`) so rehype-custom-toc can detect the ToC marker.
16
+
17
+ ```typescript
18
+ import remarkComment from "remark-comment";
19
+ import remarkParse from "remark-parse";
20
+ import remarkRehype from "remark-rehype";
21
+ import rehypeCustomToc from "rehype-custom-toc";
22
+ import rehypeStringify from "rehype-stringify";
23
+ import { unified } from "unified";
24
+
25
+ /**
26
+ * A comment node generated by the `remark-comment` plugin.
27
+ */
28
+ interface Comment extends Node {
29
+ type: "comment";
30
+ value: "";
31
+ commentValue: string;
32
+ }
33
+
34
+ const processor = unified()
35
+ .use(remarkParse)
36
+ .use(remarkComment, {
37
+ ast: true
38
+ })
39
+ .use(remarkRehype, {
40
+ handlers: {
41
+ /**
42
+ * Convert a mdast comment node to a hast comment node.
43
+ * @param _ State
44
+ * @param node mdast comment node
45
+ * @returns hast comment node
46
+ */
47
+ comment: (_, node: Comment) => ({
48
+ type: "comment",
49
+ value: node.commentValue
50
+ })
51
+ }
52
+ })
53
+ .use(rehypeCustomToc)
54
+ .use(rehypeStringify);
55
+
56
+ const markdown = `
57
+ # Title
58
+
59
+ This is a sample markdown paragraph.
60
+
61
+ <!-- toc -->
62
+
63
+ ## Section 1
64
+
65
+ ### Subsection 1.1
66
+ `;
67
+
68
+ processor.process(markdown).then((result) => {
69
+ console.log(result.toString());
70
+ });
71
+ ```
72
+
73
+ The above code will output the following (formatted for readability):
74
+
75
+ ```html
76
+ <h1 id="title">Title</h1>
77
+ <p>This is a sample markdown paragraph.</p>
78
+ <aside class="toc">
79
+ <h2>Contents</h2>
80
+ <nav>
81
+ <ul>
82
+ <li><a href="#title">Title</a></li>
83
+ <ul>
84
+ <li><a href="#section-1">Section 1</a></li>
85
+ <ul>
86
+ <li><a href="#subsection-11">Subsection 1.1</a></li>
87
+ </ul>
88
+ </ul>
89
+ </ul>
90
+ </nav>
91
+ </aside>
92
+ <h2 id="section-1">Section 1</h2>
93
+ <h3 id="subsection-11">Subsection 1.1</h3>
94
+ ```
95
+
96
+ ## Options
97
+
98
+ ### `template`
99
+
100
+ A function that takes the generated HTML and returns the final HTML. This can be used to wrap the generated HTML in a custom template.
101
+
102
+ Default:
103
+
104
+ ```javascript
105
+ const defaultTemplate = (html) => {
106
+ return `
107
+ <aside class="toc">
108
+ <h2>Contents</h2>
109
+ <nav>
110
+ ${html}
111
+ </nav>
112
+ </aside>`.trim();
113
+ };
114
+ ```
115
+
116
+ ### `maxDepth`
117
+
118
+ The maximum depth of headings to include in the table of contents.
119
+
120
+ Default: `3`
121
+
122
+ ### `ordered`
123
+
124
+ Whether to use an ordered list (`<ol>`) or an unordered list (`<ul>`).
125
+
126
+ Default: `false`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rehype-custom-toc",
3
- "version": "0.0.0",
3
+ "version": "1.0.0",
4
4
  "description": "rehype plugin to generate a customizable table of contents",
5
5
  "keywords": [
6
6
  "rehype",
@@ -26,6 +26,9 @@
26
26
  "files": [
27
27
  "dist"
28
28
  ],
29
+ "publishConfig": {
30
+ "provenance": true
31
+ },
29
32
  "scripts": {
30
33
  "test": "cross-env NODE_ENV=\"production\" vitest",
31
34
  "lint": "eslint --flag unstable_native_nodejs_ts_config \"./src/**/*.ts\"",