docs: improve SEO (#3092)

olimorris · web-flow · commit d0bc72bf570d · 2026-05-04T17:15:06.000+01:00
diff --git a/doc/.vitepress/config.mjs b/doc/.vitepress/config.mjs
@@ -62,15 +62,38 @@ const baseHeaders = [
     },
   ],
   ["link", { rel: "icon", type: "image/png", href: "/favicon.png" }],
-  // Ensure Google displays the site as CodeCompanion.nvim in search results
   [
     "script",
     { type: "application/ld+json" },
     JSON.stringify({
       "@context": "https://schema.org",
-      "@type": "WebSite",
-      name: "CodeCompanion.nvim",
-      url: "https://codecompanion.olimorris.dev",
+      "@graph": [
+        {
+          "@type": "WebSite",
+          name: "CodeCompanion.nvim",
+          url: siteUrl,
+        },
+        {
+          "@type": "SoftwareApplication",
+          name: "CodeCompanion.nvim",
+          description:
+            "AI coding, Vim style. CodeCompanion is a plugin which enables you to code with AI, using LLMs and agents, in Neovim.",
+          applicationCategory: "DeveloperApplication",
+          operatingSystem: "Linux, macOS, Windows",
+          url: siteUrl,
+          downloadUrl: "https://github.com/olimorris/codecompanion.nvim",
+          author: {
+            "@type": "Person",
+            name: "Oli Morris",
+            url: "https://github.com/olimorris",
+          },
+          offers: {
+            "@type": "Offer",
+            price: "0",
+            priceCurrency: "USD",
+          },
+        },
+      ],
     }),
   ],
 ];
diff --git a/doc/agent-client-protocol.md b/doc/agent-client-protocol.md
@@ -1,5 +1,5 @@
 ---
-description: How CodeCompanion implements the Agent Client Protocol (ACP)
+description: "CodeCompanion's Agent Client Protocol (ACP) support — covers session management, tool execution, permissions, and which capabilities are currently implemented."
 ---
 
 # Agent Client Protocol (ACP) Support
diff --git a/doc/architecture.md b/doc/architecture.md
@@ -1,5 +1,5 @@
 ---
-description: Architectural concepts and design principles behind CodeCompanion.
+description: "How CodeCompanion manages LLM context windows, handles token limits, and is architected internally — reference for contributors and advanced users."
 ---
 
 # Architecture
@@ -19,7 +19,7 @@ When a user breaches the context window, the conversation **ends** and it **cann
 > [!NOTE]
 > CodeCompanion enables context management by default
 
-If you're using the `openai_responses` or `anthropic` adapters, then CodeCompanion will use their native server-side compaction capabilities. Please see their respective documentation [here](https://developers.openai.com/api/docs/guides/compaction) and [here](https://platform.claude.com/docs/en/build-with-claude/compaction) for more information.
+If you're using the `openai_responses` or `anthropic` adapters, then CodeCompanion will use their native server-side compaction capabilities. Please see the [OpenAI compaction documentation](https://developers.openai.com/api/docs/guides/compaction) and [Anthropic compaction documentation](https://platform.claude.com/docs/en/build-with-claude/compaction) for more information.
 
 To be updated...
 
diff --git a/doc/configuration/action-palette.md b/doc/configuration/action-palette.md
@@ -1,5 +1,5 @@
 ---
-description: How to configure the action palette in CodeCompanion
+description: "Configure the CodeCompanion Action Palette — your entry point to chat buffers, prompt library prompts, and plugin features in Neovim."
 ---
 
 # Configuring the Action Palette
diff --git a/doc/configuration/adapters-acp.md b/doc/configuration/adapters-acp.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to configure ACP adapters like Claude Code, Gemini CLI and Codex
+description: "Configure Agent Client Protocol (ACP) adapters in CodeCompanion to connect with CLI agents like Claude Code, Codex, Gemini CLI, and OpenCode from Neovim."
 ---
 
 # Configuring ACP Adapters
diff --git a/doc/configuration/adapters-http.md b/doc/configuration/adapters-http.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to configure adapters like OpenAI, Anthropic, Claude Code in CodeCompanion
+description: "Configure CodeCompanion's HTTP adapters to connect Neovim to OpenAI, Anthropic, Copilot, Gemini, and Ollama. Covers API keys, model selection, and proxy settings."
 ---
 
 # Configuring HTTP Adapters
@@ -240,7 +240,7 @@ require("codecompanion").setup({
 :::
 
 > [!NOTE]
-> In this _command_ example, we're using the 1Password CLI to extract the Gemini API Key. You could also use gpg as outlined [here](https://github.com/olimorris/codecompanion.nvim/discussions/601)
+> In this _command_ example, we're using the 1Password CLI to extract the Gemini API Key. You could also [use gpg as outlined in this community discussion](https://github.com/olimorris/codecompanion.nvim/discussions/601)
 
 Supported `env` value types:
 - **Plain environment variable name (string)**: if the value is the name of an environment variable that has already been set (e.g. `"HOME"` or `"GEMINI_API_KEY"`), the plugin will read the value.
@@ -464,4 +464,4 @@ Thanks to the community for building the following adapters:
 - [Venice.ai](https://github.com/olimorris/codecompanion.nvim/discussions/972)
 - [Vertex AI](https://github.com/viespejo/cc-adapter-vertex-ai.nvim)
 
-The section of the discussion forums which is dedicated to user created adapters can be found [here](https://github.com/olimorris/codecompanion.nvim/discussions?discussions_q=is%3Aopen+label%3A%22tip%3A+adapter%22). Use these individual threads as a place to raise issues and ask questions about your specific adapters.
+The section of the discussion forums dedicated to user-created adapters can be found in the [adapter discussions on GitHub](https://github.com/olimorris/codecompanion.nvim/discussions?discussions_q=is%3Aopen+label%3A%22tip%3A+adapter%22). Use these individual threads as a place to raise issues and ask questions about your specific adapters.
diff --git a/doc/configuration/chat-buffer.md b/doc/configuration/chat-buffer.md
@@ -1,5 +1,5 @@
 ---
-description: Configure CodeCompanion's native chat buffer, to enable Vim like coding with AI
+description: "Configure CodeCompanion's chat buffer — keymaps, display options, context management, system prompt, and tool settings for AI-assisted coding in Neovim."
 ---
 
 # Configuring the Chat Buffer
diff --git a/doc/configuration/cli.md b/doc/configuration/cli.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to configure agents via the Command-Line Interface (CLI) in CodeCompanion.nvim
+description: "Configure CLI agents in CodeCompanion — define agents like Claude Code or Codex, set custom commands, configure the terminal provider, and manage input settings."
 ---
 
 # Configuring the Command-Line Interface (CLI)
diff --git a/doc/configuration/extensions.md b/doc/configuration/extensions.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to leverage extensions to expand CodeCompanion's functionality
+description: "Configure CodeCompanion extensions to add custom functionality — can be distributed as Neovim plugins or defined locally in your configuration."
 ---
 
 # Configuring Extensions
diff --git a/doc/configuration/inline.md b/doc/configuration/inline.md
@@ -1,5 +1,5 @@
 ---
-description: Configure the Inline Interaction in CodeCompanion
+description: "Configure CodeCompanion's inline interaction for writing and refactoring code directly into Neovim buffers via LLM prompts, without opening a chat buffer."
 ---
 
 # Configuring the Inline Interaction
diff --git a/doc/configuration/mcp.md b/doc/configuration/mcp.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to configure MCP servers within CodeCompanion.nvim
+description: "Configure Model Context Protocol (MCP) servers in CodeCompanion to connect Neovim to external tools and data sources via an open AI integration standard."
 ---
 
 # Configuring MCP Servers
diff --git a/doc/configuration/others.md b/doc/configuration/others.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to leverage other configuration options such as language, log level, per-project configuration and disabling the sending of code to LLMs.
+description: "Configure miscellaneous CodeCompanion options: response language, log level, per-project config files, and restricting code from being sent to LLMs."
 ---
 
 # Other Configuration Options
diff --git a/doc/configuration/prompt-library.md b/doc/configuration/prompt-library.md
@@ -1,5 +1,5 @@
 ---
-description: The prompt library enables you to use pre-built prompts, in markdown, in CodeCompanion. Learn how to configure it here
+description: "Configure CodeCompanion's prompt library with custom Lua or Markdown prompts, reusable workflows, and slash commands for your AI coding workflow in Neovim."
 ---
 
 # Configuring the Prompt Library
diff --git a/doc/configuration/rules.md b/doc/configuration/rules.md
@@ -1,5 +1,5 @@
 ---
-description: Configure ruiles (such as CLAUDE.md. AGENTS.md or Cursor rules) in CodeCompanion
+description: "Configure rules files in CodeCompanion — including CLAUDE.md, AGENTS.md, and Cursor rules — to provide persistent LLM instructions and project context in Neovim."
 ---
 
 # Configuring Rules
diff --git a/doc/configuration/system-prompt.md b/doc/configuration/system-prompt.md
@@ -1,5 +1,5 @@
 ---
-description: Configure the default system prompt in CodeCompanion
+description: "Customize CodeCompanion's system prompt for chat and inline interactions — replace the default, add dynamic context, or tune language and tone for your LLM."
 ---
 
 # Configuring System Prompts
diff --git a/doc/configuration/upgrading.md b/doc/configuration/upgrading.md
@@ -1,5 +1,5 @@
 ---
-description: Guide to upgrading CodeCompanion between versions such as v17.33.0 to v18.0.0
+description: "Step-by-step guide for upgrading CodeCompanion between major versions, covering breaking changes, configuration migration, and version pinning in Neovim."
 ---
 
 # Upgrading CodeCompanion
diff --git a/doc/extending/adapters.md b/doc/extending/adapters.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to create your own adapters in CodeCompanion
+description: "Build a custom CodeCompanion HTTP adapter to connect Neovim to any LLM. Covers the adapter interface, request handlers, environment variables, and schema."
 ---
 
 # Extending with Adapters
@@ -11,7 +11,7 @@ In CodeCompanion, adapters are interfaces that act as a bridge between the plugi
 
 This guide is intended to serve as a reference for anyone who wishes to contribute an adapter to the plugin or understand the inner workings of existing adapters.
 
-The plugin's in-built adapters can be found [here](https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters).
+The plugin's in-built adapters can be found in the [adapters source directory](https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters).
 
 ## The Interface
 
diff --git a/doc/extending/agentic-workflows.md b/doc/extending/agentic-workflows.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to create your own agentic workflows with CodeCompanion
+description: "Build agentic workflows in CodeCompanion — chain LLM prompts with tool calls to automate multi-step tasks like editing files and running your test suite."
 ---
 
 # Extending with Agentic Workflows
diff --git a/doc/extending/extensions.md b/doc/extending/extensions.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to create your own extensions in CodeCompanion
+description: "Create a CodeCompanion extension to add custom functionality to the plugin — distributable as a Neovim plugin or defined locally in your configuration."
 ---
 
 # Extending with Extensions
diff --git a/doc/extending/parsers.md b/doc/extending/parsers.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to create your parsers for rules in CodeCompanion
+description: "Create custom rules parsers in CodeCompanion to post-process and transform rules file content before it's shared with an LLM."
 ---
 
 # Extending with Rules Parsers
diff --git a/doc/extending/tools.md b/doc/extending/tools.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to create your own tools that can be leveraged by LLMs in CodeCompanion
+description: "Build custom CodeCompanion tools to let LLMs execute functions in Neovim — covers tool structure, OpenAI-compatible schemas, handlers, and agent group integration."
 ---
 
 # Extending with Tools
diff --git a/doc/extending/ui.md b/doc/extending/ui.md
@@ -1,5 +1,5 @@
 ---
-description: Some useful UI tips and tricks you can leverage
+description: "Examples and community recipes for extending CodeCompanion's UI in Neovim — including progress spinners with Fidget.nvim and custom status line integrations."
 ---
 
 # Extending the UI
@@ -9,7 +9,7 @@ Below are some examples of how you can extend CodeCompanion and modify the user
 ## Progress updates with Fidget.nvim by [@jessevdp](https://github.com/jessevdp)
 
 <p align="center">
-<video controls muted src="https://github.com/user-attachments/assets/f1419889-7b62-46f2-ba73-98327a1b378b"></video>
+<video controls muted title="Progress updates with Fidget.nvim" src="https://github.com/user-attachments/assets/f1419889-7b62-46f2-ba73-98327a1b378b"></video>
 </p>
 
 As per the discussion over at [#813](https://github.com/olimorris/codecompanion.nvim/discussions/813).
diff --git a/doc/getting-started.md b/doc/getting-started.md
@@ -1,5 +1,5 @@
 ---
-description: Getting started with CodeCompanion
+description: "Get up and running with CodeCompanion in Neovim — configure your first LLM adapter, open a chat buffer, use the inline interaction, and learn the core commands."
 ---
 
 # Getting Started
@@ -67,9 +67,9 @@ The plugin uses the notion of _interactions_ to describe the many different ways
 ### Chat and Inline
 
 > [!NOTE]
-> The adapters that the plugin supports out of the box can be found
-> [here](https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters). Or, see the user
-> contributed adapters [here](configuration/adapters-http#community-adapters).
+> The adapters that the plugin supports out of the box can be found in the
+> [built-in adapters directory](https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters). Or, see the
+> [community-contributed adapters](configuration/adapters-http#community-adapters).
 >
 > [ACP adapters](/configuration/adapters-acp) are only supported for the chat interaction.
 
@@ -172,7 +172,7 @@ You can add context from your code base by using _Editor Context_ and _Slash Com
 
 **Editor Context**
 
-_Editor Context_, accessed via `#` (by default), contain data about the present state of Neovim. You can find a list of available editor context, [here](/usage/chat-buffer/editor-context). The buffer editor context will automatically link a buffer to the chat buffer, by default, updating the LLM when the buffer changes.
+_Editor Context_, accessed via `#` (by default), contain data about the present state of Neovim. You can find a [list of available editor context](/usage/chat-buffer/editor-context). The buffer editor context will automatically link a buffer to the chat buffer, by default, updating the LLM when the buffer changes.
 
 You can use them in your prompts like:
 
@@ -185,11 +185,11 @@ What does the code in #{buffer} do?`
 > [!IMPORTANT]
 > These have been designed to work with native Neovim completions alongside nvim-cmp and blink.cmp. To open the native completion menu use `<C-_>` in insert mode when in the chat buffer. Note: Slash commands should also work with coc.nvim.
 
-_Slash commands_, accessed via `/` (by default), run commands to insert additional context into the chat buffer. You can find a list of available commands as well as how to use them, [here](/usage/chat-buffer/slash-commands).
+_Slash commands_, accessed via `/` (by default), run commands to insert additional context into the chat buffer. You can find a [list of available slash commands and how to use them](/usage/chat-buffer/slash-commands).
 
 **Tools**
 
-_Tools_, accessed via `@` (by default), allow the LLM to function as an agent and leverage external tools. You can find a list of available tools as well as how to use them, [here](usage/chat-buffer/agents-tools#available-tools).
+_Tools_, accessed via `@` (by default), allow the LLM to function as an agent and leverage external tools. You can find a [list of available tools and how to use them](usage/chat-buffer/agents-tools#available-tools).
 
 You can use them in your prompts like:
 
@@ -200,7 +200,7 @@ Can you use @{grep_search} to find occurrences of "hello world"
 ### CLI
 
 <p align="center">
-  <video controls src="https://github.com/user-attachments/assets/9b4e202d-a939-4daa-8344-74af91f9f366"></video>
+  <video controls title="CLI interaction demo" src="https://github.com/user-attachments/assets/9b4e202d-a939-4daa-8344-74af91f9f366"></video>
 </p>
 
 Running `:CodeCompanionCLI` will open a new CLI interaction. Running `:CodeCompanionCLI <your prompt>` will send the prompt to the last CLI interaction (or create a new one). You can also run `:CodeCompanionCLI Ask` to use a rich prompt input field complete with [editor context](#editor-context). Save with `:w` to send the prompt to the agent, or `:w!` to send and auto-submit it.
@@ -210,7 +210,7 @@ Adding `!` to the command (e.g. `:CodeCompanionCLI! <prompt>`) will auto-submit
 ### Inline
 
 <p align="center">
-  <video controls muted src="https://github.com/user-attachments/assets/11a42705-d9de-4eb5-a9ab-c8a2772fb4d4"></video>
+  <video controls muted title="Inline interaction demo" src="https://github.com/user-attachments/assets/11a42705-d9de-4eb5-a9ab-c8a2772fb4d4"></video>
 </p>
 
 > [!NOTE]
diff --git a/doc/index.md b/doc/index.md
@@ -1,5 +1,5 @@
 ---
-description: CodeCompanion is a plugin which enables you to code with AI, using LLMs and agents, in Neovim
+description: "CodeCompanion.nvim is an AI coding plugin for Neovim. Chat with Claude, GPT-5, and Gemini, run CLI agents like Claude Code and Codex, and edit code inline."
 prev: false
 next:
   text: 'Installation'
@@ -13,7 +13,7 @@ next:
 CodeCompanion is a plugin which enables you to code with AI, using LLMs and agents, in Neovim.
 
 <p>
-<video controls muted src="https://github.com/user-attachments/assets/3cc83544-2690-49b5-8be6-51e671db52ef"></video>
+<video controls muted title="CodeCompanion overview demo" src="https://github.com/user-attachments/assets/3cc83544-2690-49b5-8be6-51e671db52ef"></video>
 </p>
 
 ## Features
diff --git a/doc/installation.md b/doc/installation.md
@@ -1,5 +1,5 @@
 ---
-description: How to install CodeCompanion and it's dependencies
+description: "Install CodeCompanion.nvim with lazy.nvim or packer. Covers dependencies, Neovim 0.11+ requirements, optional integrations like nvim-cmp, and API key setup."
 ---
 
 # Installation
diff --git a/doc/model-context-protocol.md b/doc/model-context-protocol.md
@@ -1,5 +1,5 @@
 ---
-description: How to leverage Model Context Protocol (MCP) servers within CodeCompanion.nvim
+description: "Overview of CodeCompanion's Model Context Protocol (MCP) support — which capabilities are implemented and how MCP tools appear in the chat buffer in Neovim."
 ---
 
 # Model Context Protocol (MCP) Support
diff --git a/doc/usage/action-palette.md b/doc/usage/action-palette.md
@@ -1,5 +1,5 @@
 ---
-description: How to use the action palette in CodeCompanion
+description: "Use CodeCompanion's Action Palette to launch chat buffers, switch between open chats, access the prompt library, and discover plugin features from a single menu."
 ---
 
 # Using the Action Palette
diff --git a/doc/usage/chat-buffer/agents-tools.md b/doc/usage/chat-buffer/agents-tools.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to use agents and tools in CodeCompanion so you can leverage the full potential of your LLM and ACP adapters.
+description: "Use CodeCompanion agent tools to let LLMs edit files, run commands, and search the web in Neovim. Covers tool groups, approval system, and model compatibility."
 ---
 
 # Using Agents and Tools
@@ -20,11 +20,11 @@ In the plugin, tools are simply context and actions that are shared with an LLM.
 
 ## How They Work
 
-Tools make use of an LLM's [function calling](https://platform.openai.com/docs/guides/function-calling) ability. All tools in CodeCompanion follow OpenAI's function calling specification, [here](https://platform.openai.com/docs/guides/function-calling#defining-functions).
+Tools make use of an LLM's [function calling](https://platform.openai.com/docs/guides/function-calling) ability. All tools in CodeCompanion follow [OpenAI's function calling specification for defining functions](https://platform.openai.com/docs/guides/function-calling#defining-functions).
 
 When a tool is added to the chat buffer, the LLM is instructured by the plugin to return a structured JSON schema which has been defined for each tool. The chat buffer parses the LLMs response and detects the tool use before triggering the _tools/init.lua_ file. The tool system triggers off a series of events, which sees tool's added to a queue and sequentially worked with their output being shared back to the LLM via the chat buffer. Depending on the tool, flags may be inserted on the chat buffer for later processing.
 
-An outline of the architecture can be seen [here](/extending/tools#architecture).
+An outline of the [tool system architecture](/extending/tools#architecture) is available in the extending section.
 
 ## Agents / Tool Groups
 
@@ -227,7 +227,7 @@ Use @{grep_search} to find all occurrences of `buf_add_message`?
 > By default, when editing files, this tool requires user approval before it can be executed
 
 <p>
-  <video controls muted src="https://github.com/user-attachments/assets/990bbc99-7b12-4dca-8770-c24b9f3e7838"></video>
+  <video controls muted title="insert_edit_into_file tool demo" src="https://github.com/user-attachments/assets/990bbc99-7b12-4dca-8770-c24b9f3e7838"></video>
 </p>
 
 This tool can edit buffers and files for code changes from an LLM:
diff --git a/doc/usage/chat-buffer/editor-context.md b/doc/usage/chat-buffer/editor-context.md
@@ -1,5 +1,5 @@
 ---
-description: Learn how to add context related to buffers and data in your editor, to the chat buffer
+description: "Share Neovim state with your LLM using CodeCompanion editor context — reference buffers, selections, diagnostics, and more with the #{context} syntax in chat."
 ---
 
 # Using Editor Context
diff --git a/doc/usage/chat-buffer/index.md b/doc/usage/chat-buffer/index.md
diff --git a/doc/usage/chat-buffer/rules.md b/doc/usage/chat-buffer/rules.md
diff --git a/doc/usage/chat-buffer/slash-commands.md b/doc/usage/chat-buffer/slash-commands.md
diff --git a/doc/usage/cli.md b/doc/usage/cli.md
diff --git a/doc/usage/events.md b/doc/usage/events.md
diff --git a/doc/usage/inline.md b/doc/usage/inline.md
diff --git a/doc/usage/introduction.md b/doc/usage/introduction.md
diff --git a/doc/usage/prompt-library.md b/doc/usage/prompt-library.md
diff --git a/doc/usage/ui.md b/doc/usage/ui.md
diff --git a/doc/usage/workflows.md b/doc/usage/workflows.md
