0.9.0 omit headlines from toc (fixes #65)

CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2025-01-21
+
+* **Added:** Headlines can now be omitted from the table of contents by placing a special HTML comment tag before the headline (fixes #65).
+* **Added:** Option `omitTag` can override the default tag `<!-- omit from toc -->`
+
+***
+
 ## [0.8.0] - 2024-09-10
 
 * **Added:** Option `getTokensText` to override how text is extracted from tokens to build headlines and slugs (fixes #61), similar to the function in [markdown-it-anchor](https://www.npmjs.com/package/markdown-it-anchor).

README.md

@@ -70,6 +70,7 @@ Name                   | Description
 `containerClass`       | The class for the container DIV                                                     | "table-of-contents"
 `slugify`              | A custom slugification function                                                     | `encodeURIComponent(String(s).trim().toLowerCase().replace(/\s+/g, '-'))`
 `markerPattern`        | Regex pattern of the marker to be replaced with TOC                                 | `/^\[\[toc\]\]/im`
+`omitTag`			   | HTML comment tag to exclude next headline from TOC									 | `<!-- omit from toc -->`
 `listType`             | Type of list (`ul` for unordered, `ol` for ordered)                                 | `ul`
 `format`               | A function for formatting headings (see below)                                      | `md.renderInline(content)`
 `containerHeaderHtml`  | Optional HTML string for container header                                           | `undefined`
@@ -219,6 +220,23 @@ HTML output:
 <h4 id="related">See related articles</h4>
 ```
 
+## Example for omitting headlines from the TOC
+
+If you want to exclude single headlines, you can use a special HTML comment to omit the next headline from the TOC:
+
+```markdown
+<!-- omit from toc -->
+# Title
+```
+
+For this to work, the HTML comment must come right in the line before the headline you want to exclude. Furthermore, you need to allow HTML in MarkdownIT:
+
+```js
+const md = new MarkdownIt({ html: true });
+```
+
+You can override the HTML comment by using the option `omitTag` as explained above. Both, the tag and the actual comment in the Markdown file are case-insensitive.
+
 ## Additional infos
 
 * This plugin outputs a semantically correct table of contents. Sub-lists are rendered within the parent `<li>` tag and not as a separate (empty) `<li>`.

index.js

@@ -35,6 +35,7 @@ const defaultOptions = {
     containerClass: 'table-of-contents',
     slugify: slugify,
     markerPattern: /^\[\[toc\]\]/im,
+	omitTag: '<!-- omit from toc -->',
     listType: 'ul',
     format: function (content, md) {
         return md.renderInline(content);
@@ -85,9 +86,13 @@ function findHeadlineElements(levels, tokens, options) {
     const headings = [];
     let currentHeading = null;
 
-    tokens.forEach(token => {
+    tokens.forEach((token, index) => {
         if (token.type === 'heading_open') {
-            const id = findExistingIdAttr(token);
+            const prev = index > 0 ? tokens[index-1] : null;
+			if (prev && prev.type === 'html_block' && prev.content.trim().toLowerCase().replace('\n', '') === options.omitTag) {
+				return;
+			}
+			const id = findExistingIdAttr(token);
             const level = parseInt(token.tag.toLowerCase().replace('h', ''), 10);
             if (levels.indexOf(level) >= 0) {
                 currentHeading = {