astro-custom-toc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ろぼいん
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# astro-custom-toc
+
+Astro Integration to generate a customizable table of contents.
+
+> [!WARNING]
+> This plugin uses [remark-comment](https://github.com/leebyron/remark-comment). It may break other plug-ins that use comments.
+
+## Installation
+
+```bash
+npx astro add astro-custom-toc
+```
+
+### Manual Install
+
+Install the package
+
+```bash
+npm install astro-custom-toc
+```
+
+Add the plugin to your `astro.config.mjs`. **This plugin must be inserted before the [mdx()](https://github.com/withastro/astro/tree/main/packages/integrations/mdx/) plugin if you are using it.**
+
+```javascript
+import { defineConfig } from "astro/config";
+import { remarkCustomToc } from "./src/plugins/remark-toc";
+
+// https://astro.build/config
+export default defineConfig({
+    // ... other config
+    integrations: [remarkCustomToc(), mdx()]
+});
+```
+
+## Usage
+
+To include a table of contents in your markdown file, add ``showToc: true`` to the frontmatter of the markdown file. 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.
+
+```markdown
+---
+showToc: true
+---
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+<!-- toc -->
+
+## Section 1
+
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+### Subsection 1.1
+
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+```
+
+## Options
+
+```typescript
+type RemarkCustomTocTemplate = (html: string) => string;
+
+interface RemarkCustomTocOptions {
+    template?: RemarkCustomTocTemplate;
+    maxDepth?: number;
+    ordered?: boolean;
+}
+```
+
+### `template`
+
+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.
+
+Default:
+
+```javascript
+const defaultTemplate = (html) => {
+    return `
+<aside class="toc">
+    <h2>Contents</h2>
+    <nav>
+        ${html}
+    </nav>
+</aside>`.trim();
+};
+```
+
+### `maxDepth`
+
+The maximum depth of headings to include in the table of contents.
+
+Default: `3`
+
+### `ordered`
+
+Whether to use an ordered list (`<ol>`) or an unordered list (`<ul>`).
+
+Default: `false`

package/index.ts

@@ -0,0 +1,44 @@
+import type { AstroConfig, AstroIntegration } from "astro";
+import { remarkCustomToc, RemarkCustomTocOptions } from "./remark-custom-toc";
+import remarkComment from "remark-comment";
+
+const astroCustomToc = (options?: RemarkCustomTocOptions) => {
+    const integration: AstroIntegration = {
+        name: "astro-custom-toc",
+        hooks: {
+            "astro:config:setup": ({ config, updateConfig }) => {
+                checkOrder(config);
+                updateConfig({
+                    markdown: {
+                        remarkPlugins: [
+                            [
+                                remarkComment,
+                                {
+                                    ast: true
+                                }
+                            ],
+                            [remarkCustomToc, options]
+                        ]
+                    }
+                });
+            }
+        }
+    };
+
+    return integration;
+};
+
+const checkOrder = (config: AstroConfig) => {
+    const customTocIndex = config.integrations.findIndex((i) => i.name === "astro-custom-toc");
+    const mdxIndex = config.integrations.findIndex((i) => i.name === "@astrojs/mdx");
+    if (mdxIndex > -1 && customTocIndex > mdxIndex) {
+        throw new Error(
+            `
+MDX integration configured before astro-custom-toc.
+\`astroCustomToc()\` must be loaded before \`mdx()\`.
+`.trim()
+        );
+    }
+};
+
+export default astroCustomToc;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "astro-custom-toc",
+  "version": "1.0.0",
+  "description": "Astro Integration to generate a customizable table of contents",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "remark-custom-toc.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Robot-Inventor/astro-custom-toc.git"
+  },
+  "keywords": [
+    "astro",
+    "remark",
+    "markdown",
+    "astro-integration"
+  ],
+  "author": "Robot-Inventor",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Robot-Inventor/astro-custom-toc/issues"
+  },
+  "homepage": "https://github.com/Robot-Inventor/astro-custom-toc#readme",
+  "dependencies": {
+    "github-slugger": "^2.0.0",
+    "jsdom": "^24.0.0",
+    "remark-comment": "^1.0.0",
+    "typescript": "^5.3.3",
+    "unist-util-visit": "^5.0.0"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^21.1.6"
+  }
+}

package/remark-custom-toc.ts

@@ -0,0 +1,139 @@
+import type { AstroUserConfig } from "astro";
+import { visit } from "unist-util-visit";
+import Slugger from "github-slugger";
+import { JSDOM } from "jsdom";
+
+interface Heading {
+    slug: string;
+    text: string;
+    depth: number;
+}
+
+export type RemarkCustomTocTemplate = (html: string) => string;
+
+export interface RemarkCustomTocOptions {
+    template?: RemarkCustomTocTemplate;
+    maxDepth?: number;
+    ordered?: boolean;
+}
+
+type RemarkPlugin = NonNullable<NonNullable<AstroUserConfig["markdown"]>["remarkPlugins"]>[number];
+
+interface VFile {
+    data: {
+        astro?: {
+            frontmatter: Record<string, any>;
+        };
+    };
+}
+
+interface CommentNode {
+    type: "comment";
+    value: "";
+    commentValue: string;
+}
+
+const defaultTemplate = (html: string) => {
+    return `
+<aside class="toc">
+    <h2>Contents</h2>
+    <nav>
+        ${html}
+    </nav>
+</aside>`.trim();
+};
+
+export const remarkCustomToc: RemarkPlugin = ({
+    template = defaultTemplate,
+    maxDepth = 3,
+    ordered = false
+}: RemarkCustomTocOptions = {}) => {
+    return (tree, { data }: VFile) => {
+        if (data.astro && data.astro.frontmatter.showToc !== true) return;
+
+        const slugs = new Slugger();
+        slugs.reset();
+
+        const headings: Heading[] = [];
+        visit(tree, "heading", (node) => {
+            const { depth } = node;
+            const textNode = node.children[0];
+            // @ts-ignore
+            const text = textNode ? textNode.value : "";
+            const slug = slugs.slug(text);
+            // @ts-ignore
+            node.data = { id: slug };
+            headings.push({ slug, text, depth });
+        });
+
+        let tocIndex = 0;
+        visit(tree, "comment", (node: CommentNode, index) => {
+            if (node.commentValue.trim().toLowerCase() === "toc" && index !== undefined) {
+                tocIndex = index;
+            }
+        });
+
+        visit(tree, "html", (node, index) => {
+            if (node.value.trim().toLowerCase() === "<!-- toc -->" && index !== undefined) {
+                tocIndex = index;
+            }
+        });
+
+        const toc = generateToc(template, maxDepth, ordered, headings);
+        if (tocIndex === 0) {
+            // @ts-ignore
+            tree.children.unshift(toc);
+        } else {
+            // @ts-ignore
+            tree.children.splice(tocIndex, 1, toc);
+        }
+    };
+};
+
+const generateToc = (template: RemarkCustomTocTemplate, maxDepth: number, ordered: boolean, headings: Heading[]) => {
+    const { document } = new JSDOM().window;
+
+    const toc: HTMLElement = document.createElement(ordered ? "ol" : "ul");
+    let currentDepth = 2;
+    let currentParent = toc;
+    for (const heading of headings) {
+        if (heading.depth > maxDepth) continue;
+
+        if (heading.depth === currentDepth) {
+            const li = document.createElement("li");
+            const a = document.createElement("a");
+            a.href = `#${heading.slug}`;
+            a.textContent = heading.text;
+            li.appendChild(a);
+            currentParent.appendChild(li);
+            currentDepth = heading.depth;
+        } else if (heading.depth > currentDepth) {
+            const ul = document.createElement(ordered ? "ol" : "ul");
+            const li = document.createElement("li");
+            const a = document.createElement("a");
+            a.href = `#${heading.slug}`;
+            a.textContent = heading.text;
+            li.appendChild(a);
+            ul.appendChild(li);
+            currentParent.appendChild(ul);
+            currentParent = ul;
+            currentDepth = heading.depth;
+        } else {
+            for (let i = 0; i < currentDepth - heading.depth; i++) {
+                currentParent = currentParent.parentElement!;
+            }
+            const li = document.createElement("li");
+            const a = document.createElement("a");
+            a.href = `#${heading.slug}`;
+            a.textContent = heading.text;
+            li.appendChild(a);
+            currentParent.appendChild(li);
+            currentDepth = heading.depth;
+        }
+    }
+
+    return {
+        type: "html",
+        value: template(toc.outerHTML)
+    };
+};