Merge pull request #8 from thefrontside/tm/tweak-contribs

Cleaned up contrib pages to improve indexing

components/api/api-page.tsx

@@ -37,7 +37,10 @@ export function* ApiPage({
     connector,
     method,
   ) {
-    if (pages && pages.find((page) => page.name === symbol)) {
+    if (
+      pages &&
+      pages.find((page) => page.name === symbol && page.kind !== "import")
+    ) {
       return `[${symbol}](${yield* externalLinkResolver(
         symbol,
         connector,

components/package/exports.tsx

@@ -48,7 +48,11 @@ function* PackageExport({
 }: PackageExportOptions): Operation<JSXElement> {
   const exports: JSXChild[] = [];
 
-  for (const page of docPages.sort((a, b) => a.name.localeCompare(b.name))) {
+  for (
+    const page of docPages
+      .flatMap((page) => (page.kind === "import" ? [] : [page]))
+      .sort((a, b) => a.name.localeCompare(b.name))
+  ) {
     exports.push(
       ...[
         <a

components/type/icon.tsx

@@ -1,26 +1,42 @@
-export function Icon({ kind }: { kind: string }) {
-  switch (kind) {
+export function Icon(props: { kind: string; class?: string }) {
+  switch (props.kind) {
     case "function":
       return (
-        <span class="rounded-full bg-sky-100 inline-block w-6 h-full mr-1 text-center">
+        <span
+          class={`${
+            props.class ? props.class : ""
+          } rounded-full bg-sky-100 inline-block w-6 h-full mr-1 text-center`}
+        >
           f
         </span>
       );
     case "interface":
       return (
-        <span class="rounded-full bg-orange-50 text-orange-600 inline-block w-6 h-full mr-1 text-center">
+        <span
+          class={`${
+            props.class ? props.class : ""
+          } rounded-full bg-orange-50 text-orange-600 inline-block w-6 h-full mr-1 text-center`}
+        >
           I
         </span>
       );
     case "typeAlias":
       return (
-        <span class="rounded-full bg-red-50 text-red-600 inline-block w-6 h-full mr-1 text-center">
+        <span
+          class={`${
+            props.class ? props.class : ""
+          } rounded-full bg-red-50 text-red-600 inline-block w-6 h-full mr-1 text-center`}
+        >
           T
         </span>
       );
     case "variable": {
       return (
-        <span class="rounded-full bg-purple-200 text-violet-600 inline-block w-6 h-full mr-1 text-center">
+        <span
+          class={`${
+            props.class ? props.class : ""
+          } rounded-full bg-purple-200 text-violet-600 inline-block w-6 h-full mr-1 text-center`}
+        >
           v
         </span>
       );

components/type/markdown.tsx

@@ -14,6 +14,8 @@ const NEW =
   `<span class="inline-block bg-violet-100 rounded px-2 text-sm text-violet-900 mx-1">new</span>`;
 const OPTIONAL =
   `<span class="inline-block bg-sky-100 rounded px-2 text-sm text-sky-900 mx-1">optional</span>`;
+const READONLY =
+  `<span class="inline-block bg-orange-100 rounded px-2 text-sm text-orange-900 mx-1">readonly</span>`;
 
 export const NO_DOCS_AVAILABLE = "*No documentation available.*";
 
@@ -134,6 +136,8 @@ export function* extract(
   }
 
   if (node.kind === "interface") {
+    if (node.name === "Completed") console.log(node);
+
     lines.push("\n", ...TypeParams(node.interfaceDef.typeParams, node));
 
     if (node.interfaceDef.properties.length > 0) {
@@ -142,7 +146,9 @@ export function* extract(
         const typeDef = property.tsType ? TypeDef(property.tsType) : "";
         const description = property.jsDoc?.doc || NO_DOCS_AVAILABLE;
         lines.push(
-          `<dt class="border-dotted [&:not(:first-child)]:border-t-2 [&:not(:first-child)]:pt-3 [&:not(:first-child)]:mt-2">**${property.name}**: ${typeDef}</dt>`,
+          `<dt class="border-dotted [&:not(:first-child)]:border-t-2 [&:not(:first-child)]:pt-3 [&:not(:first-child)]:mt-2">**${property.name}**${
+            property.readonly ? READONLY : ""
+          }${property.optional ? OPTIONAL : ""}: ${typeDef}</dt>`,
           `<dd class="flex flex-col [&>pre]:mb-3">`,
           description,
           "</dd>",
@@ -313,7 +319,9 @@ export function TypeDef(typeDef: TsTypeDef): string {
     }
     case "conditional": {
       return `${TypeDef(typeDef.conditionalType.checkType)} extends ${
-        TypeDef(typeDef.conditionalType.extendsType)
+        TypeDef(
+          typeDef.conditionalType.extendsType,
+        )
       } ? ${
         TypeDef(
           typeDef.conditionalType.trueType,
@@ -322,12 +330,16 @@ export function TypeDef(typeDef: TsTypeDef): string {
     }
     case "indexedAccess": {
       return `${TypeDef(typeDef.indexedAccess.objType)}[${
-        TypeDef(typeDef.indexedAccess.indexType)
+        TypeDef(
+          typeDef.indexedAccess.indexType,
+        )
       }]`;
     }
+    case "literal": {
+      return `*${typeDef.repr}*`;
+    }
     case "importType":
     case "infer":
-    case "literal":
     case "optional":
     case "rest":
     case "this":

deno.json

@@ -1,6 +1,8 @@
 {
   "tasks": {
-    "dev": "deno run -A --watch main.tsx"
+    "dev": "deno run -A --watch main.tsx",
+    "staticalize": "deno run -A jsr:@frontside/staticalize@0.2.0/cli --site http://localhost:8000 --output=built --base=http://localhost:8000",
+    "pagefind": "npx pagefind --site built"
   },
   "lint": {
     "exclude": ["docs/esm"],

hooks/use-description-parse.tsx

@@ -2,6 +2,7 @@ import { call, type Operation } from "effection";
 import { unified } from "unified";
 import type { VFile } from "npm:vfile@6.0.3";
 import rehypeInferDescriptionMeta from "npm:rehype-infer-description-meta@2.0.0";
+import rehypeInferTitleMeta from "npm:rehype-infer-title-meta@2.0.0";
 import rehypeStringify from "npm:rehype-stringify@10.0.1";
 import remarkParse from "npm:remark-parse@11.0.0";
 import remarkRehype from "npm:remark-rehype@11.1.1";
@@ -12,13 +13,19 @@ export function* useDescription(markdown: string): Operation<string> {
   return file.data?.meta?.description ?? "";
 }
 
+export function* useTitle(markdown: string): Operation<string> {
+  const file = yield* useMarkdownFile(markdown);
+  return file.data?.meta?.title ?? "";
+}
+
 export function* useMarkdownFile(markdown: string): Operation<VFile> {
   return yield* call(() =>
     unified()
       .use(remarkParse)
       .use(remarkRehype)
       .use(rehypeStringify)
       .use(trimAfterHR)
+      .use(rehypeInferTitleMeta)
       .use(rehypeInferDescriptionMeta, {
         inferDescriptionHast: true,
         truncateSize: 200,

hooks/use-markdown.tsx

@@ -7,6 +7,7 @@ import rehypeAddClasses from "npm:rehype-add-classes@1.0.0";
 import rehypePrismPlus from "npm:rehype-prism-plus@2.0.0";
 import remarkGfm from "npm:remark-gfm@4.0.0";
 import rehypeSlug from "npm:rehype-slug@6.0.0";
+import { JSXElement } from "revolution/jsx-runtime";
 
 export function* defaultLinkResolver(
   symbol: string,
@@ -38,7 +39,7 @@ export type ResolveLinkFunction = (
 export function* useMarkdown(
   markdown: string,
   options?: UseMDXOptions & UseMarkdownOptions,
-) {
+): Operation<JSXElement> {
   /**
    * I'm doing this pre-processing here because MDX throws a parse error when it encounteres `{@link }`.
    * I can't use a remark/rehype plugin to change this because they are applied after MDX parses is successful.
@@ -86,7 +87,18 @@ export function* useMarkdown(
     remarkRehypeOptions: options?.remarkRehypeOptions,
   });
 
-  return yield* call(() => mod.default());
+  return yield* call(async () => {
+    try {
+      const result = await mod.default();
+      return result;
+    } catch (e) {
+      console.error(
+        `Failed to convert markdown to JSXElement for ${markdown}`,
+        e,
+      );
+      return <></>;
+    }
+  });
 }
 
 export function createJsDocSanitizer(

main.tsx

@@ -13,8 +13,8 @@ import { assetsRoute } from "./routes/assets-route.ts";
 import { docsRoute } from "./routes/docs-route.tsx";
 import { indexRoute } from "./routes/index-route.tsx";
 import { apiReferenceRoute } from "./routes/api-reference-route.tsx";
-import { contribIndexRoute } from "./routes/contrib/index-route.tsx";
-import { contribPackageRoute } from "./routes/contrib/package-route.tsx";
+import { contribIndexRoute } from "./routes/contrib-index-route.tsx";
+import { contribPackageRoute } from "./routes/contrib-package-route.tsx";
 
 import { patchDenoPermissionsQuerySync } from "./deno-deploy-patch.ts";
 import { loadDocs } from "./resources/docs.ts";

resources/package.ts

@@ -4,7 +4,7 @@ import { z } from "npm:zod@3.23.8";
 
 import { useJSRClient } from "../context/jsr.ts";
 import { DocsPages, useDocPages } from "../hooks/use-deno-doc.tsx";
-import { useDescription } from "../hooks/use-description-parse.tsx";
+import { useDescription, useTitle } from "../hooks/use-description-parse.tsx";
 import { useMDX } from "../hooks/use-mdx.tsx";
 import { PackageDetailsResult, PackageScoreResult } from "./jsr-client.ts";
 import { RepositoryRef } from "./repository-ref.ts";
@@ -90,6 +90,7 @@ export interface Package {
    */
   docs(): Operation<DocsPages>;
   MDXContent(): Operation<JSX.Element>;
+  title(): Operation<string>;
   description(): Operation<string>;
 }
 
@@ -208,6 +209,10 @@ export function loadPackage(
 
         return mod.default({});
       },
+      *title(): Operation<string> {
+        let readme = yield* pkg.readme();
+        return yield* useTitle(readme);
+      },
       *description(): Operation<string> {
         let readme = yield* pkg.readme();
         return yield* useDescription(readme);

routes/api-index-route.tsx

@@ -9,6 +9,7 @@ import { DocPage } from "../hooks/use-deno-doc.tsx";
 import { createChildURL } from "./links-resolvers.ts";
 import { extractVersion, major, minor, rsort } from "../lib/semver.ts";
 import { ResolveLinkFunction } from "../hooks/use-markdown.tsx";
+import { Icon } from "../components/type/icon.tsx";
 
 export function apiIndexRoute({
   library,
@@ -83,7 +84,7 @@ export function apiIndexRoute({
               </p>
               <h3>Latest release: {v3version}</h3>
               <p>This release includes the following exports:</p>
-              <ul class="columns-3">
+              <ul class="columns-3 pl-0">
                 {yield* listPages({
                   pages: v3docs["."],
                   linkResolver: createChildURL("v3"),
@@ -113,7 +114,7 @@ export function apiIndexRoute({
               </p>
               <h3>Latest release: {v4version}</h3>
               <p>This release includes the following exports:</p>
-              <ul class="columns-3">
+              <ul class="columns-3 pl-0">
                 {yield* listPages({
                   pages: v3docs["."],
                   linkResolver: createChildURL("v4"),
@@ -139,8 +140,11 @@ function* listPages({
   for (const page of pages.sort((a, b) => a.name.localeCompare(b.name))) {
     const link = yield* linkResolver(page.name);
     elements.push(
-      <li>
-        <a href={link}>{page.name}</a>
+      <li class="list-none pb-1">
+        <a href={link}>
+          <Icon kind={page.kind} class="mr-2" />
+          {page.name}
+        </a>
       </li>,
     );
   }

routes/contrib/index-route.tsx → routes/contrib-index-route.tsx

@@ -1,9 +1,9 @@
 import { all } from "effection";
-import type { SitemapRoute } from "../../plugins/sitemap.ts";
+import type { SitemapRoute } from "../plugins/sitemap.ts";
 import type { JSXElement } from "revolution";
-import { useAppHtml } from "../app.html.tsx";
-import { Repository } from "../../resources/repository.ts";
-import { GithubPill } from "../../components/package/source-link.tsx";
+import { useAppHtml } from "./app.html.tsx";
+import { Repository } from "../resources/repository.ts";
+import { GithubPill } from "../components/package/source-link.tsx";
 
 export function contribIndexRoute(
   contrib: Repository,
@@ -43,7 +43,9 @@ export function contribIndexRoute(
                   return (
                     <li class="px-0">
                       <h3>
-                        <a href={`/contrib/${pkg.path}`}>{pkg.packageName}</a>
+                        <a href={`/contrib/${pkg.path}`}>
+                          {yield* pkg.title()}
+                        </a>
                       </h3>
                       <p>{yield* pkg.description()}</p>
                     </li>