diff --git a/astro.config.mjs b/astro.config.mjs index b0074833..196d954e 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -27,6 +27,7 @@ import { SUPPORTED_LANGUAGES, SITE_TITLES } from "./src/config/i18n"; import { firebaseIntegration } from "./src/integrations/firebase"; import { remarkClientOnly } from "./src/plugins"; import { devServerFileWatcher } from "./src/integrations/dev-server-file-watcher"; +import { llmsTxtIndex } from "./src/integrations/llms-txt-index"; import onDemandDirective from "./src/integrations/client-on-demand/register.js"; import { cspConfig } from "./src/config/csp"; import { monacoEditorIntegration } from "./src/integrations/monacoEditor"; @@ -152,6 +153,20 @@ export default defineConfig({ }), starlightLlmsTxt({ rawContent: true, + description: + "Developer documentation for the Aptos blockchain — Move smart contracts, SDKs, APIs, indexer, node operations, and AI tools.", + optionalLinks: [ + { + label: "Aptos MCP Server", + url: "https://www.npmjs.com/package/@anthropic-ai/aptos-mcp", + description: "MCP server for AI coding tools", + }, + { + label: "Aptos GitHub", + url: "https://github.com/aptos-labs", + description: "Official source code repositories", + }, + ], promote: [ "index*", "get-started", @@ -197,6 +212,10 @@ export default defineConfig({ sidebar, customCss: ["./src/styles/global.css", "katex/dist/katex.min.css"], }), + // Override the starlight-llms-txt plugin's /llms.txt index with a structured + // version that lists page titles, descriptions, and per-page .md URLs. + // Must be after Starlight so our injected route takes priority. + llmsTxtIndex(), sitemap({ serialize(item) { item.lastmod = new Date().toISOString(); diff --git a/src/content/docs/build/ai.mdx b/src/content/docs/build/ai.mdx index 553626cd..7c7c083a 100644 --- a/src/content/docs/build/ai.mdx +++ b/src/content/docs/build/ai.mdx @@ -11,6 +11,10 @@ Aptos provides first-class support for AI-powered development workflows. Whether assistant or an AI chat tool, you can give it deep knowledge of the Aptos blockchain, Move language, SDKs, and APIs. +## AskAptos Chatbot + +The AskAptos chatbot is built into the documentation site — look for it in the top-right corner of the navigation bar. It can answer questions about Aptos concepts, help you plan implementations, and point you to the right documentation pages. + ## Aptos MCP Server The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets AI coding tools directly call @@ -27,10 +31,10 @@ Aptos APIs, query on-chain data, and generate correct Aptos code — without nee The [LLMs.txt standard](https://llmstxt.org/) provides machine-readable documentation feeds that AI tools can ingest to understand the full Aptos documentation. We publish three feeds to suit different context window sizes: -| Feed | URL | Best for | -| ------------------ | ------------------------------------ | ------------------------------------------- | -| **llms.txt** | [`/llms.txt`](/llms.txt) | Structured index of all doc sections | -| **llms-small.txt** | [`/llms-small.txt`](/llms-small.txt) | Condensed docs for smaller context windows | -| **llms-full.txt** | [`/llms-full.txt`](/llms-full.txt) | Full documentation — all pages concatenated | +| Feed | URL | Best for | +| ------------------ | ------------------------------------ | ------------------------------------------------------------------------- | +| **llms.txt** | [`/llms.txt`](/llms.txt) | Structured index with page titles, descriptions, and per-page `.md` links | +| **llms-small.txt** | [`/llms-small.txt`](/llms-small.txt) | Condensed docs for smaller context windows | +| **llms-full.txt** | [`/llms-full.txt`](/llms-full.txt) | Full documentation — all pages concatenated | diff --git a/src/content/docs/es/build/ai.mdx b/src/content/docs/es/build/ai.mdx index 9fc49662..21062d9f 100644 --- a/src/content/docs/es/build/ai.mdx +++ b/src/content/docs/es/build/ai.mdx @@ -11,6 +11,10 @@ Aptos ofrece soporte de primera clase para flujos de trabajo de desarrollo poten un asistente de codificación con IA o una herramienta de chat con IA, puedes darle un conocimiento profundo de la blockchain Aptos, el lenguaje Move, SDKs y APIs. +## Chatbot AskAptos + +El chatbot AskAptos está integrado en el sitio de documentación — búscalo en la esquina superior derecha de la barra de navegación. Puede responder preguntas sobre conceptos de Aptos, ayudarte a planificar implementaciones y dirigirte a las páginas de documentación correctas. + ## Servidor MCP de Aptos El [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) permite que las herramientas de codificación @@ -29,10 +33,10 @@ El [estándar LLMs.txt](https://llmstxt.org/) proporciona feeds de documentació herramientas de IA pueden ingerir para comprender la documentación completa de Aptos. Publicamos tres feeds para adaptarse a diferentes tamaños de ventana de contexto: -| Feed | URL | Ideal para | -| ------------------ | ------------------------------------ | --------------------------------------------------------------- | -| **llms.txt** | [`/llms.txt`](/llms.txt) | Índice estructurado de todas las secciones de documentación | -| **llms-small.txt** | [`/llms-small.txt`](/llms-small.txt) | Documentación condensada para ventanas de contexto más pequeñas | -| **llms-full.txt** | [`/llms-full.txt`](/llms-full.txt) | Documentación completa — todas las páginas concatenadas | +| Feed | URL | Ideal para | +| ------------------ | ------------------------------------ | ------------------------------------------------------------------------- | +| **llms.txt** | [`/llms.txt`](/llms.txt) | Índice estructurado con títulos, descripciones y enlaces `.md` por página | +| **llms-small.txt** | [`/llms-small.txt`](/llms-small.txt) | Documentación condensada para ventanas de contexto más pequeñas | +| **llms-full.txt** | [`/llms-full.txt`](/llms-full.txt) | Documentación completa — todas las páginas concatenadas | diff --git a/src/content/docs/es/index.mdx b/src/content/docs/es/index.mdx index 0a6302c7..abe7978a 100644 --- a/src/content/docs/es/index.mdx +++ b/src/content/docs/es/index.mdx @@ -34,7 +34,7 @@ import ListCard from '~/components/ListCard.astro'; - - [¡Nuevo! Chatbot de IA AskAptos](#) Consulta documentación, planifica o refina requisitos con IA (¡arriba a la derecha!). + - [¡Nuevo! Chatbot de IA AskAptos](/es/build/ai) Consulta documentación, planifica o refina requisitos con IA (¡arriba a la derecha!). - [Testnet Faucet](/es/network/faucet) Financia tu cuenta de testnet con APT para comenzar a construir. - [SDKs Oficiales](/es/build/sdks) TypeScript, Go, Java, Python, Rust, C++, Unity y más. - [Aptos CLI](/es/build/cli) Compila, prueba, publica contratos; cuentas y claves; localnet. diff --git a/src/content/docs/es/llms-txt.mdx b/src/content/docs/es/llms-txt.mdx index a54d8e1c..5d6f1bdb 100644 --- a/src/content/docs/es/llms-txt.mdx +++ b/src/content/docs/es/llms-txt.mdx @@ -15,8 +15,27 @@ Proporcionamos las siguientes rutas de LLMs.txt para ayudar a las herramientas d - [llms-small.txt](/llms-small.txt) - Proporciona una versión condensada de la documentación, optimizada para ventanas de contexto más pequeñas - [llms-full.txt](/llms-full.txt) - Proporciona la documentación completa y exhaustiva para todos los conceptos de Aptos +## Acceso Markdown por Página + +Cada página de documentación también está disponible como Markdown sin procesar agregando `.md` a la URL: + +| URL de la Página | URL Markdown | +| -------------------------------------------------- | ----------------------------------------------------- | +| `https://aptos.dev/build/guides/first-transaction` | `https://aptos.dev/build/guides/first-transaction.md` | +| `https://aptos.dev/build/sdks/ts-sdk` | `https://aptos.dev/build/sdks/ts-sdk.md` | + +Esto es útil para herramientas de IA que necesitan obtener páginas individuales con el mínimo de tokens, en lugar de ingerir la documentación completa. El índice [llms.txt](/llms.txt) lista todas las páginas con sus URLs `.md` y descripciones para que tu herramienta de IA pueda elegir exactamente qué páginas leer. + ## Uso con Herramientas de IA +### Claude Code + +Agrega el contexto de la documentación de Aptos a proyectos de [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview): + +1. Agrega `https://aptos.dev/llms.txt` al archivo `CLAUDE.md` de tu proyecto como referencia +2. Claude Code leerá el índice y obtendrá las páginas relevantes a través de URLs `.md` según sea necesario +3. Para una integración más profunda con herramientas on-chain, consulta [Aptos MCP para Claude Code](/es/build/ai/aptos-mcp/claude) + ### Cursor Usa la función `@Docs` en Cursor para incluir los archivos LLMs.txt en tu proyecto. Esto ayuda a Cursor a proporcionar sugerencias de código y documentación más precisas para el desarrollo en Aptos. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 13c5f55a..af253727 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -34,7 +34,7 @@ import ListCard from '~/components/ListCard.astro'; - - [NEW! AskAptos AI Chatbot](#) Query docs, plan or refine requirements with AI (top right!). + - [NEW! AskAptos AI Chatbot](/build/ai) Query docs, plan or refine requirements with AI (top right!). - [Testnet Faucet](/network/faucet) Fund your testnet account with APT to start building. - [Official SDKs](/build/sdks) TypeScript, Go, Java, Python, Rust, C++, Unity, and more. - [Aptos CLI](/build/cli) Compile, test, publish contracts; accounts & keys; localnet. diff --git a/src/content/docs/llms-txt.mdx b/src/content/docs/llms-txt.mdx index 52be4b5d..381587d1 100644 --- a/src/content/docs/llms-txt.mdx +++ b/src/content/docs/llms-txt.mdx @@ -16,8 +16,27 @@ We provide the following LLMs.txt routes to help AI tools access our documentati - [llms-small.txt](/llms-small.txt) - Provides a condensed version of the documentation, optimized for smaller context windows - [llms-full.txt](/llms-full.txt) - Provides the full comprehensive documentation for all Aptos concepts +## Per-Page Markdown Access + +Every documentation page is also available as raw Markdown by appending `.md` to the URL: + +| Page URL | Markdown URL | +| -------------------------------------------------- | ----------------------------------------------------- | +| `https://aptos.dev/build/guides/first-transaction` | `https://aptos.dev/build/guides/first-transaction.md` | +| `https://aptos.dev/build/sdks/ts-sdk` | `https://aptos.dev/build/sdks/ts-sdk.md` | + +This is useful for AI tools that need to fetch individual pages with minimal tokens, rather than ingesting the full documentation. The [llms.txt](/llms.txt) index lists all pages with their `.md` URLs and descriptions so your AI tool can pick exactly which pages to read. + ## Usage with AI Tools +### Claude Code + +Add Aptos documentation context to [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) projects: + +1. Add `https://aptos.dev/llms.txt` to your project's `CLAUDE.md` file as a reference +2. Claude Code will read the index and fetch relevant pages via `.md` URLs as needed +3. For deeper integration with on-chain tools, see [Aptos MCP for Claude Code](/build/ai/aptos-mcp/claude) + ### Cursor Use the `@Docs` feature in Cursor to include the LLMs.txt files in your project. This helps Cursor provide more accurate diff --git a/src/content/docs/zh/build/ai.mdx b/src/content/docs/zh/build/ai.mdx index 2452890b..5960758f 100644 --- a/src/content/docs/zh/build/ai.mdx +++ b/src/content/docs/zh/build/ai.mdx @@ -10,6 +10,10 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components'; Aptos 为 AI 驱动的开发工作流提供一流支持。无论您使用的是 AI 编程助手还是 AI 聊天工具， 都可以让它深入了解 Aptos 区块链、Move 语言、SDK 和 API。 +## AskAptos 聊天机器人 + +AskAptos 聊天机器人已内置于文档站点中——在导航栏右上角查找即可。它可以回答关于 Aptos 概念的问题，帮助您规划实现方案，并指引您到正确的文档页面。 + ## Aptos MCP 服务器 [模型上下文协议 (MCP)](https://modelcontextprotocol.io/) 让 AI 编程工具能够直接调用 Aptos API、 @@ -26,10 +30,10 @@ Aptos 为 AI 驱动的开发工作流提供一流支持。无论您使用的是 [LLMs.txt 标准](https://llmstxt.org/)提供机器可读的文档源，AI 工具可以摄取这些内容以理解完整的 Aptos 文档。我们发布三种文档源以适应不同的上下文窗口大小： -| 文档源 | URL | 最适合 | -| ------------------ | ------------------------------------ | --------------- | -| **llms.txt** | [`/llms.txt`](/llms.txt) | 所有文档章节的结构化索引 | -| **llms-small.txt** | [`/llms-small.txt`](/llms-small.txt) | 适合较小上下文窗口的压缩文档 | -| **llms-full.txt** | [`/llms-full.txt`](/llms-full.txt) | 完整文档——所有页面串联在一起 | +| 文档源 | URL | 最适合 | +| ------------------ | ------------------------------------ | --------------------------- | +| **llms.txt** | [`/llms.txt`](/llms.txt) | 包含页面标题、描述和逐页 `.md` 链接的结构化索引 | +| **llms-small.txt** | [`/llms-small.txt`](/llms-small.txt) | 适合较小上下文窗口的压缩文档 | +| **llms-full.txt** | [`/llms-full.txt`](/llms-full.txt) | 完整文档——所有页面串联在一起 | diff --git a/src/content/docs/zh/index.mdx b/src/content/docs/zh/index.mdx index 01d0dfbd..b32e2ce3 100644 --- a/src/content/docs/zh/index.mdx +++ b/src/content/docs/zh/index.mdx @@ -34,7 +34,7 @@ import ListCard from '~/components/ListCard.astro'; - - [新！AskAptos AI 聊天机器人](#) 查询文档，规划或完善需求（右上角！）。 + - [新！AskAptos AI 聊天机器人](/zh/build/ai) 查询文档，规划或完善需求（右上角！）。 - [测试网水龙头](/zh/network/faucet) 为你的测试网账户提供 APT 资金以开始构建。 - [官方 SDK](/zh/build/sdks) TypeScript、Go、Java、Python、Rust、C++、Unity 等。 - [Aptos CLI](/zh/build/cli) 编译、测试、发布合约；账户和密钥；本地网络。 diff --git a/src/content/docs/zh/llms-txt.mdx b/src/content/docs/zh/llms-txt.mdx index 7ae64cdd..9483b785 100644 --- a/src/content/docs/zh/llms-txt.mdx +++ b/src/content/docs/zh/llms-txt.mdx @@ -16,8 +16,27 @@ description: 如何让 Cursor、GitHub Copilot、ChatGPT 和 Claude 等工具理 - [llms-small.txt](/llms-small.txt) - 提供文档的压缩版本，针对较小的上下文窗口进行了优化 - [llms-full.txt](/llms-full.txt) - 提供所有 Aptos 概念的完整综合文档 +## 逐页 Markdown 访问 + +每个文档页面也可以通过在 URL 后添加 `.md` 获取原始 Markdown 格式： + +| 页面 URL | Markdown URL | +| -------------------------------------------------- | ----------------------------------------------------- | +| `https://aptos.dev/build/guides/first-transaction` | `https://aptos.dev/build/guides/first-transaction.md` | +| `https://aptos.dev/build/sdks/ts-sdk` | `https://aptos.dev/build/sdks/ts-sdk.md` | + +这对于需要以最少 token 获取单个页面的 AI 工具非常有用，而不必摄取完整的文档。[llms.txt](/llms.txt) 索引列出了所有页面及其 `.md` URL 和描述，以便您的 AI 工具可以准确选择要阅读的页面。 + ## 与 AI 工具的使用 +### Claude Code + +将 Aptos 文档上下文添加到 [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) 项目： + +1. 将 `https://aptos.dev/llms.txt` 添加到项目的 `CLAUDE.md` 文件中作为参考 +2. Claude Code 会读取索引并根据需要通过 `.md` URL 获取相关页面 +3. 如需更深层次的链上工具集成，请参阅 [Aptos MCP for Claude Code](/zh/build/ai/aptos-mcp/claude) + ### Cursor 在 Cursor 中使用 `@Docs` 功能将 LLMs.txt 文件包含在您的项目中。这有助于 Cursor 为 Aptos 开发提供更准确的代码建议和文档。 diff --git a/src/integrations/llms-txt-index.ts b/src/integrations/llms-txt-index.ts new file mode 100644 index 00000000..1f1f5033 --- /dev/null +++ b/src/integrations/llms-txt-index.ts @@ -0,0 +1,25 @@ +import type { AstroIntegration, RouteOptions } from "astro"; + +/** + * Overrides the starlight-llms-txt plugin's /llms.txt index route with a structured + * version that lists all pages with titles, descriptions, and per-page .md URLs. + * + * Uses the astro:route:setup hook to swap the plugin's entrypoint for our custom handler + * while keeping the llms-full.txt and llms-small.txt routes from the plugin untouched. + */ +export function llmsTxtIndex(): AstroIntegration { + return { + name: "llms-txt-index", + hooks: { + "astro:route:setup": ({ route }: { route: RouteOptions }) => { + // Only override the plugin's /llms.txt index route (not full/small/custom) + if ( + route.component.includes("starlight-llms-txt") && + route.component.endsWith("/llms.txt.ts") + ) { + (route as { component: string }).component = "./src/pages/llms-index.ts"; + } + }, + }, + }; +} diff --git a/src/pages/llms-index.ts b/src/pages/llms-index.ts new file mode 100644 index 00000000..4bd754ee --- /dev/null +++ b/src/pages/llms-index.ts @@ -0,0 +1,183 @@ +import type { APIRoute } from "astro"; +import { getCollection } from "astro:content"; + +export const prerender = true; + +const SITE_URL = import.meta.env.SITE; + +// Pages to exclude from the index entirely +const EXCLUDE_PAGES = new Set(["contribute/components/themed-image"]); + +// Top-level section grouping and display order +const SECTION_CONFIG: Record = { + "build/get-started": "Getting Started", + "build/guides": "Guides", + "build/sdks": "SDKs", + "build/smart-contracts": "Smart Contracts", + "build/apis": "APIs", + "build/cli": "CLI", + "build/indexer": "Indexer", + "build/ai": "AI Tools", + "build/aips": "AIPs (Aptos Improvement Proposals)", + "build/create-aptos-dapp": "Create Aptos Dapp", + "network/blockchain": "Blockchain Concepts", + "network/nodes": "Nodes", + "network/faucet": "Faucet", + "network/glossary": "Glossary", + "network/releases": "Releases", +}; + +interface Doc { + id: string; + data: { title: string; description?: string }; +} + +function getSectionKey(slug: string): string { + const keys = Object.keys(SECTION_CONFIG).sort((a, b) => b.length - a.length); + for (const key of keys) { + if (slug.startsWith(key)) return key; + } + return "other"; +} + +/** + * Derive sub-section key from page path. For a page like + * "build/sdks/ts-sdk/account", the sub-section is "build/sdks/ts-sdk". + * Only creates a sub-section if there's a directory level between the + * section root and the page (i.e., depth >= section + 2 segments). + */ +function getSubSectionKey(slug: string, sectionKey: string): string | null { + const remainder = slug.slice(sectionKey.length + 1); // after "build/sdks/" + if (!remainder) return null; + const parts = remainder.split("/"); + const first = parts[0]; + if (parts.length < 2 || !first) return null; // direct child of section, no sub-section + return `${sectionKey}/${first}`; +} + +function formatEntry(doc: Doc): string { + const url = `${SITE_URL}/${doc.id}.md`; + const desc = doc.data.description ? `: ${doc.data.description}` : ""; + return `- [${doc.data.title}](${url})${desc}`; +} + +export const GET: APIRoute = async () => { + // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call + const docs = await getCollection("docs"); + + // Filter to English-only, exclude 404, locale roots, and excluded pages + const englishDocs = (docs as Doc[]) + .filter( + (doc) => + !doc.id.startsWith("es/") && + !doc.id.startsWith("zh/") && + doc.id !== "es" && + doc.id !== "zh" && + !doc.id.includes("404") && + !EXCLUDE_PAGES.has(doc.id), + ) + .sort((a, b) => a.id.localeCompare(b.id)); + + // Group by section + const sections = new Map(); + const topLevel: Doc[] = []; + + for (const doc of englishDocs) { + const sectionKey = getSectionKey(doc.id); + if (sectionKey === "other") { + topLevel.push(doc); + } else { + if (!sections.has(sectionKey)) sections.set(sectionKey, []); + const sectionList = sections.get(sectionKey); + if (sectionList) sectionList.push(doc); + } + } + + // Build a lookup of slug -> doc for sub-section title resolution + const docsBySlug = new Map(); + for (const doc of englishDocs) { + docsBySlug.set(doc.id, doc); + } + + const lines: string[] = [ + "# Aptos Developer Documentation", + "", + "> Developer documentation for the Aptos blockchain — Move smart contracts, SDKs, APIs, indexer, node operations, and AI tools.", + "", + "This file lists all documentation pages with descriptions. Each page is also available as raw Markdown by appending `.md` to its URL (e.g. `https://aptos.dev/build/guides/first-transaction.md`).", + "", + "## Full Documentation", + "", + `- [Complete documentation](${SITE_URL}/llms-full.txt): All pages concatenated into a single file`, + `- [Abridged documentation](${SITE_URL}/llms-small.txt): Condensed version for smaller context windows`, + "", + ]; + + // Top-level pages + for (const doc of topLevel) { + lines.push(formatEntry(doc)); + } + if (topLevel.length > 0) lines.push(""); + + // Grouped sections with auto-derived sub-sections + for (const [sectionKey, sectionLabel] of Object.entries(SECTION_CONFIG)) { + const sectionDocs = sections.get(sectionKey); + if (!sectionDocs || sectionDocs.length === 0) continue; + + lines.push(`## ${sectionLabel}`); + lines.push(""); + + // Split into direct children and sub-sectioned pages + const directChildren: Doc[] = []; + const subSections = new Map(); + const subSectionOrder: string[] = []; + + for (const doc of sectionDocs) { + const subKey = getSubSectionKey(doc.id, sectionKey); + if (subKey) { + if (!subSections.has(subKey)) { + subSections.set(subKey, []); + subSectionOrder.push(subKey); + } + const subList = subSections.get(subKey); + if (subList) subList.push(doc); + } else { + directChildren.push(doc); + } + } + + // Print direct children first + for (const doc of directChildren) { + lines.push(formatEntry(doc)); + } + + // Print sub-sections + for (const subKey of subSectionOrder) { + const subDocs = subSections.get(subKey); + if (!subDocs || subDocs.length === 0) continue; + + // Use the index page's title as the sub-section header, or derive from path + const indexDoc = docsBySlug.get(subKey); + const fallback = subKey.split("/").pop() ?? subKey; + const subLabel = indexDoc ? indexDoc.data.title : fallback; + + lines.push(""); + lines.push(`### ${subLabel}`); + lines.push(""); + + for (const doc of subDocs) { + lines.push(formatEntry(doc)); + } + } + + lines.push(""); + } + + return new Response(lines.join("\n"), { + status: 200, + headers: { + "Content-Type": "text/plain; charset=utf-8", + "Cache-Control": "public, max-age=3600", + }, + }); +};