diff --git a/apps/kilocode-docs/AGENTS.md b/apps/kilocode-docs/AGENTS.md index 7afeeeb4570..14174cd8597 100644 --- a/apps/kilocode-docs/AGENTS.md +++ b/apps/kilocode-docs/AGENTS.md @@ -20,91 +20,75 @@ This convention helps identify documentation-only PRs and keeps them organized. This project uses [Markdoc](https://markdoc.dev/) for rendering markdown with custom components. Custom tags allow you to embed React components directly in markdown files. -## Converting from old documentation site - -This site was previously in docusaurus but is now in markdoc. Sometimes the user may ask you to update the images and other tags in a page that was imported. These are the types of updates you'd need to make - ### Images -Images will often look like standard HTML image tags like: +Use the Markdoc image tag format: -Connect account screen +```markdown +{% image src="/docs/img/kilo-provider/connected-accounts.png" alt="Connect account screen" width="800" caption="Connect account screen" /%} +``` -We want to convert them to Markdoc image tags like this: +Note that this site is served under kilo.ai/docs so the `/docs` prefix **must** be present in every image path. -{% image src="/docs/img/kilo-provider/connected-accounts.png" alt="Connect account screen" width="800" caption="Connect account screen" /%} +Image attributes: -Note that this site is served under kilo.ai/docs so the `/docs` MUST be present in every image tag. - -Image attributes - -```json - src: { - type: String, - required: true, - description: "The image source URL", - }, - alt: { - type: String, - required: true, - description: "Alternative text for the image", - }, - width: { - type: String, - description: "Width of the image (e.g., '500px', '80%')", - }, - height: { - type: String, - description: "Height of the image (e.g., '300px', 'auto')", - }, - caption: { - type: String, - description: "Optional caption displayed below the image", - } -``` +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------------------- | +| `src` | String | Yes | The image source URL | +| `alt` | String | Yes | Alternative text for the image | +| `width` | String | No | Width of the image (e.g., '500px', '80%') | +| `height` | String | No | Height of the image (e.g., '300px', 'auto') | +| `caption` | String | No | Caption displayed below the image | ### Callouts -When callouts are used, they should be in markdoc format like this: +Use the Markdoc callout tag format: ```markdown {% callout type="info" %} -You can report any bugs or feedbacks by chatting with us in our [Discord server](https://discord.gg/ovhcloud), in the AI Endpoints channel. +You can report any bugs or feedback by chatting with us in our [Discord server](https://discord.gg/ovhcloud), in the AI Endpoints channel. {% /callout %} ``` -Callout Attributes: - -```json - title: { - type: String, - description: "Optional custom title for the callout", - }, - type: { - type: String, - default: "note", - matches: ["generic", "note", "tip", "info", "warning", "danger"], - description: - "The type of callout: generic (no icon/title), note, tip, info, warning, or danger", - }, - collapsed: { - type: Boolean, - default: false, - description: - "When true, the callout starts collapsed and can be expanded by clicking the header", - } -``` +Callout attributes: -### Codicons +| Attribute | Type | Default | Description | +| ----------- | ------- | ------- | ------------------------------------------------- | +| `title` | String | - | Optional custom title for the callout | +| `type` | String | "note" | One of: generic, note, tip, info, warning, danger | +| `collapsed` | Boolean | false | When true, the callout starts collapsed | -Codicon icons look like this: - -```html - -``` +### Codicons -And we want to convert that to look like this: +Use the Markdoc codicon tag format: ```markdown {% codicon name="gear" /%} ``` + +## Documentation Guidelines + +### Adding New Pages + +1. Create your page in the appropriate directory under `pages/` +2. **Always update navigation**: Add the page to the corresponding navigation file in `lib/nav/` + - Each section has its own nav file (e.g., `getting-started.ts`, `code-with-ai.ts`, `ai-providers.ts`) + - Navigation structure is exported from `lib/nav/index.ts` + - See `lib/types.ts` for the `NavSection` and `NavLink` interfaces + +### Removing or Moving Pages + +**Never remove a page without adding a redirect.** This prevents broken links from search engines, external references, and user bookmarks. + +1. Add a redirect entry to `previous-docs-redirects.js` +2. Redirect format: + ```javascript + { + source: "/docs/old-path", + destination: "/docs/new-path", + basePath: false, + permanent: true, + } + ``` +3. Update the navigation file to remove or update the link +4. Redirects are loaded in `next.config.js` diff --git a/apps/kilocode-docs/lib/nav/getting-started.ts b/apps/kilocode-docs/lib/nav/getting-started.ts index b2cc3aa6793..d7be768df74 100644 --- a/apps/kilocode-docs/lib/nav/getting-started.ts +++ b/apps/kilocode-docs/lib/nav/getting-started.ts @@ -46,6 +46,16 @@ export const GettingStartedNav: NavSection[] = [ href: "/getting-started/migrating", children: "Migrating from Cursor", }, + { + href: "/getting-started/troubleshooting", + children: "Troubleshooting", + subLinks: [ + { + href: "/getting-started/troubleshooting/troubleshooting-extension", + children: "Extension Troubleshooting", + }, + ], + }, ], }, ] diff --git a/apps/kilocode-docs/pages/getting-started/troubleshooting/index.md b/apps/kilocode-docs/pages/getting-started/troubleshooting/index.md new file mode 100644 index 00000000000..2f88f41c9a8 --- /dev/null +++ b/apps/kilocode-docs/pages/getting-started/troubleshooting/index.md @@ -0,0 +1,12 @@ +--- +title: "Troubleshooting" +description: "Guides for diagnosing and resolving issues with Kilo Code" +--- + +# Troubleshooting + +This section contains guides for diagnosing and resolving common issues with Kilo Code. + +## Guides + +- [**Extension Troubleshooting**](/docs/getting-started/troubleshooting/troubleshooting-extension) - How to capture console logs and report issues with the Kilo Code extension diff --git a/apps/kilocode-docs/pages/getting-started/troubleshooting/troubleshooting-extension.md b/apps/kilocode-docs/pages/getting-started/troubleshooting/troubleshooting-extension.md new file mode 100644 index 00000000000..a92a28e7af3 --- /dev/null +++ b/apps/kilocode-docs/pages/getting-started/troubleshooting/troubleshooting-extension.md @@ -0,0 +1,57 @@ +--- +title: "Troubleshooting IDE Extensions" +description: "How to capture console logs and report issues with Kilo Code" +--- + +# Capturing Console Logs + +Providing console logs helps us pinpoint exactly what's going wrong with your installation, network, or MCP setup. This guide walks you through capturing those logs in your IDE. + +## Opening Developer Tools + +{% tabs %} +{% tab label="VS Code" %} + +1. **Open the Command Palette**: Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac) +2. **Search for Developer Tools**: Type `Developer: Open Webview Developer Tools` and select it + +{% /tab %} +{% tab label="JetBrains" %} + +### Enable JCEF Debugging + +1. Open your JetBrains IDE and go to **Help → Find Action** (or press `Cmd+Shift+A` / `Ctrl+Shift+A`) +2. Type `Registry` and open it +3. Search for `jcef` and configure these settings: + - `ide.browser.jcef.debug.port` → set to `9222` + - `ide.browser.jcef.contextMenu.devTools.enabled` → check the box +4. Restart your IDE after making these changes + +### Connect Chrome DevTools + +1. Make sure the **Kilo Code panel is open** in your IDE (the debug target won't appear unless the webview is active) +2. Open Chrome (or any Chromium-based browser like Edge or Arc) +3. Navigate to `http://localhost:9222/json` to see the list of inspectable targets +4. Find the entry with `"title": "Kilo Code"` and open the `devtoolsFrontendUrl` link +5. Chrome DevTools will open connected to the Kilo webview—click the **Console** tab + +{% /tab %} +{% /tabs %} + +## Capturing the Error + +Once you have the Developer Tools console open: + +1. **Clear previous logs**: Click the "Clear Console" button (🚫 icon at the top of the Console panel) to remove old messages +2. **Reproduce the issue**: Perform the action that was causing problems +3. **Check for errors**: Look at the Console tab for error messages (usually shown in red). If you suspect connection issues, also check the **Network** tab +4. **Copy the logs**: Right-click in the console and select "Save as..." or copy the relevant error messages + +## Contact Support + +If you're unable to resolve the issue, please inspect the console logs, remove any secrets, and send the logs to **[hi@kilocode.ai](mailto:hi@kilocode.ai)** along with the following: + +- The error messages from the console +- Steps to reproduce the issue +- Screenshots or screen recordings of the issue +- Your IDE and Kilo Code version