From f21372e84c6e955f82b33ff0d5a7b506166cfee6 Mon Sep 17 00:00:00 2001 From: vihar Date: Sat, 22 Aug 2026 02:00:27 +0530 Subject: [PATCH] docs: add related-site and optional sections to llms.txt, dedupe developer docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both llms.txt files only listed their own site, so an agent reading docs.plane.so had no pointer to the API reference, webhooks, MCP server or self-hosting docs (and vice versa) — one of the is-agentic discoverability findings. Following the llmstxt.org layout: - custom template on both sites adds `## Related documentation` (the other Plane docs site's llms.txt plus its key entry pages) and `## Optional` (llms-full.txt, sitemap.xml, GitHub, plane.so) - `details` now tells agents every page is available as Markdown via `.md` or `Accept: text/markdown` - developer-docs: drop the "/" shortcut sidebar from the llms.txt table of contents — its four groups repeated 14 pages that the section sidebars already list, so every page now appears exactly once - docs vercel.json: send the same `; rel="describedby"` Link header that developer-docs already sends Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01CsPSwTnpsEb5c5Ud2CLrL8 --- .../developer-docs/docs/.vitepress/config.mts | 28 ++++++++++++++++++- apps/docs/docs/.vitepress/config.ts | 22 ++++++++++++++- apps/docs/vercel.json | 2 +- 3 files changed, 49 insertions(+), 3 deletions(-) diff --git a/apps/developer-docs/docs/.vitepress/config.mts b/apps/developer-docs/docs/.vitepress/config.mts index 5a74acc0..35990fff 100644 --- a/apps/developer-docs/docs/.vitepress/config.mts +++ b/apps/developer-docs/docs/.vitepress/config.mts @@ -65,7 +65,33 @@ export default extendConfig( description: "Plane is open-source, modern project management software. These developer docs cover self-hosting, the REST API, and tools for building on Plane.", details: - "This documentation covers self-hosting (Docker, Kubernetes, and more), the REST API reference for projects, work items, cycles, modules, states, pages, and more, plus developer tools including OAuth apps, webhooks, agents, and the MCP server.", + "This documentation covers self-hosting (Docker, Kubernetes, and more), the REST API reference for projects, work items, cycles, modules, states, pages, and more, plus developer tools including OAuth apps, webhooks, agents, and the MCP server. Every page is also available as Markdown: append `.md` to its URL or request it with `Accept: text/markdown`.", + // llmstxt.org layout: H1, blockquote, details, then H2 link sections. "Related + // documentation" points agents at docs.plane.so (how to use the product) and + // "Optional" holds the bulk files they can skip. + customLLMsTxtTemplate: + "# {title}\n\n{description}\n\n{details}\n\n## Table of Contents\n\n{toc}\n\n## Related documentation\n\n{related}\n\n## Optional\n\n{optional}\n", + customTemplateVariables: { + related: [ + "- [Plane product documentation](https://docs.plane.so/llms.txt): Index of docs.plane.so — how to use Plane: workspaces, projects, work items, cycles, modules, pages, integrations, importers, automations, and Plane AI.", + "- [Core concepts](https://docs.plane.so/introduction/core-concepts.md): The building blocks the API exposes — workspaces, projects, work items, cycles, modules, views, and pages.", + "- [Quickstart](https://docs.plane.so/introduction/quickstart.md): Set up a workspace and a first project.", + "- [Roles and permissions](https://docs.plane.so/roles-and-permissions/overview.md): What each workspace and project role is allowed to do.", + ].join("\n"), + optional: [ + "- [Complete documentation in one file](https://developers.plane.so/llms-full.txt): Every page of developers.plane.so concatenated as Markdown (about 1.6 MB).", + "- [Sitemap](https://developers.plane.so/sitemap.xml): Every page URL on developers.plane.so.", + "- [Plane on GitHub](https://github.com/makeplane/plane): Source code, issues, and releases.", + "- [plane.so](https://plane.so): Product website, pricing, and sign-up.", + ].join("\n"), + }, + // The "/" sidebar only holds shortcut groups that repeat pages from the section + // sidebars, so drop it to keep every page listed exactly once. + sidebar: (configSidebar) => { + if (!configSidebar || Array.isArray(configSidebar)) return configSidebar; + const { "/": _shortcuts, ...sections } = configSidebar; + return sections; + }, // Per-page .md versions are already emitted by buildEnd() for the // `Accept: text/markdown` rewrite in vercel.json, so the plugin only // owns llms.txt / llms-full.txt. diff --git a/apps/docs/docs/.vitepress/config.ts b/apps/docs/docs/.vitepress/config.ts index ebeae667..3095a63b 100644 --- a/apps/docs/docs/.vitepress/config.ts +++ b/apps/docs/docs/.vitepress/config.ts @@ -54,7 +54,27 @@ const config = defineConfig({ description: "Plane is open-source, modern project management software for planning, tracking, and shipping work.", details: - "This documentation covers workspaces, projects, work items, cycles, modules, pages and wikis, integrations, importers, automations, and Plane AI.", + "This documentation covers workspaces, projects, work items, cycles, modules, pages and wikis, integrations, importers, automations, and Plane AI. Every page is also available as Markdown: append `.md` to its URL or request it with `Accept: text/markdown`.", + // llmstxt.org layout: H1, blockquote, details, then H2 link sections. "Related + // documentation" points agents at developers.plane.so (API, webhooks, MCP server, + // self-hosting) and "Optional" holds the bulk files they can skip. + customLLMsTxtTemplate: + "# {title}\n\n{description}\n\n{details}\n\n## Table of Contents\n\n{toc}\n\n## Related documentation\n\n{related}\n\n## Optional\n\n{optional}\n", + customTemplateVariables: { + related: [ + "- [Plane developer documentation](https://developers.plane.so/llms.txt): Index of developers.plane.so — REST API reference, webhooks, OAuth apps, the MCP server, agents, and self-hosting guides.", + "- [REST API reference](https://developers.plane.so/api-reference/introduction.md): Authentication, pagination, rate limits, and every endpoint of the Plane public API.", + "- [Webhooks](https://developers.plane.so/dev-tools/intro-webhooks.md): Real-time event notifications for work items, cycles, modules, and more.", + "- [MCP server](https://developers.plane.so/dev-tools/mcp-server.md): Let AI assistants read and update Plane through the Model Context Protocol.", + "- [Self-host Plane](https://developers.plane.so/self-hosting/overview.md): Deploy Plane with Docker Compose, Kubernetes, or Podman.", + ].join("\n"), + optional: [ + "- [Complete documentation in one file](https://docs.plane.so/llms-full.txt): Every page of docs.plane.so concatenated as Markdown (about 1 MB).", + "- [Sitemap](https://docs.plane.so/sitemap.xml): Every page URL on docs.plane.so.", + "- [Plane on GitHub](https://github.com/makeplane/plane): Source code, issues, and releases.", + "- [plane.so](https://plane.so): Product website, pricing, and sign-up.", + ].join("\n"), + }, // Per-page .md versions are already emitted by buildEnd() for the // `Accept: text/markdown` rewrite in vercel.json, so the plugin only // owns llms.txt / llms-full.txt. diff --git a/apps/docs/vercel.json b/apps/docs/vercel.json index b8862aae..8b4cda18 100644 --- a/apps/docs/vercel.json +++ b/apps/docs/vercel.json @@ -7,7 +7,7 @@ "headers": [ { "key": "Link", - "value": "; rel=\"service-doc\"; type=\"text/html\", ; rel=\"sitemap\"; type=\"application/xml\"" + "value": "; rel=\"describedby\"; type=\"text/plain\", ; rel=\"service-doc\"; type=\"text/html\", ; rel=\"sitemap\"; type=\"application/xml\"" }, { "key": "X-Robots-Tag",