feat(site): API reference pages for media elements (#1342)

site/src/utils/remarkConditionalHeadings.js

@@ -5,12 +5,14 @@ import { kebabCase } from 'es-toolkit/string';
 import GithubSlugger from 'github-slugger';
 import { buildComponentReferenceTocHeadings, createComponentReferenceModel } from './componentReferenceModel';
 import { buildFeatureReferenceTocHeadings, createFeatureReferenceModel } from './featureReferenceModel';
+import { buildMediaReferenceTocHeadings, createMediaReferenceModel } from './mediaReferenceModel';
 import { buildUtilReferenceTocHeadings, createUtilReferenceModel } from './utilReferenceModel';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const COMPONENT_REF_DIR = path.resolve(__dirname, '../content/generated-component-reference');
 const FEATURE_REF_DIR = path.resolve(__dirname, '../content/generated-feature-reference');
 const UTIL_REF_DIR = path.resolve(__dirname, '../content/generated-util-reference');
+const MEDIA_REF_DIR = path.resolve(__dirname, '../content/generated-media-reference');
 
 function readComponentRefJson(componentName) {
   const kebab = kebabCase(componentName);
@@ -72,6 +74,9 @@ export default function remarkConditionalHeadings() {
         } else if (node.name === 'UtilReference') {
           injectUtilReferenceHeadings(node, headingsWithMetadata, reservedSlugs);
           return;
+        } else if (node.name === 'MediaReference') {
+          injectMediaReferenceHeadings(node, headingsWithMetadata, reservedSlugs);
+          return;
         }
       }
 
@@ -207,6 +212,32 @@ function injectUtilReferenceHeadings(node, headingsWithMetadata, reservedSlugs)
   }
 }
 
+function readMediaRefJson(tagName) {
+  const filePath = path.join(MEDIA_REF_DIR, `${tagName}.json`);
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function injectMediaReferenceHeadings(node, headingsWithMetadata, reservedSlugs) {
+  const mediaAttr = node.attributes?.find((a) => a.name === 'media');
+  const mediaName = typeof mediaAttr?.value === 'string' ? mediaAttr.value : null;
+  if (!mediaName) return;
+
+  const json = readMediaRefJson(kebabCase(mediaName));
+  if (!json) return;
+
+  const mediaModel = createMediaReferenceModel(mediaName, json);
+  const mediaHeadings = buildMediaReferenceTocHeadings(mediaModel);
+
+  headingsWithMetadata.push(...mediaHeadings);
+  for (const heading of mediaHeadings) {
+    reservedSlugs.add(heading.slug);
+  }
+}
+
 /**
  * Extract array value from JSX attribute like frameworks={["react", "html"]}
  */