Add markdown API reference routes and enable page actions (#687)

* feat: add TypeScript API markdown generation and tests

- Implement TypeScript API markdown generation in `typescript-api-markdown.ts` with functions for rendering index, modules, items, and members.
- Create e2e tests for API markdown routes in `api-markdown-routes.spec.ts` to ensure correct markdown responses for C# and TypeScript routes.
- Add unit tests for API markdown routes in `api-markdown.vitest.test.ts` to validate markdown generation for various API components including modules, types, and functions.

* feat: enhance markdown normalization and update tests to validate formatting

* feature: enable faster local builds, by omitting pagefind

* fix: address API markdown lint feedback

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test: stabilize API markdown route fixtures

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: IEvangelist

package.json

@@ -6,6 +6,7 @@
     "install": "pnpm --dir ./src/frontend i",
     "dev": "pnpm --dir ./src/frontend run dev",
     "build": "pnpm --dir ./src/frontend run build",
+    "build:skip-search": "pnpm --dir ./src/frontend run build:skip-search",
     "preview": "pnpm --dir ./src/frontend run preview",
     "test": "pnpm --dir ./src/frontend run test",
     "test:all": "pnpm --dir ./src/frontend run test:all",

src/frontend/astro.config.mjs

@@ -21,6 +21,9 @@ import starlightSidebarTopics from 'starlight-sidebar-topics';
 import starlightPageActions from 'starlight-page-actions';
 import jopSoftwarecookieconsent from '@jop-software/astro-cookieconsent';
 
+const modeArgIndex = process.argv.indexOf('--mode');
+const isSkipSearchBuild = modeArgIndex >= 0 && process.argv[modeArgIndex + 1] === 'skip-search';
+
 // https://astro.build/config
 export default defineConfig({
   prefetch: true,
@@ -34,6 +37,7 @@ export default defineConfig({
       iconPacks,
     }),
     starlight({
+      pagefind: !isSkipSearchBuild,
       title: 'Aspire',
       routeMiddleware: ['./src/route-data-middleware'],
       defaultLocale: 'root',

src/frontend/package.json

@@ -21,16 +21,19 @@
     "start": "pnpm git-env && pnpm check-data && astro dev",
     "start:host": "pnpm git-env && pnpm check-data && astro dev --host",
     "build": "pnpm git-env && astro build",
+    "build:skip-search": "pnpm git-env && astro build --mode skip-search",
     "build:production": "pnpm git-env && astro build --mode production",
     "preview": "astro preview",
     "preview:host": "astro preview --host",
     "astro": "pnpm git-env && astro",
     "test": "pnpm test:unit && pnpm test:e2e",
     "test:all": "pnpm lint && pnpm test",
-    "test:unit": "pnpm test:unit:contracts && pnpm test:unit:components && pnpm test:unit:docs",
+    "test:unit": "pnpm test:unit:contracts && pnpm test:unit:components && pnpm test:unit:docs && pnpm test:unit:api-markdown",
+    "test:unit:api-markdown": "vitest run --config vitest.config.ts tests/unit/api-markdown.vitest.test.ts",
     "test:unit:contracts": "vitest run --config vitest.config.ts tests/unit/analytics-script-contracts.vitest.test.ts",
     "test:unit:components": "vitest run --config vitest.config.ts tests/unit/custom-components.vitest.test.ts tests/unit/site-tour.vitest.test.ts",
     "test:unit:docs": "vitest run --config vitest.config.ts tests/unit/filetree-format.vitest.test.ts",
+    "test:e2e:api-markdown": "playwright test --config playwright.api-markdown.config.mjs",
     "test:e2e": "playwright test",
     "test:e2e:install": "playwright install chromium",
     "test:e2e:serve": "pnpm git-env && pnpm check-data && astro dev --host 127.0.0.1 --port 4321",

src/frontend/playwright.api-markdown.config.mjs

@@ -0,0 +1,25 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  testMatch: 'api-markdown-routes.spec.ts',
+  fullyParallel: true,
+  workers: 1,
+  reporter: [['list']],
+  use: {
+    baseURL: 'http://127.0.0.1:4322',
+  },
+  webServer: {
+    command: 'pnpm git-env && pnpm check-data && astro dev --host 127.0.0.1 --port 4322',
+    env: {
+      ...process.env,
+      ASTRO_TELEMETRY_DISABLED: '1',
+      E2E_TESTS: '1',
+    },
+    url: 'http://127.0.0.1:4322',
+    reuseExistingServer: false,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    timeout: 120000,
+  },
+});

src/frontend/src/middleware.ts

@@ -0,0 +1,13 @@
+import { defineMiddleware } from 'astro:middleware';
+
+const nestedApiMarkdownPattern = /^\/reference\/api\/(?:csharp|typescript)\/.+\.md$/;
+
+export const onRequest = defineMiddleware((context, next) => {
+  const { pathname, search } = context.url;
+
+  if (nestedApiMarkdownPattern.test(pathname)) {
+    return context.redirect(`${pathname}/${search}`, 308);
+  }
+
+  return next();
+});

src/frontend/src/pages/reference/api/csharp.md.ts

@@ -0,0 +1,13 @@
+import type { APIRoute } from 'astro';
+
+import { markdownResponse } from '@utils/api-markdown-shared';
+import { renderCSharpIndexMarkdown } from '@utils/csharp-api-markdown';
+import { getPackages } from '@utils/packages';
+
+export const prerender = true;
+
+export const GET: APIRoute = async () => {
+  const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+  const packages = (await getPackages()).map((entry) => entry.data);
+  return markdownResponse(renderCSharpIndexMarkdown(packages, base));
+};

src/frontend/src/pages/reference/api/csharp/[package].md.ts

@@ -0,0 +1,34 @@
+import type { APIRoute } from 'astro';
+
+import { markdownResponse } from '@utils/api-markdown-shared';
+import { renderCSharpPackageMarkdown } from '@utils/csharp-api-markdown';
+import type { PackageApiDocument } from '@utils/packages';
+import { getPackages, packageSlug } from '@utils/packages';
+
+export const prerender = true;
+
+type RouteProps = {
+  pkg: PackageApiDocument;
+};
+
+type StaticPath = {
+  params: { package: string };
+  props: RouteProps;
+};
+
+export async function getStaticPaths(): Promise<StaticPath[]> {
+  const packages = await getPackages();
+
+  return packages.map((entry) => ({
+    params: { package: packageSlug(entry.data.package.name) },
+    props: {
+      pkg: entry.data,
+    },
+  }));
+}
+
+export const GET: APIRoute = ({ props }) => {
+  const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+  const routeProps = props as RouteProps;
+  return markdownResponse(renderCSharpPackageMarkdown(routeProps.pkg, base));
+};

src/frontend/src/pages/reference/api/csharp/[package]/[type].md.ts

@@ -0,0 +1,59 @@
+import type { APIRoute } from 'astro';
+
+import { markdownResponse } from '@utils/api-markdown-shared';
+import { renderCSharpTypeMarkdown } from '@utils/csharp-api-markdown';
+import type { PackageApiDocument, PackageType } from '@utils/packages';
+import { genericArity, getPackages, packageSlug, slugify } from '@utils/packages';
+
+export const prerender = true;
+
+type RouteProps = {
+  allTypes: PackageType[];
+  pkg: PackageApiDocument;
+  type: PackageType;
+};
+
+type StaticPath = {
+  params: { package: string; type: string };
+  props: RouteProps;
+};
+
+export async function getStaticPaths(): Promise<StaticPath[]> {
+  const packages = await getPackages();
+  const paths: StaticPath[] = [];
+
+  for (const entry of packages) {
+    const pkg = entry.data;
+    const pkgSlug = packageSlug(pkg.package.name);
+
+    for (const type of pkg.types) {
+      const typeSlug = slugify(type.name, genericArity(type));
+      if (!typeSlug) {
+        continue;
+      }
+
+      paths.push({
+        params: {
+          package: pkgSlug,
+          type: typeSlug,
+        },
+        props: {
+          allTypes: pkg.types,
+          pkg,
+          type,
+        },
+      });
+    }
+  }
+
+  return paths;
+}
+
+export const GET: APIRoute = ({ props }) => {
+  const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+  const routeProps = props as RouteProps;
+
+  return markdownResponse(
+    renderCSharpTypeMarkdown(routeProps.pkg, routeProps.type, routeProps.allTypes, base)
+  );
+};

src/frontend/src/pages/reference/api/csharp/[package]/[type]/[memberKind].astro

@@ -101,6 +101,7 @@ const headings: { depth: 2 | 3; slug: string; text: string }[] = filteredMembers
     next: false,
     tableOfContents: false,
     pagefind: false,
+    pageActions: true,
   }}
   sidebar={apiSidebar}
   headings={headings}
@@ -170,4 +171,4 @@ const headings: { depth: 2 | 3; slug: string; text: string }[] = filteredMembers
     flex-direction: column;
     gap: 1rem;
   }
-</style>
+</style>

src/frontend/src/pages/reference/api/csharp/[package]/[type]/[memberKind].md.ts

@@ -0,0 +1,83 @@
+import type { APIRoute } from 'astro';
+
+import { markdownResponse } from '@utils/api-markdown-shared';
+import { renderCSharpMemberKindMarkdown } from '@utils/csharp-api-markdown';
+import type { PackageApiDocument, PackageMember, PackageType } from '@utils/packages';
+import {
+  genericArity,
+  getPackages,
+  memberKindOrder,
+  memberKindSlugs,
+  packageSlug,
+  slugify,
+} from '@utils/packages';
+
+export const prerender = true;
+
+type RouteProps = {
+  allTypes: PackageType[];
+  memberKind: string;
+  pkg: PackageApiDocument;
+  type: PackageType;
+};
+
+type StaticPath = {
+  params: { memberKind: string; package: string; type: string };
+  props: RouteProps;
+};
+
+export async function getStaticPaths(): Promise<StaticPath[]> {
+  const packages = await getPackages();
+  const paths: StaticPath[] = [];
+
+  for (const entry of packages) {
+    const pkg = entry.data;
+    const pkgSlug = packageSlug(pkg.package.name);
+
+    for (const type of pkg.types) {
+      const typeSlug = slugify(type.name, genericArity(type));
+      if (!typeSlug) {
+        continue;
+      }
+
+      const members = type.members ?? [];
+      for (const memberKind of memberKindOrder) {
+        const memberKindSlug = memberKindSlugs[memberKind];
+        if (!memberKindSlug || !members.some((member: PackageMember) => member.kind === memberKind)) {
+          continue;
+        }
+
+        paths.push({
+          params: {
+            memberKind: memberKindSlug,
+            package: pkgSlug,
+            type: typeSlug,
+          },
+          props: {
+            allTypes: pkg.types,
+            memberKind,
+            pkg,
+            type,
+          },
+        });
+      }
+    }
+  }
+
+  return paths;
+}
+
+export const GET: APIRoute = ({ props }) => {
+  const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+  const routeProps = props as RouteProps;
+
+  return markdownResponse(
+    renderCSharpMemberKindMarkdown(
+      routeProps.pkg,
+      routeProps.type,
+      routeProps.memberKind,
+      routeProps.allTypes,
+      base
+    )
+  );
+};