From cecbfe2e492b8f9e00a9089b5ee86f36c8a766b2 Mon Sep 17 00:00:00 2001 From: Railly Hugo Date: Thu, 1 Oct 2026 02:58:45 -0300 Subject: [PATCH] docs: descriptive page titles and structured data for search --- apps/docs/content/docs/agents.mdx | 5 ++- apps/docs/content/docs/backlog.mdx | 5 ++- apps/docs/content/docs/dashboard.mdx | 5 ++- apps/docs/content/docs/get-started.mdx | 5 ++- apps/docs/content/docs/graph.mdx | 5 ++- apps/docs/content/docs/index.mdx | 5 ++- apps/docs/content/docs/library.mdx | 5 ++- apps/docs/content/docs/reference.mdx | 5 ++- apps/docs/content/docs/security.mdx | 5 ++- apps/docs/content/docs/status.mdx | 5 ++- apps/docs/src/app/docs/[[...slug]]/page.tsx | 43 ++++++++++++++++++++- apps/docs/src/app/page.tsx | 31 ++++++++++++--- apps/docs/tests/content.test.ts | 2 +- 13 files changed, 98 insertions(+), 28 deletions(-) diff --git a/apps/docs/content/docs/agents.mdx b/apps/docs/content/docs/agents.mdx index 1ab2ade..cc0bb08 100644 --- a/apps/docs/content/docs/agents.mdx +++ b/apps/docs/content/docs/agents.mdx @@ -1,6 +1,7 @@ --- -title: Agents and skills -description: Install the issue-graph skill and use it to trace issues, check PR status, and review backlogs. +title: Agent skill for issue and PR context +navTitle: Agents and skills +description: Install the issue-graph agent skill so coding agents can trace issues, check PR status, review backlogs, and return exact dashboard links. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/backlog.mdx b/apps/docs/content/docs/backlog.mdx index 5e078d1..5cb0d5b 100644 --- a/apps/docs/content/docs/backlog.mdx +++ b/apps/docs/content/docs/backlog.mdx @@ -1,6 +1,7 @@ --- -title: Reconcile and plan -description: Find backlog items to verify and get an ordered queue of reviews and investigations. +title: Reconcile a backlog and plan reviews +navTitle: Reconcile and plan +description: Find backlog items to verify, review suggested actions, check coverage, compare competing PRs, and get an ordered queue of reviews. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/dashboard.mdx b/apps/docs/content/docs/dashboard.mdx index cfd9cd4..442ea4f 100644 --- a/apps/docs/content/docs/dashboard.mdx +++ b/apps/docs/content/docs/dashboard.mdx @@ -1,6 +1,7 @@ --- -title: Dashboard and saved queries -description: Filter captured work, open an exact dashboard view, replay decisions, and configure scoring defaults. +title: Dashboard, saved queries, and filters +navTitle: Dashboard and saved queries +description: Capture a repository, filter and rank its open work, open an exact dashboard view, replay past decisions, and keep scoring defaults. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/get-started.mdx b/apps/docs/content/docs/get-started.mdx index 3f6be86..074ad96 100644 --- a/apps/docs/content/docs/get-started.mdx +++ b/apps/docs/content/docs/get-started.mdx @@ -1,6 +1,7 @@ --- -title: Get started -description: Install issue-graph, sign in with GitHub CLI, and trace your first issue. +title: Install the CLI and trace your first issue +navTitle: Get started +description: Install issue-graph from npm, sign in with GitHub CLI, trace your first issue, and save the result as JSON or an HTML explorer. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/graph.mdx b/apps/docs/content/docs/graph.mdx index 9e5b159..8aaa93a 100644 --- a/apps/docs/content/docs/graph.mdx +++ b/apps/docs/content/docs/graph.mdx @@ -1,6 +1,7 @@ --- -title: Graph -description: Trace linked issues and pull requests, compare saved results, and export an HTML explorer. +title: Trace linked issues and pull requests +navTitle: Graph +description: Trace the issues and pull requests linked to one item, control crawl depth and budget, compare snapshots, and export JSON or HTML. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx index a7223f8..1a92e42 100644 --- a/apps/docs/content/docs/index.mdx +++ b/apps/docs/content/docs/index.mdx @@ -1,6 +1,7 @@ --- -title: Overview -description: Find related issues, check pull request status, and plan backlog reviews from your terminal. +title: Map related issues and pull requests +navTitle: Overview +description: Trace related issues and pull requests from your terminal, check review status, find existing fixes, and choose what to review next. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/library.mdx b/apps/docs/content/docs/library.mdx index 13d1c45..c2c7c40 100644 --- a/apps/docs/content/docs/library.mdx +++ b/apps/docs/content/docs/library.mdx @@ -1,6 +1,7 @@ --- -title: Library -description: Use issue-graph in your application with a GitHub CLI or HTTP transport. +title: Use issue-graph as a library +navTitle: Library +description: Use issue-graph in your application to crawl issue graphs, collect PR status, and query dashboard models over HTTP or GitHub CLI. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/reference.mdx b/apps/docs/content/docs/reference.mdx index f2258ac..cb46015 100644 --- a/apps/docs/content/docs/reference.mdx +++ b/apps/docs/content/docs/reference.mdx @@ -1,6 +1,7 @@ --- -title: Command reference -description: Look up CLI commands, flags, output formats, storage options, and exit codes. +title: CLI command reference and exit codes +navTitle: Command reference +description: Look up issue-graph commands, flags, output formats, crawl controls, storage options, and exit codes, plus help and JSON schema output. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/security.mdx b/apps/docs/content/docs/security.mdx index 17c36d5..d53c843 100644 --- a/apps/docs/content/docs/security.mdx +++ b/apps/docs/content/docs/security.mdx @@ -1,6 +1,7 @@ --- -title: Permissions and privacy -description: Configure GitHub access and understand which commands save files or send data to an external agent. +title: Permissions, local files, and privacy +navTitle: Permissions and privacy +description: Configure GitHub access, see which commands save local files or send data to an external agent, and share captured results carefully. lastModified: 2026-09-27 --- diff --git a/apps/docs/content/docs/status.mdx b/apps/docs/content/docs/status.mdx index 1b7093d..07423e6 100644 --- a/apps/docs/content/docs/status.mdx +++ b/apps/docs/content/docs/status.mdx @@ -1,6 +1,7 @@ --- -title: Status and history -description: Count pull requests by author and repository, check review states, and compare saved reports. +title: Pull request status and review history +navTitle: Status and history +description: Check open pull requests by repository and author, read review-state counts and draft or conflict flags, pick an output format, and compare captures. lastModified: 2026-09-27 --- diff --git a/apps/docs/src/app/docs/[[...slug]]/page.tsx b/apps/docs/src/app/docs/[[...slug]]/page.tsx index b42fb5f..2b215e3 100644 --- a/apps/docs/src/app/docs/[[...slug]]/page.tsx +++ b/apps/docs/src/app/docs/[[...slug]]/page.tsx @@ -6,7 +6,7 @@ import { docsPath, isSafePathSegments, markdownPath } from "@/lib/docs-paths"; import { config } from "@/lib/geistdocs/config"; import { geistdocsSource } from "@/lib/geistdocs/source"; import { pageMetadata } from "@/lib/page-metadata"; -import { siteDescription } from "@/lib/site"; +import { canonicalUrl, siteDescription, siteName } from "@/lib/site"; type PageProps = { params: Promise<{ slug?: string[] }> }; @@ -34,7 +34,46 @@ const docsPage = createDocsPage({ export default async function Page({ params }: PageProps) { const validated = await getPage(params); - return ; + const { page } = validated; + const url = canonicalUrl(docsPath(page.slugs)); + // The Geistdocs frontmatter schema keeps navTitle, but PageData does not type it. + const { navTitle } = page.data as { navTitle?: string }; + const structuredData = { + "@context": "https://schema.org", + "@graph": [ + { + "@type": "TechArticle", + headline: page.data.title, + description: page.data.description ?? siteDescription, + url, + isPartOf: { "@type": "WebSite", name: siteName, url: canonicalUrl("/") }, + }, + { + "@type": "BreadcrumbList", + itemListElement: [ + { "@type": "ListItem", position: 1, name: "Docs", item: canonicalUrl("/docs") }, + ...(page.slugs.length + ? [ + { + "@type": "ListItem", + position: 2, + name: navTitle ?? page.data.title, + item: url, + }, + ] + : []), + ], + }, + ], + }; + return ( + <> + + + + ); } export async function generateMetadata({ params }: PageProps) { diff --git a/apps/docs/src/app/page.tsx b/apps/docs/src/app/page.tsx index 76af48d..5c79e93 100644 --- a/apps/docs/src/app/page.tsx +++ b/apps/docs/src/app/page.tsx @@ -5,7 +5,13 @@ import { InstallSelector } from "@/components/install-selector"; import { renderTerminalCommand } from "@/components/terminal-output"; import { landingDescription, landingTitle, workflows } from "@/lib/landing-content"; import { pageMetadata } from "@/lib/page-metadata"; -import { plannedInstallCommand, siteDescription, siteName, siteUrl } from "@/lib/site"; +import { + plannedInstallCommand, + repositoryUrl, + siteDescription, + siteName, + siteUrl, +} from "@/lib/site"; import "@/components/landing.css"; export const metadata = pageMetadata("/", landingTitle, siteDescription); @@ -13,10 +19,25 @@ export const metadata = pageMetadata("/", landingTitle, siteDescription); export default function Home() { const structuredData = { "@context": "https://schema.org", - "@type": "WebSite", - name: siteName, - url: siteUrl, - description: siteDescription, + "@graph": [ + { + "@type": "WebSite", + name: siteName, + url: siteUrl, + description: siteDescription, + }, + { + "@type": "SoftwareApplication", + name: siteName, + url: siteUrl, + description: siteDescription, + applicationCategory: "DeveloperApplication", + operatingSystem: "Node.js 20+", + license: "https://www.apache.org/licenses/LICENSE-2.0", + sameAs: [repositoryUrl, "https://www.npmjs.com/package/issue-graph"], + offers: { "@type": "Offer", price: "0", priceCurrency: "USD" }, + }, + ], }; return ( diff --git a/apps/docs/tests/content.test.ts b/apps/docs/tests/content.test.ts index b9c88ac..43d7132 100644 --- a/apps/docs/tests/content.test.ts +++ b/apps/docs/tests/content.test.ts @@ -50,7 +50,7 @@ describe("documentation content contract", () => { test("names the docs entry Overview", async () => { const intro = await read("content/docs/index.mdx"); - expect(intro).toMatch(/^title: Overview$/m); + expect(intro).toMatch(/^navTitle: Overview$/m); }); test("documents published npm-first installation and preserves access boundaries", async () => {