fix: Improve documentation generation

- Use product labels from repos-config.json for correct capitalization
  (e.g., "GravityBoard" instead of "Gravityboard")
- Add htmlEscapeDescription() to convert PHPDoc <code> blocks to
  markdown fenced code blocks in descriptions
- Keep htmlEscape() simple for summaries/inline text
- Add /claudedocs to .gitignore

Author: zackkatz

.gitignore

@@ -65,3 +65,4 @@ yarn-error.log*
 # Misc
 *.log
 *.tmp
+/claudedocs

scripts/generate-category-indexes.mjs

@@ -12,6 +12,15 @@ import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const docsDir = path.join(__dirname, '..', 'docs');
 
+// Load product config for proper labels
+const configPath = path.join(__dirname, '..', 'repos-config.json');
+const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+const productLabels = new Map(
+  (config.products || [])
+    .filter(p => p.id && p.label)
+    .map(p => [p.id, p.label])
+);
+
 /**
  * Find all actions and filters directories (lowercase).
  * @param {string} dir
@@ -46,16 +55,21 @@ function countHooks(dir) {
 }
 
 /**
- * Get product name from path.
+ * Get product name from path using repos-config.json labels.
  * @param {string} dirPath
  * @returns {string}
  */
 function getProductName(dirPath) {
   const parts = dirPath.split(path.sep);
   const docsIndex = parts.indexOf('docs');
   if (docsIndex !== -1 && parts[docsIndex + 1]) {
-    // Convert slug to title case
-    return parts[docsIndex + 1]
+    const productId = parts[docsIndex + 1];
+    // Use label from config, fallback to title case
+    if (productLabels.has(productId)) {
+      return productLabels.get(productId);
+    }
+    // Fallback: convert slug to title case
+    return productId
       .split('-')
       .map(word => word.charAt(0).toUpperCase() + word.slice(1))
       .join(' ');

scripts/generate-php-api.mjs

@@ -1200,14 +1200,26 @@ function mdEscape(text) {
 
 /**
  * Escape HTML entities in text to prevent markdown/HTML parsing issues.
- * Use this for descriptions and summaries that appear in markdown content.
+ * Use this for summaries and short text that appear inline.
  */
 function htmlEscape(text) {
   return String(text ?? '')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;');
 }
 
+/**
+ * Escape HTML entities in description text, preserving PHPDoc <code> blocks.
+ * Converts <code>...</code> to markdown fenced code blocks.
+ * Use this for multi-line descriptions where code examples may appear.
+ */
+function htmlEscapeDescription(text) {
+  return htmlEscape(text)
+    // Convert <code> blocks to markdown fenced code blocks
+    .replace(/&lt;code&gt;/gi, '\n```php\n')
+    .replace(/&lt;\/code&gt;/gi, '\n```\n');
+}
+
 /**
  * Clean description text: strip leading em-dashes and similar prefixes.
  */
@@ -1518,7 +1530,7 @@ function generateClassPage({ productLabel, classSymbol, product, repoRef, typeLi
 \`${wordpressFormatSignature(phpShortArraySyntax(m.signature || `function ${m.name}()`))}\`
 
 ${htmlEscape(m.summary || '')}
-${m.description ? `\n${processInlineSeeRefs(htmlEscape(m.description))}\n` : ''}
+${m.description ? `\n${processInlineSeeRefs(htmlEscapeDescription(m.description))}\n` : ''}
 ${paramsTable ? `\n#### Parameters\n\n${paramsTable}\n` : ''}
 ${resolvedReturnType || resolvedReturnDesc ? `\n#### Returns\n\n- ${codeInlineType(resolvedReturnType, typeLinkCtx)}${resolvedReturnDesc ? ` — ${mdEscape(resolvedReturnDesc)}` : ''}\n` : ''}
 ${throwsList.length ? `\n#### Throws\n\n${throwsList.map((t) => `- ${codeInlineType(t.type, typeLinkCtx)}${t.description ? ` — ${mdEscape(cleanDescription(t.description))}` : ''}`).join('\n')}\n` : ''}
@@ -1527,7 +1539,7 @@ ${renderSeeAlsoSection(m.tags, typeLinkCtx, { heading: '####' })}
 ${renderSinceTags(since)}
 ${deprecated.length ? `\n**Deprecated:** ${deprecated.map((d) => {
   const ver = d.version ? `\`${mdEscape(d.version)}\`` : '';
-  const desc = d.description ? processInlineSeeRefs(htmlEscape(d.description)) : '';
+  const desc = d.description ? processInlineSeeRefs(htmlEscapeDescription(d.description)) : '';
   if (ver && desc) return `${ver} (${desc})`;
   if (ver) return ver;
   if (desc) return desc;
@@ -1551,13 +1563,13 @@ ${formatTagsYaml(versionTags)}---
 # \`${fqcn}\`
 
 ${htmlEscape(classSymbol.summary || '')}
-${classSymbol.description ? `\n${processInlineSeeRefs(htmlEscape(classSymbol.description))}\n` : ''}
+${classSymbol.description ? `\n${processInlineSeeRefs(htmlEscapeDescription(classSymbol.description))}\n` : ''}
 ${renderExamplesSection(classSymbol.tags, { heading: '##' })}
 ${renderSeeAlsoSection(classSymbol.tags, typeLinkCtx, { heading: '##' })}
 ${renderSinceTags(since)}
 ${deprecated.length ? `\n**Deprecated:** ${deprecated.map((d) => {
   const ver = d.version ? `\`${mdEscape(d.version)}\`` : '';
-  const desc = d.description ? processInlineSeeRefs(htmlEscape(d.description)) : '';
+  const desc = d.description ? processInlineSeeRefs(htmlEscapeDescription(d.description)) : '';
   if (ver && desc) return `${ver} (${desc})`;
   if (ver) return ver;
   if (desc) return desc;
@@ -1626,13 +1638,13 @@ ${formatTagsYaml(versionTags)}---
 \`${wordpressFormatSignature(phpShortArraySyntax(functionSymbol.signature || `function ${shortName}()`))}\`
 
 ${htmlEscape(functionSymbol.summary || '')}
-${functionSymbol.description ? `\n${processInlineSeeRefs(htmlEscape(functionSymbol.description))}\n` : ''}
+${functionSymbol.description ? `\n${processInlineSeeRefs(htmlEscapeDescription(functionSymbol.description))}\n` : ''}
 ${renderExamplesSection(functionSymbol.tags, { heading: '##' })}
 ${renderSeeAlsoSection(functionSymbol.tags, typeLinkCtx, { heading: '##' })}
 ${renderSinceTags(since)}
 ${deprecated.length ? `\n**Deprecated:** ${deprecated.map((d) => {
   const ver = d.version ? `\`${mdEscape(d.version)}\`` : '';
-  const desc = d.description ? processInlineSeeRefs(htmlEscape(d.description)) : '';
+  const desc = d.description ? processInlineSeeRefs(htmlEscapeDescription(d.description)) : '';
   if (ver && desc) return `${ver} (${desc})`;
   if (ver) return ver;
   if (desc) return desc;