docs: agent tracing guides for 20 frameworks + per-framework skills

apps/landing/astro.config.mjs

@@ -5,6 +5,7 @@ import { defineConfig } from "astro/config"
 import { transformerNotationDiff, transformerNotationHighlight } from "@shikijs/transformers"
 import { unified } from "@astrojs/markdown-remark"
 import rehypeTableWrap from "./src/lib/rehype-table-wrap.mjs"
+import remarkInstallTabs from "./src/lib/remark-install-tabs.mjs"
 import { codeTheme } from "./src/lib/code-theme.mjs"
 import mdx from "@astrojs/mdx"
 import { paraglideVitePlugin } from "@inlang/paraglide-js"
@@ -99,7 +100,8 @@ export default defineConfig({
 	markdown: {
 		// Stay on the remark pipeline: Sätteri doesn't run the Shiki transformers
 		// configured below. Revisit when the transformer story lands there.
-		processor: unified({ rehypePlugins: [rehypeTableWrap] }),
+		// MDX inherits these plugins.
+		processor: unified({ remarkPlugins: [remarkInstallTabs], rehypePlugins: [rehypeTableWrap] }),
 		shikiConfig: {
 			theme: codeTheme,
 			wrap: true,

apps/landing/src/components/docs/DocsCategoryIcon.astro

@@ -110,7 +110,7 @@ const base = {
 	</svg>
 )}
 
-{name === "Agent Sessions" && (
+{(name === "Agent Sessions" || name === "AI Agents") && (
 	<svg class={className} {...base}>
 		<path d="M3 4H21V16H13L8 21V16H3V4Z" />
 		<path d="M8 9H8.01" />

apps/landing/src/components/docs/DocsSidebar.astro

@@ -5,6 +5,7 @@
 // Language rows carry their logo; Effect's platform pages nest under Effect.
 import { getCollection } from "astro:content";
 import DocsCategoryIcon from "./DocsCategoryIcon.astro";
+import BrandMarkIcon from "../BrandMarkIcon.astro";
 import LanguageLogo from "./LanguageLogo.astro";
 import { groupRank, isDocGroup, sectionForGroup } from "../../lib/docs-nav";
 import { getDocSections } from "../../lib/docs-order";
@@ -73,8 +74,10 @@ const rowClass = (active: boolean) =>
                                 aria-current={active ? "page" : undefined}
                                 class:list={["flex items-center gap-2 px-2.5 py-1.5 text-[13px] leading-5 transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-primary", rowClass(active)]}
                             >
-                                {doc.data.sdk && (
+                                {doc.data.sdk ? (
                                     <LanguageLogo id={doc.data.sdk} class="h-3.5 w-3.5 shrink-0" />
+                                ) : (
+                                    doc.data.icon && <BrandMarkIcon id={doc.data.icon} class="h-3.5 w-3.5 shrink-0" />
                                 )}
                                 <span class="truncate">{label(doc)}</span>
                             </a>

apps/landing/src/components/docs/GuideGrid.astro

@@ -1,17 +1,19 @@
 ---
-// One ecosystem's cards on /docs/instrumentation. Styled with scoped CSS on
+// One ecosystem's cards on /docs/instrumentation (or a given card list, as on /docs/frontend). Styled with scoped CSS on
 // purpose: the page sits inside `.docs-content`, whose descendant rules for
 // `a`/`p` beat plain Tailwind utilities (see `local/InstallTabs.astro`).
-import { GUIDE_SECTIONS } from "../../lib/instrumentation-guides";
+import { type GuideCard, GUIDE_SECTIONS } from "../../lib/instrumentation-guides";
 import BrandMarkIcon from "../BrandMarkIcon.astro";
 import LanguageLogo from "./LanguageLogo.astro";
 
 interface Props {
-    section: string;
+    /** A section of GUIDE_SECTIONS, or `cards` for a list shown elsewhere. */
+    section?: string;
+    cards?: readonly GuideCard[];
 }
 
-const { section } = Astro.props;
-const data = GUIDE_SECTIONS.find((s) => s.id === section);
+const { section, cards } = Astro.props;
+const data = cards ? { cards } : GUIDE_SECTIONS.find((s) => s.id === section);
 if (!data) throw new Error(`Unknown guide section: ${section}`);
 ---
 

apps/landing/src/components/docs/LanguageLogo.astro

@@ -1,8 +1,8 @@
 ---
-// Maps a `LanguageId` to its brand logo. The only place the logo components
+// Maps a `LogoId` to its brand logo. The only place the logo components
 // are wired to language ids — everything else passes the id around.
 import type { AstroComponentFactory } from "astro/runtime/server/index.js";
-import type { LanguageId } from "../../lib/docs-languages";
+import type { LogoId } from "../../lib/docs-languages";
 import EffectLogomark from "../icons/EffectLogomark.astro";
 import NodeJsLogo from "../icons/NodeJsLogo.astro";
 import NextjsLogo from "../icons/NextjsLogo.astro";
@@ -13,9 +13,10 @@ import OpenJdkLogo from "../icons/OpenJdkLogo.astro";
 import CsharpLogo from "../icons/CsharpLogo.astro";
 import KotlinLogo from "../icons/KotlinLogo.astro";
 import LaravelLogo from "../icons/LaravelLogo.astro";
+import TypeScriptLogo from "../icons/TypeScriptLogo.astro";
 
 interface Props {
-    id: LanguageId;
+    id: LogoId;
     class?: string;
 }
 
@@ -30,7 +31,8 @@ const LOGOS = {
     kotlin: KotlinLogo,
     csharp: CsharpLogo,
     laravel: LaravelLogo,
-} satisfies Record<LanguageId, AstroComponentFactory>;
+    typescript: TypeScriptLogo,
+} satisfies Record<LogoId, AstroComponentFactory>;
 
 const { id, class: className = "h-4 w-4" } = Astro.props;
 const Logo = LOGOS[id];

apps/landing/src/components/docs/LanguageTabs.astro

@@ -2,9 +2,11 @@
 // Language/framework switcher for docs pages. Children are `<LanguageTab id>`
 // panels holding ordinary markdown, so code blocks keep their highlighting and
 // copy buttons. The pick is remembered and shared by every group on the site.
-// Without JavaScript the first panel shows and the rest stay hidden.
+// Without JavaScript the first panel shows and the rest stay hidden. Styles live
+// in global.css and behavior in lib/docs-tabs.ts, shared with the package-manager
+// switchers remark-install-tabs.mjs renders.
 import LanguageLogo from "./LanguageLogo.astro";
-import { LANGUAGE_IDS, type LanguageId } from "../../lib/docs-languages";
+import { LOGO_IDS, type LogoId } from "../../lib/docs-languages";
 
 interface Tab {
     id: string;
@@ -17,10 +19,10 @@ interface Props {
 }
 
 const { tabs, label = "Language" } = Astro.props;
-const isLanguage = (id: string): id is LanguageId => (LANGUAGE_IDS as readonly string[]).includes(id);
+const hasLogo = (id: string): id is LogoId => (LOGO_IDS as readonly string[]).includes(id);
 ---
 
-<div class="lt" data-lang-tabs>
+<div class="lt" data-lang-tabs="maple-docs-language">
     <div class="lt__rail" role="tablist" aria-label={label}>
         {tabs.map((tab, index) => (
             <button
@@ -31,7 +33,7 @@ const isLanguage = (id: string): id is LanguageId => (LANGUAGE_IDS as readonly s
                 aria-selected={index === 0 ? "true" : "false"}
                 tabindex={index === 0 ? 0 : -1}
             >
-                {isLanguage(tab.id) ? (
+                {hasLogo(tab.id) ? (
                     <LanguageLogo id={tab.id} class="lt__icon" />
                 ) : (
                     <svg class="lt__icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
@@ -49,123 +51,6 @@ const isLanguage = (id: string): id is LanguageId => (LANGUAGE_IDS as readonly s
     </div>
 </div>
 
-<style>
-    .lt {
-        margin: 16px 0 24px;
-    }
-    .lt__rail {
-        display: flex;
-        flex-wrap: wrap;
-        gap: 6px;
-        margin-bottom: 12px;
-    }
-    .lt__tab {
-        display: inline-flex;
-        align-items: center;
-        gap: 7px;
-        height: 32px;
-        padding: 0 11px 0 9px;
-        border-radius: 8px;
-        border: 1px solid var(--border);
-        background: transparent;
-        color: var(--muted-foreground);
-        font: inherit;
-        font-size: 13px;
-        cursor: pointer;
-        transition: color 150ms ease, background-color 150ms ease, border-color 150ms ease;
-    }
-    .lt__tab:hover {
-        color: var(--foreground);
-        border-color: color-mix(in oklab, var(--muted-foreground) 50%, transparent);
-    }
-    .lt__tab[aria-selected="true"] {
-        color: var(--foreground);
-        background: var(--bg-elevated);
-        border-color: color-mix(in oklab, var(--muted-foreground) 50%, transparent);
-    }
-    .lt__tab:focus-visible {
-        outline: 2px solid var(--primary);
-        outline-offset: 2px;
-    }
-    .lt__tab :global(.lt__icon) {
-        width: 15px;
-        height: 15px;
-        flex: none;
-    }
-    /* Before the script runs (or without it), only the first panel shows. */
-    .lt:not([data-ready]) .lt__panels > :global([data-lang-panel]:not(:first-child)) {
-        display: none;
-    }
-</style>
-
 <script>
-    const STORAGE_KEY = "maple-docs-language";
-    const roots = Array.from(document.querySelectorAll<HTMLElement>("[data-lang-tabs]"));
-
-    const readStored = () => {
-        try {
-            return localStorage.getItem(STORAGE_KEY);
-        } catch {
-            return null;
-        }
-    };
-    const writeStored = (id: string) => {
-        try {
-            localStorage.setItem(STORAGE_KEY, id);
-        } catch {
-            // Storage blocked: the choice just isn't remembered.
-        }
-    };
-
-    const triggersOf = (root: HTMLElement) => Array.from(root.querySelectorAll<HTMLElement>("[data-lang-trigger]"));
-
-    // A group without the requested id keeps its current tab.
-    const activate = (root: HTMLElement, id: string) => {
-        const triggers = triggersOf(root);
-        if (!triggers.some((t) => t.dataset.langTrigger === id)) return false;
-        for (const t of triggers) {
-            const on = t.dataset.langTrigger === id;
-            t.setAttribute("aria-selected", on ? "true" : "false");
-            t.tabIndex = on ? 0 : -1;
-        }
-        for (const panel of root.querySelectorAll<HTMLElement>("[data-lang-panel]")) {
-            panel.hidden = panel.dataset.langPanel !== id;
-        }
-        return true;
-    };
-
-    const select = (id: string) => {
-        writeStored(id);
-        for (const root of roots) activate(root, id);
-    };
-
-    const stored = readStored();
-    for (const root of roots) {
-        const first = triggersOf(root)[0]?.dataset.langTrigger;
-        if (!(stored && activate(root, stored)) && first) activate(root, first);
-        root.dataset.ready = "";
-
-        root.addEventListener("click", (event) => {
-            const trigger = (event.target as HTMLElement | null)?.closest<HTMLElement>("[data-lang-trigger]");
-            if (!trigger?.dataset.langTrigger) return;
-            // Keep the clicked tab under the pointer when other groups above it change height.
-            const top = trigger.getBoundingClientRect().top;
-            select(trigger.dataset.langTrigger);
-            window.scrollBy(0, trigger.getBoundingClientRect().top - top);
-        });
-
-        root.addEventListener("keydown", (event) => {
-            const triggers = triggersOf(root);
-            const index = triggers.indexOf(event.target as HTMLElement);
-            if (index === -1) return;
-            const step = event.key === "ArrowRight" ? 1 : event.key === "ArrowLeft" ? -1 : 0;
-            if (!step) return;
-            event.preventDefault();
-            const next = triggers[(index + step + triggers.length) % triggers.length];
-            if (next?.dataset.langTrigger) {
-                select(next.dataset.langTrigger);
-                next.focus();
-            }
-        });
-    }
+    import "../../lib/docs-tabs";
 </script>

apps/landing/src/components/icons/TypeScriptLogo.astro

@@ -0,0 +1,17 @@
+---
+interface Props {
+    class?: string;
+}
+
+const { class: className = "w-3.5 h-3.5" } = Astro.props;
+---
+
+<svg
+    class={className}
+    viewBox="0 0 24 24"
+    fill="#3178C6"
+    aria-hidden="true"
+>
+    <title>TypeScript</title>
+    <path d="M1.125 0C.502 0 0 .502 0 1.125v21.75C0 23.498.502 24 1.125 24h21.75c.623 0 1.125-.502 1.125-1.125V1.125C24 .502 23.498 0 22.875 0zm17.363 9.75c.612 0 1.154.037 1.627.111a6.38 6.38 0 0 1 1.306.34v2.458a3.95 3.95 0 0 0-.643-.361 5.093 5.093 0 0 0-.717-.26 5.453 5.453 0 0 0-1.426-.2c-.3 0-.573.028-.819.086a2.1 2.1 0 0 0-.623.242c-.17.104-.3.229-.393.374a.888.888 0 0 0-.14.49c0 .196.053.373.156.529.104.156.252.304.443.444s.423.276.696.41c.273.135.582.274.926.416.47.197.892.407 1.266.628.374.222.695.473.963.753.268.279.472.598.614.957.142.359.214.776.214 1.253 0 .657-.125 1.21-.373 1.656a3.033 3.033 0 0 1-1.012 1.085 4.38 4.38 0 0 1-1.487.596c-.566.12-1.163.18-1.79.18a9.916 9.916 0 0 1-1.84-.164 5.544 5.544 0 0 1-1.512-.493v-2.63a5.033 5.033 0 0 0 3.237 1.2c.333 0 .624-.03.872-.09.249-.06.456-.144.623-.25.166-.108.29-.234.373-.38a1.023 1.023 0 0 0-.074-1.089 2.12 2.12 0 0 0-.537-.5 5.597 5.597 0 0 0-.807-.444 27.72 27.72 0 0 0-1.007-.436c-.918-.383-1.602-.852-2.053-1.405-.45-.553-.676-1.222-.676-2.005 0-.614.123-1.141.369-1.582.246-.441.58-.804 1.004-1.089a4.494 4.494 0 0 1 1.47-.629 7.536 7.536 0 0 1 1.77-.201zm-15.113.188h9.563v2.166H9.506v9.646H6.789v-9.646H3.375z" />
+</svg>

apps/landing/src/content.config.ts

@@ -1,5 +1,6 @@
 import { defineCollection, reference, z } from "astro:content"
 import { glob } from "astro/loaders"
+import { BRAND_MARKS, type BrandMarkId } from "./lib/brand-marks"
 import { LANGUAGE_IDS } from "./lib/docs-languages"
 import { CHANGELOG_CATEGORIES, CONTRIBUTOR_IDS } from "./lib/changelog-meta"
 
@@ -28,6 +29,9 @@ const docs = defineCollection({
 		// ("Node.js" for "Node.js Instrumentation").
 		navLabel: z.string().optional(),
 		sdk: z.enum(LANGUAGE_IDS).optional(),
+		// Brand mark on the sidebar row, for guides that aren't a language (`sdk`),
+		// like the frontend framework guides.
+		icon: z.enum(Object.keys(BRAND_MARKS) as [BrandMarkId, ...BrandMarkId[]]).optional(),
 	}),
 })