Merge pull request #138 from jannis-baum/issue/137-add-toc-support-fo…

…r-markdown

Add TOC support for Markdown

README.md

@@ -28,12 +28,15 @@ issue](https://github.com/jannis-baum/vivify/issues/new/choose) or
   [extended](https://www.markdownguide.org/extended-syntax/) syntax support
 - [KaTeX math](https://katex.org)
 - [graphviz/dot graphs](https://graphviz.org/doc/info/lang.html)
-- `<kbd>` tags, e.g. to style keyboard shortcuts
+- [GitHub alert
+  blocks](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
 - links to other files: [relative links like in
   GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links)
   as well as absolute file links
 - [add styles, classes, ids or other attributes directly from
   Markdown](https://github.com/arve0/markdown-it-attrs?tab=readme-ov-file#examples)
+- table of contents with `[[toc]]`
+- `<kbd>` tags, e.g. to style keyboard shortcuts
 
 You can find examples for all supported features in the files in the
 [`tests/`](tests) directory. In case you are looking at these on GitHub, keep in

docs/customization.md

@@ -26,18 +26,6 @@ following optional keys:
   How long the server should wait in milliseconds before shutting down after the
   last client disconnected; this will be overwritten by the environment variable
   `VIV_TIMEOUT` (default is 10000)
-- **`"katexOptions"`**\
-  [Available KaTeX options](https://katex.org/docs/options.html), such as
-
-  ```json
-  {
-    "errorColor": "#cc0000",
-    "macros": {
-      "\\RR": "\\mathbb{R}"
-    }
-  }
-  ```
-
 - **`"pageTitle"`**\
   JavaScript code that will be evaluated to determine the viewer's page title.
   Here, the variable `components` is set to a string array of path components
@@ -53,3 +41,25 @@ following optional keys:
 - **`"preferHomeTilde"`**\
   Prefer using `~` as a placeholder for your home directory in URLs as well as
   the `components` for `"pageTitle"` (default is `true`)
+- **`"katexOptions"`**\
+  [Available KaTeX options](https://katex.org/docs/options.html), such as
+
+  ```json
+  {
+    "errorColor": "#cc0000",
+    "macros": {
+      "\\RR": "\\mathbb{R}"
+    }
+  }
+  ```
+
+- **`"tocOptions"`**\
+  [Available options for the table of
+  contents](https://www.npmjs.com/package/markdown-it-table-of-contents?activeTab=readme#options),
+  such as
+
+  ```json
+  {
+    "includeLevel": [2, 3]
+  }
+  ```

package.json

@@ -27,6 +27,7 @@
     "markdown-it-mark": "^4.0.0",
     "markdown-it-sub": "^2.0.0",
     "markdown-it-sup": "^2.0.0",
+    "markdown-it-table-of-contents": "^0.6.0",
     "markdown-it-task-lists": "^2.1.1",
     "markdown-it-texmath": "^1.0.0",
     "node-stream-zip": "^1.15.0",

src/parser/config.ts

@@ -8,11 +8,14 @@ type Config = {
     dirListIgnore?: string[];
     port: number;
     timeout: number;
-    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-    katexOptions?: any;
     pageTitle?: string;
     mdExtensions: string[];
     preferHomeTilde: boolean;
+    // markdown-it plugin options
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    katexOptions?: any;
+    tocOptions?: any;
+    /* eslint-enable @typescript-eslint/no-explicit-any */
 };
 
 const defaultConfig: Config = {

src/parser/markdown.ts

@@ -52,6 +52,9 @@ mdit.use(mark);
 /* @ts-expect-error: module not typed */
 import attributes from 'markdown-it-attrs';
 mdit.use(attributes);
+/* @ts-expect-error: module not typed */
+import toc from 'markdown-it-table-of-contents';
+mdit.use(toc, config.tocOptions);
 
 // MARK: untyped plugins done
 

tests/markdown-additional.md

@@ -1,6 +1,8 @@
 # Additional Markdown test file
 
-Test various other Markdown syntax here.
+Test various other Markdown syntax here, starting with the table of contents
+
+[[toc]]
 
 ## Relative file link
 

yarn.lock

@@ -1787,6 +1787,11 @@ markdown-it-sup@^2.0.0:
   resolved "https://registry.yarnpkg.com/markdown-it-sup/-/markdown-it-sup-2.0.0.tgz#683b9390929f3024fcd5291799c466ce3d367f44"
   integrity sha512-5VgmdKlkBd8sgXuoDoxMpiU+BiEt3I49GItBzzw7Mxq9CxvnhE/k09HFli09zgfFDRixDQDfDxi0mgBCXtaTvA==
 
+markdown-it-table-of-contents@^0.6.0:
+  version "0.6.0"
+  resolved "https://registry.yarnpkg.com/markdown-it-table-of-contents/-/markdown-it-table-of-contents-0.6.0.tgz#7c9e8d619fb12f88c9fb05a7b32b2fe932b9c541"
+  integrity sha512-jHvEjZVEibyW97zEYg19mZCIXO16lHbvRaPDkEuOfMPBmzlI7cYczMZLMfUvwkhdOVQpIxu3gx6mgaw46KsNsQ==
+
 markdown-it-task-lists@^2.1.1:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/markdown-it-task-lists/-/markdown-it-task-lists-2.1.1.tgz#f68f4d2ac2bad5a2c373ba93081a1a6848417088"