ext-apps/scripts/typedoc-plugin-seo.mjs

/**
 * TypeDoc plugin that adds SEO metadata to generated pages.
 *
 * - Normalizes document page filenames to lowercase-hyphenated slugs
 * - Injects JSON-LD (TechArticle / WebPage) structured data for search crawlers
 * - Adds per-page meta description tags extracted from page content
 * - Copies favicons to the output directory
 */

import { Renderer } from "typedoc";
import fs from "node:fs";
import path from "node:path";
import zlib from "node:zlib";
import * as htmlparser2 from "htmlparser2";

const SITE_NAME = "MCP Apps";

/**
 * Convert a TypeDoc-generated document filename to a lowercase hyphenated slug.
 * e.g. "CSP_and_CORS.html" → "csp-and-cors.html"
 *      "Testing_MCP_Apps.html" → "testing-mcp-apps.html"
 * @param {string} filename
 * @returns {string}
 */
function toSlug(filename) {
  return filename
    .replace(/\.html$/, "")
    .replace(/_/g, "-")
    .toLowerCase()
    .concat(".html");
}

/**
 * Extract a plain-text description from the rendered HTML body.
 * Parses the first content paragraph using htmlparser2 and truncates.
 * @param {string} html
 * @returns {string}
 */
function extractDescription(html) {
  // Find the main content area
  const contentMatch = html.match(
    /<div class="tsd-panel tsd-typography">([\s\S]*?)<\/div>\s*<\/div>/,
  );
  if (!contentMatch) return "";

  const content = contentMatch[1];

  // Find first <p> that has real content (skip headings, code blocks, lists)
  const paragraphs = content.match(/<p>([^<][\s\S]*?)<\/p>/g);
  if (!paragraphs) return "";

  for (const p of paragraphs) {
    const text = htmlparser2
      .parseDocument(p)
      .children.map((node) => htmlparser2.DomUtils.textContent(node))
      .join("")
      .replace(/\s+/g, " ")
      .trim();

    // Skip very short or code-heavy paragraphs
    if (text.length > 40) {
      return text.length > 160 ? text.slice(0, 157) + "..." : text;
    }
  }

  return "";
}

/**
 * Extract the page title from the <title> tag.
 * @param {string} html
 * @returns {string}
 */
function extractTitle(html) {
  const match = html.match(/<title>([^<]+)<\/title>/);
  return match ? match[1] : SITE_NAME;
}

/**
 * Determine if a page is a document (guide) or API reference page.
 * @param {string} url
 * @returns {boolean}
 */
function isDocumentPage(url) {
  return url.includes("documents/");
}

/**
 * Build a JSON-LD structured data object for the page.
 * @param {object} options
 * @param {string} options.title
 * @param {string} options.description
 * @param {string} options.url
 * @param {boolean} options.isDocument
 * @returns {object}
 */
function buildJsonLd({ title, description, url, isDocument }) {
  return {
    "@context": "https://schema.org",
    "@type": isDocument ? "TechArticle" : "WebPage",
    name: title,
    headline: title,
    ...(description && { description }),
    ...(url && { url }),
    isPartOf: {
      "@type": "WebSite",
      name: SITE_NAME,
      url: "https://apps.extensions.modelcontextprotocol.io/",
    },
  };
}

/**
 * TypeDoc plugin entry point.
 * @param {import('typedoc').Application} app
 */
export function load(app) {
  const hostedBaseUrl = app.options.getValue("hostedBaseUrl") || "";

  // --- Per-page: inject JSON-LD, meta descriptions, and favicons ---
  app.renderer.on(Renderer.EVENT_END_PAGE, (page) => {
    if (!page.contents) return;

    const title = extractTitle(page.contents);

    // Prefer frontmatter description, fall back to auto-extraction
    const frontmatterDesc =
      page.model?.isDocument?.() && page.model.frontmatter?.description
        ? String(page.model.frontmatter.description)
        : "";
    const description = frontmatterDesc || extractDescription(page.contents);
    const fullUrl = hostedBaseUrl
      ? `${hostedBaseUrl.replace(/\/$/, "")}/${page.url}`
      : "";

    // Build JSON-LD
    const jsonLd = buildJsonLd({
      title,
      description,
      url: fullUrl,
      isDocument: isDocumentPage(page.url),
    });

    const jsonLdScript = `<script type="application/ld+json">${JSON.stringify(jsonLd)}</script>`;

    // Build meta description tag (replace the generic one if present)
    const metaDescription = description
      ? `<meta name="description" content="${description.replace(/"/g, "&quot;")}"/>`
      : "";

    // Replace existing generic meta description
    if (metaDescription) {
      page.contents = page.contents.replace(
        /<meta name="description" content="Documentation for [^"]*"\/>/,
        metaDescription,
      );
    }

    // Build favicon tags with correct relative path
    const depth = page.url.split("/").length - 1;
    const base = depth > 0 ? "../".repeat(depth) : "./";
    const faviconTags = [
      `<link rel="icon" href="${base}favicons/favicon-32x32.png" type="image/png" sizes="32x32" media="(prefers-color-scheme: light)"/>`,
      `<link rel="icon" href="${base}favicons/favicon-16x16.png" type="image/png" sizes="16x16" media="(prefers-color-scheme: light)"/>`,
      `<link rel="shortcut icon" href="${base}favicons/favicon.ico" type="image/x-icon" media="(prefers-color-scheme: light)"/>`,
      `<link rel="icon" href="${base}favicons/favicon-dark-32x32.png" type="image/png" sizes="32x32" media="(prefers-color-scheme: dark)"/>`,
      `<link rel="icon" href="${base}favicons/favicon-dark-16x16.png" type="image/png" sizes="16x16" media="(prefers-color-scheme: dark)"/>`,
      `<link rel="shortcut icon" href="${base}favicons/favicon-dark.ico" type="image/x-icon" media="(prefers-color-scheme: dark)"/>`,
      `<link rel="apple-touch-icon" href="${base}favicons/apple-touch-icon.png" type="image/png" sizes="180x180"/>`,
    ].join("\n");

    // Inject favicons and JSON-LD before </head>
    const headInjections = [faviconTags, jsonLdScript]
      .filter(Boolean)
      .join("\n");

    page.contents = page.contents.replace(
      "</head>",
      headInjections + "\n</head>",
    );
  });

  // --- Post-render: copy favicons + rename document slugs ---
  app.renderer.on(Renderer.EVENT_END, (event) => {
    const outDir = event.outputDirectory;

    // Copy favicons to output directory
    const srcFavicons = path.join(path.dirname(outDir), "favicons");
    const destFavicons = path.join(outDir, "favicons");
    if (fs.existsSync(srcFavicons)) {
      if (!fs.existsSync(destFavicons)) fs.mkdirSync(destFavicons);
      for (const file of fs.readdirSync(srcFavicons)) {
        fs.copyFileSync(
          path.join(srcFavicons, file),
          path.join(destFavicons, file),
        );
      }
    }

    const docsDir = path.join(outDir, "documents");

    if (!fs.existsSync(docsDir)) return;

    // Build rename map: old filename → new slug
    const renameMap = new Map();
    for (const file of fs.readdirSync(docsDir)) {
      if (!file.endsWith(".html")) continue;
      const slug = toSlug(file);
      if (slug !== file) {
        renameMap.set(file, slug);
      }
    }

    if (renameMap.size === 0) return;

    // Rename the files
    for (const [oldName, newName] of renameMap) {
      fs.renameSync(path.join(docsDir, oldName), path.join(docsDir, newName));
    }

    // Build link replacement patterns (documents/OldName.html → documents/new-name.html)
    const replacements = [...renameMap.entries()].map(([oldName, newName]) => ({
      old: `documents/${oldName}`,
      new: `documents/${newName}`,
    }));

    // Update all HTML files in the output directory
    updateLinksRecursive(outDir, replacements);

    // Update compressed JS data files (navigation + search index)
    updateCompressedJsData(
      path.join(outDir, "assets", "navigation.js"),
      "navigationData",
      replacements,
    );
    updateCompressedJsData(
      path.join(outDir, "assets", "search.js"),
      "searchData",
      replacements,
    );

    // Update sitemap.xml
    const sitemapPath = path.join(outDir, "sitemap.xml");
    if (fs.existsSync(sitemapPath)) {
      let sitemap = fs.readFileSync(sitemapPath, "utf8");
      for (const r of replacements) {
        sitemap = sitemap.replaceAll(r.old, r.new);
      }
      fs.writeFileSync(sitemapPath, sitemap);
    }
  });
}

/**
 * Decompress a TypeDoc JS data file, replace document slugs, and recompress.
 * TypeDoc stores navigation and search data as deflate-compressed base64.
 * @param {string} filePath
 * @param {string} varName - JS variable name (e.g. "navigationData", "searchData")
 * @param {Array<{old: string, new: string}>} replacements
 */
function updateCompressedJsData(filePath, varName, replacements) {
  if (!fs.existsSync(filePath)) return;

  let content = fs.readFileSync(filePath, "utf8");
  const pattern = new RegExp(`window\\.${varName} = "(.+)"`);
  const match = content.match(pattern);
  if (!match) return;

  // Decompress
  const buf = Buffer.from(match[1], "base64");
  let json = zlib.inflateSync(buf).toString();

  // Replace slugs
  let changed = false;
  for (const r of replacements) {
    if (json.includes(r.old)) {
      json = json.replaceAll(r.old, r.new);
      changed = true;
    }
  }

  if (!changed) return;

  // Recompress and write
  const compressed = zlib.deflateSync(json);
  const encoded = compressed.toString("base64");
  content = content.replace(pattern, `window.${varName} = "${encoded}"`);
  fs.writeFileSync(filePath, content);
}

/**
 * Recursively update links in all HTML files under a directory.
 * @param {string} dir
 * @param {Array<{old: string, new: string}>} replacements
 */
function updateLinksRecursive(dir, replacements) {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      updateLinksRecursive(fullPath, replacements);
    } else if (entry.name.endsWith(".html") || entry.name.endsWith(".js")) {
      let content = fs.readFileSync(fullPath, "utf8");
      let changed = false;
      for (const r of replacements) {
        if (content.includes(r.old)) {
          content = content.replaceAll(r.old, r.new);
          changed = true;
        }
      }
      if (changed) {
        fs.writeFileSync(fullPath, content);
      }
    }
  }
}