markdown-toc.cjs

/* eslint-disable */

const fs = require("fs");
const path = require("path");
const glob = require("glob");

/* What this script does
 *
 * - creates a list of all files with the ".md" ending (checkAllMarkdownFiles)
 * - checks if the `<!-- auto-generated-toc-start -->` and `<!-- auto-generated-toc-end-->`
 *   are marking the place where the TOC should go (tocShouldBeGenerated)
 * - in files with that comments, it creates a list of links as TOC (generateTOC)
 */

// Marks the beginning where the TOC should go
const tocStartComment = "<!-- auto-generated-toc-start -->";

// Marks the end of the TOC
const tocEndComment = "<!-- auto-generated-toc-end -->";

function tocShouldBeGenerated(markdownContent, fileName) {
  const hasAutoTocStartComment = markdownContent.includes(tocStartComment);
  const hasAutoTocEndComment = markdownContent.includes(tocEndComment);

  if (!hasAutoTocStartComment && !hasAutoTocEndComment) {
    return false;
  }

  if (hasAutoTocStartComment && !hasAutoTocEndComment) {
    console.log(
      `\n ⚠️  File ${fileName}:\n    Found ${tocStartComment} but no ${tocEndComment}.\n`
    );
    return false;
  }

  if (!hasAutoTocStartComment && hasAutoTocEndComment) {
    console.log(
      `\n ⚠️  File ${fileName}:\n    Found ${tocEndComment} but no ${tocStartComment}.\n`
    );
    return false;
  }
  return true;
}

function checkAllMarkdownFiles() {
  // Get all Markdown files in the current directory and its subdirectories
  const files = glob.sync(["**/*.md", "../**/*.md"], {
    cwd: process.cwd(),
    ignore: ["**/node_modules/**", ".git/**"],
    nodir: true,
    absolute: true,
    dot: true,
  });

  console.log(`🤖 checking file: `);
  files.forEach((fileName) => {
    console.log(`\n- ${fileName}`);
    const markdownContent = fs.readFileSync(fileName, "utf-8");

    if (tocShouldBeGenerated(markdownContent, fileName)) {
      generateTOC(fileName, markdownContent);
    } else {
      console.log("No comment to autogenerate TOC found.");
    }
  });
  console.log(
    `\n 🏁 Finished check for autogenerated TOC for ${files.length} files.\n`
  );
}

function checkSingleMarkdownFile(targetFile) {
  const fileName = path.resolve(targetFile);
  const markdownContent = fs.readFileSync(fileName, "utf-8");

  if (tocShouldBeGenerated(markdownContent, fileName)) {
    generateTOC(fileName, markdownContent);
  } else {
    console.log("No comment to autogenerate TOC found.");
  }
}

function generateTOC(fileName, markdownContent) {
  const existingTocStartIndex = markdownContent.indexOf(tocStartComment);
  const existingTocEndIndex = markdownContent.indexOf(tocEndComment);

  const tocHeading = "## Table of Contents";

  const toc = [];
  let isFirstHeading = true;

  // Regular expression to match Markdown headings
  const headingRegex = /^(#{1,6})\s+(.+)$/gm;

  let match;
  while ((match = headingRegex.exec(markdownContent)) !== null) {
    const headingLevelSigns = match[1];
    const headingLevel = headingLevelSigns.length;
    const headingContent = match[2];

    if (headingLevel === 1 && isFirstHeading) {
      // Skip the first heading with level 1
      isFirstHeading = false;
      continue;
    }

    // check if the heading is the autogenerated one,
    // if yes, do not continue with this loop
    if (`${headingLevelSigns} ${headingContent}` === tocHeading) {
      continue;
    }

    toc.push({
      level: headingLevel,
      content: headingContent,
    });

    isFirstHeading = false;
  }

  // Generate Table of Contents with proper indentation
  const tocList = toc
    .map((entry) => {
      const linkContent = entry.content
        .replace(/\[([^\]]+)\]\(.+?\)/, "$1")
        .trim();

      // Remove non-alphanumeric characters (except hyphens) for links
      const link = linkContent
        .toLowerCase()
        .replace(/\s+/g, "-")
        .replace(/^[^a-zA-Z0-9]+/, "")
        .replace(/[^a-zA-Z0-9- ]/g, "");

      const indentation = "  ".repeat(Math.max(entry.level - 2, 0));

      return `${indentation}- [${linkContent}](#${link})`;
    })
    .join("\n");

  try {
    // If there's an existing TOC, replace it with the updated one.
    if (existingTocStartIndex !== -1 && existingTocEndIndex !== -1) {
      const beforeToc = markdownContent.substring(0, existingTocStartIndex);
      const afterToc = markdownContent.substring(
        existingTocEndIndex + tocEndComment.length
      );
      fs.writeFileSync(
        fileName,
        `${beforeToc}${tocStartComment}\n\n${tocHeading}\n\n${tocList}\n\n${tocEndComment}${afterToc}`,
        "utf-8"
      );
    } else {
      // Otherwise, add the TOC based on the location of comments.
      fs.appendFileSync(
        fileName,
        `\n${tocStartComment}\n${tocHeading}\n\n${tocList}\n\n${tocEndComment}`,
        "utf-8"
      );
    }

    console.log(
      `✅ Table of Contents added/updated in ${path.relative(
        process.cwd(),
        fileName
      )}.`
    );
  } catch (error) {
    console.error(
      `Error writing to ${path.relative(process.cwd(), fileName)}:`,
      error
    );
  }
}

const targetFileArgIndex = process.argv.indexOf("-f");
if (targetFileArgIndex !== -1) {
  const targetFile = process.argv[targetFileArgIndex + 1];
  if (!targetFile) {
    console.error("⛔️ ERROR: Please provide a file path with -f flag.");
    return;
  }

  if (path.extname(targetFile) !== ".md") {
    console.error(
      "⛔️ ERROR: The file specified with -f must have the .md extension."
    );
    return;
  }
  console.log(`🤖 Checking file: ${targetFile}`);
  checkSingleMarkdownFile(targetFile);
} else {
  checkAllMarkdownFiles();
}