fix(docs): resolve API anchor ID collisions by appending kind suffix

Author: fkatsuhiro

packages/docs/src/routes/api/index.tsx

@@ -1,6 +1,5 @@
 import { $, component$, useOn, useSignal, useStore, useTask$, isBrowser } from '@builder.io/qwik';
 import { Link } from '@builder.io/qwik-city';
-
 import { toSnakeCase } from '../../utils/utils';
 
 // TODO: load the content of these files using fs instead of importing them
@@ -140,32 +139,45 @@ export const ApiMemberWrapper = component$(({ id, data, filters }: any) => {
 });
 
 
-export const ApiMemberList = component$(({ id, data, filters }: any) => (
-  <ul class="grid sm:grid-cols-2 lg:grid-cols-3 pb-5">
-    {data.members.map((member: any) => {
-      const kind = toSnakeCase(member.kind);
-
-      if (!member.name) {
-        return;
-      }
-
-      const name = member.name.toLowerCase()
-        .replace(/[^a-zA-Z0-9]/g, '')
-        .replace(/ /g, '-');
-
-
-      return (
-        <li
-          key={`${id}-member-${member.id}-${kind}`}
-          data-kind={kind}
-          data-kind-label={kind.substring(0, 1).toUpperCase()}
-          class={`api-item list-none text-xs ${
-            (kind in filters && !filters[kind] && 'hidden') || ''
-          }`}
-        >
-          <Link href={`${data.id}#${name}`}>{member.name}</Link>
-        </li>
-      );
-    })}
-  </ul>
-));
+export const ApiMemberList = component$(({ id, data, filters }: any) => {
+  const nameCounts = data.members.reduce((acc: Record<string, number>, m: any) => {
+    if (m.name) {
+      const normalizedName = m.name.toLowerCase();
+      acc[normalizedName] = (acc[normalizedName] || 0) + 1;
+    }
+    return acc;
+  }, {});
+  return (
+    <ul class="grid sm:grid-cols-2 lg:grid-cols-3 pb-5">
+      {data.members.map((member: any) => {
+        const kind = toSnakeCase(member.kind);
+
+        if (!member.name) {
+          return;
+        }
+      
+        const name = member.name.toLowerCase()
+            .replace(/[$]/g, '_')
+            .replace(/[^a-zA-Z0-9_]/g, '')
+            .replace(/ /g, '-');
+
+        const anchorId = nameCounts[member.name.toLowerCase()] > 1 
+            ? `${name}-${kind}`
+            : name;
+
+        return (
+          <li
+            key={`${id}-member-${member.id}-${kind}`}
+            data-kind={kind}
+            data-kind-label={kind.substring(0, 1).toUpperCase()}
+            class={`api-item list-none text-xs ${
+              (kind in filters && !filters[kind] && 'hidden') || ''
+            }`}
+          >
+            <Link href={`${data.id}#${anchorId}`}>{member.name}</Link>
+          </li>
+        );
+      })}
+    </ul>
+  );
+});

packages/docs/src/routes/api/qwik-city-vite-azure-swa/index.mdx

@@ -4,7 +4,7 @@ title: \@builder.io/qwik-city/vite/azure-swa API Reference
 
 # [API](/api) › @builder.io/qwik-city/vite/azure-swa
 
-## azureSwaAdapter
+<h2 id="azureswaadapter">azureSwaAdapter</h2>
 
 ```typescript
 export declare function azureSwaAdapter(opts?: AzureSwaAdapterOptions): any;
@@ -44,7 +44,7 @@ any
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/adapters/azure-swa/vite/index.ts)
 
-## AzureSwaAdapterOptions
+<h2 id="azureswaadapteroptions">AzureSwaAdapterOptions</h2>
 
 ```typescript
 export interface AzureSwaAdapterOptions extends ServerAdapterOptions

packages/docs/src/routes/api/qwik-city-vite-static/index.mdx

@@ -4,7 +4,7 @@ title: \@builder.io/qwik-city/vite/static API Reference
 
 # [API](/api) › @builder.io/qwik-city/vite/static
 
-## staticAdapter
+<h2 id="staticadapter">staticAdapter</h2>
 
 ```typescript
 export declare function staticAdapter(opts: StaticGenerateAdapterOptions): any;
@@ -42,7 +42,7 @@ any
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/adapters/static/vite/index.ts)
 
-## StaticGenerateAdapterOptions
+<h2 id="staticgenerateadapteroptions">StaticGenerateAdapterOptions</h2>
 
 ```typescript
 export interface StaticGenerateAdapterOptions extends Omit<StaticGenerateRenderOptions, 'outDir'>

scripts/api-docs.ts

@@ -2,7 +2,7 @@ import { execa } from 'execa';
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { format } from 'prettier';
-import { type BuildConfig } from './util.ts';
+import { type BuildConfig, toSnakeCase } from './util.ts';
 
 export async function generateQwikApiMarkdownDocs(config: BuildConfig, apiJsonInputDir: string) {
   await generateApiMarkdownPackageDocs(config, apiJsonInputDir, ['qwik']);
@@ -198,6 +198,12 @@ async function createApiData(
 async function createApiMarkdown(a: ApiData) {
   let md: string[] = [];
 
+  const memberNameCounts = a.members.reduce((acc: Record<string, number>, m) => {
+    const normalizedName = m.name.toLowerCase();
+    acc[normalizedName] = (acc[normalizedName] || 0) + 1;
+    return acc;
+  }, {});
+
   md.push(`---`);
   md.push(`title: \\${a.package} API Reference`);
   md.push(`---`);
@@ -207,7 +213,11 @@ async function createApiMarkdown(a: ApiData) {
 
   for (const m of a.members) {
     // const title = `${toSnakeCase(m.kind)} - ${m.name.replace(/"/g, '')}`;
-    md.push(`## ${m.name}`);
+    const kind = toSnakeCase(m.kind);
+    const isDuplicateName = memberNameCounts[m.name.toLowerCase()] > 1;
+    const anchorId = isDuplicateName ? `${m.id}-${kind}` : m.id;
+
+    md.push(`<h2 id="${anchorId}">${m.name}</h2>`);
     md.push(``);
 
     // sanitize / adjust output

scripts/util.ts

@@ -366,3 +366,10 @@ export async function getQwikVersion(config: BuildConfig) {
   const qwikPkgJson = await readPackageJson(qwikDir);
   return qwikPkgJson.version;
 }
+
+// pascal to snake case
+export const toSnakeCase = (str: string) =>
+  str
+    .split(/\.?(?=[A-Z])/)
+    .join('-')
+    .toLowerCase();