fix(docs): eliminate broken-link build warnings (#7)

* fix(docs): eliminate broken-link warnings

- Filter nav helpers to products with generated docs (drops broken
  /docs/block-mcp/ and /docs/gravitysearch/ links rendered on every page).
- Render @SInCE as plain text in the API and hooks generators; per-version
  since/<version>/ index pages are never generated, so the links 404'd.

* fix(docs): drop method anchors from @see cross-class links

An @see-referenced method is frequently not a rendered heading on the target
class page (not in its public set), so #method anchors 404. Link to the class
page (always exists). Eliminates the residual broken-anchor warnings.

Author: zackkatz

docusaurus.config.js

@@ -31,6 +31,11 @@ const products_with_docs = config_products
     return fs.existsSync(docsDir);
   });
 
+// Only link to products that actually have generated docs. Configured-but-docless
+// products (e.g. block-mcp, gravitysearch) otherwise produce broken nav links on
+// every page.
+const product_ids_with_docs = new Set(products_with_docs.map((p) => p.id));
+
 // Read actual plugin versions from repository files
 const product_versions = readAllProductVersions(config_products);
 
@@ -48,6 +53,7 @@ const categories = repos_config.categories || {};
 function getProductsByCategory(categoryId) {
   return config_products
     .filter((p) => p?.category === categoryId && p?.label && p?.id)
+    .filter((p) => product_ids_with_docs.has(p.id))
     .map((p) => ({
       label: p.label,
       href: `/docs/${p.id}/`,
@@ -58,6 +64,7 @@ function getProductsByCategory(categoryId) {
 function getFreeProducts() {
   return config_products
     .filter((p) => p?.isFree === true && p?.label && p?.id)
+    .filter((p) => product_ids_with_docs.has(p.id))
     .map((p) => ({
       label: p.label,
       href: `/docs/${p.id}/`,
@@ -68,6 +75,7 @@ function getFreeProducts() {
 function getThirdPartyProducts() {
   return config_products
     .filter((p) => p?.isThirdParty === true && p?.label && p?.id)
+    .filter((p) => product_ids_with_docs.has(p.id))
     .map((p) => ({
       label: p.label,
       href: `/docs/${p.id}/`,

scripts/generate-hooks.mjs

@@ -332,18 +332,9 @@ function addTagsToHooks(outputDir) {
           }
         }
 
-        // Convert Since section to use links to tag pages
-        // Replace "- 1.0" with "- [1.0](../../since/1-0/)"
-        // Path is ../../ because docs are in actions/ or filters/ subdirs
-        let newSinceSection = sinceMatch[0];
-        for (const tag of tags) {
-          const tagSlug = tag.replace(/\./g, '-');
-          newSinceSection = newSinceSection.replace(
-            new RegExp(`- ${tag.replace(/\./g, '\\.')}(?!\\])`, 'g'),
-            `- [${tag}](../../since/${tagSlug}/)`
-          );
-        }
-        content = content.replace(sinceMatch[0], newSinceSection);
+        // Leave the Since list as plain version numbers. Per-version "since"
+        // index pages are not generated, so linking to ../../since/<version>/
+        // produced broken links.
       }
 
       // Add tags to frontmatter if we have any

scripts/generate-php-api.mjs

@@ -1082,7 +1082,10 @@ function renderSeeAlsoSection(tags, typeLinkCtx, { heading = '##' } = {}) {
         const classUrl = resolveTypeUrl(className, typeLinkCtx);
         const methodRef = `\\${className}::${methodName}()`;
         if (classUrl) {
-          const link = `[\`${methodRef}\`](${classUrl}#${methodName.toLowerCase()})`;
+          // Link to the class page, not a method anchor: an @see-referenced method
+          // is often not a rendered heading on the target page (not in its public
+          // set), so `#method` anchors frequently 404. The class page always exists.
+          const link = `[\`${methodRef}\`](${classUrl})`;
           return description ? `- ${link} ${description}` : `- ${link}`;
         }
         // No link available, but still format nicely
@@ -1132,13 +1135,9 @@ function renderSinceTags(since) {
   if (!since || since.length === 0) return '';
 
   const formatEntry = (v) => {
-    const numericVersion = v.version.match(/^[\d.]+/)?.[0];
-    const versionSlug = numericVersion ? versionToSlug(numericVersion) : null;
-    // Link to since page if we have a valid numeric version
-    // Path is ../../../since/ because API docs are in api/classes/ or api/functions/
-    const ver = versionSlug
-      ? `[\`${mdEscape(v.version)}\`](../../../since/${versionSlug}/)`
-      : `\`${mdEscape(v.version)}\``;
+    // Render the version as plain text. Per-version "since" index pages are not
+    // generated, so linking to ../../../since/<version>/ produced broken links.
+    const ver = `\`${mdEscape(v.version)}\``;
     return v.description ? `${ver} (${mdEscape(v.description)})` : ver;
   };