Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

docs: serve the docs site at docs.ix-infra.com/oss

KageBinaryc9178ea6b164
diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs
index be37790f..57e027f9 100644
--- a/docs-site/astro.config.mjs
+++ b/docs-site/astro.config.mjs
@@ -1,13 +1,25 @@
// Copyright 2026 Ix Infrastructure Inc.
+import { satteri } from '@astrojs/markdown-satteri'
import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightOpenAPI, { createOpenAPISidebarGroup } from 'starlight-openapi'
+import { baseLinksPlugin } from './scripts/base-links-plugin.mjs'
+import { DOCS_BASE } from './site-base.mjs'
+
const apiSidebarGroup = createOpenAPISidebarGroup()
export default defineConfig({
site: 'https://docs.ix-infra.com',
+ // Served at docs.ix-infra.com/oss/, with the Kartr docs to sit beside it.
+ // Astro does not nest the output under the base, so it is built into
+ // dist/oss/ and dist/ stays the root of the domain (scripts/finalize-dist.mjs).
+ base: DOCS_BASE,
+ outDir: `./dist${DOCS_BASE}`,
+ markdown: {
+ processor: satteri({ mdastPlugins: [baseLinksPlugin(DOCS_BASE)] }),
+ },
integrations: [
starlight({
title: 'Ix Docs',
@@ -19,7 +31,7 @@ export default defineConfig({
},
favicon: '/favicon.png',
head: [
- { tag: 'meta', attrs: { property: 'og:image', content: 'https://docs.ix-infra.com/og-image.png' } },
+ { tag: 'meta', attrs: { property: 'og:image', content: `https://docs.ix-infra.com${DOCS_BASE}/og-image.png` } },
],
social: [
{ icon: 'github', label: 'GitHub', href: 'https://github.com/ix-infrastructure/Ix' },
diff --git a/docs-site/package-lock.json b/docs-site/package-lock.json
index 7acd5b37..14b12342 100644
--- a/docs-site/package-lock.json
+++ b/docs-site/package-lock.json
@@ -8,9 +8,11 @@
"name": "ix-docs-site",
"version": "0.1.0",
"dependencies": {
+ "@astrojs/markdown-satteri": "^0.4.2",
"@astrojs/starlight": "^0.42.4",
"@fontsource-variable/inter": "^5.3.0",
"astro": "^7.3.5",
+ "satteri": "^0.10.5",
"sharp": "^0.35.4",
"starlight-openapi": "^0.26.2"
},
diff --git a/docs-site/package.json b/docs-site/package.json
index 96746e5e..f5e2c579 100644
--- a/docs-site/package.json
+++ b/docs-site/package.json
@@ -3,22 +3,24 @@
"version": "0.1.0",
"private": true,
"type": "module",
- "description": "Source for docs.ix-infra.com, the Ix documentation site",
+ "description": "Source for docs.ix-infra.com/oss, the Ix open-source documentation",
"scripts": {
"sync": "node scripts/sync-reference.mjs",
"predev": "npm run sync",
"dev": "astro dev",
"prebuild": "npm run sync",
- "build": "astro build",
+ "build": "astro build && node scripts/finalize-dist.mjs",
"preview": "astro preview"
},
"engines": {
"node": ">=22.12.0"
},
"dependencies": {
+ "@astrojs/markdown-satteri": "^0.4.2",
"@astrojs/starlight": "^0.42.4",
"@fontsource-variable/inter": "^5.3.0",
"astro": "^7.3.5",
+ "satteri": "^0.10.5",
"sharp": "^0.35.4",
"starlight-openapi": "^0.26.2"
},
diff --git a/docs-site/scripts/base-links-plugin.mjs b/docs-site/scripts/base-links-plugin.mjs
new file mode 100644
index 00000000..e47b51bd
--- /dev/null
+++ b/docs-site/scripts/base-links-plugin.mjs
@@ -0,0 +1,43 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+// A Sätteri mdast plugin that prefixes root-relative links in the docs with the
+// site's base path.
+//
+// The site is served under a base (/oss/ on docs.ix-infra.com). Astro puts that
+// base on the URLs it generates — the sidebar, assets, the favicon — but not on
+// links written inside a page. Pages keep writing /reference/commands/, and this
+// turns it into /oss/reference/commands/, so the content does not have to know
+// where the site is mounted. It covers Markdown links and definitions, and
+// href/src in raw HTML.
+//
+// Two things it cannot reach, which use page-relative links instead: front
+// matter (the home page's hero), which is not Markdown, and attributes on MDX
+// components such as LinkCard, which Sätteri does not let a plugin rewrite.
+
+import { defineMdastPlugin } from 'satteri'
+
+const ROOT_RELATIVE = /^\/(?!\/)/
+
+export function withBase(url, base) {
+ if (!base || !ROOT_RELATIVE.test(url) || url === base || url.startsWith(`${base}/`)) return url
+ return base + url
+}
+
+export function baseLinksPlugin(base) {
+ const prefix = base.replace(/\/+$/, '')
+
+ const url = (node, ctx) => {
+ const next = withBase(node.url, prefix)
+ if (next !== node.url) ctx.setProperty(node, 'url', next)
+ }
+
+ return defineMdastPlugin({
+ name: 'ix-docs-base-links',
+ link: url,
+ definition: url,
+ html(node, ctx) {
+ const next = node.value.replace(/\b(href|src)="(\/[^"]*)"/g, (_, attr, link) => `${attr}="${withBase(link, prefix)}"`)
+ if (next !== node.value) ctx.setProperty(node, 'value', next)
+ },
+ })
+}
diff --git a/docs-site/scripts/finalize-dist.mjs b/docs-site/scripts/finalize-dist.mjs
new file mode 100644
index 00000000..ea5cd571
--- /dev/null
+++ b/docs-site/scripts/finalize-dist.mjs
@@ -0,0 +1,21 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+// Writes the files that live at the root of the deployed site, above the docs.
+//
+// docs.ix-infra.com is meant to hold more than one set of docs — /oss/ now,
+// /kartr/ later — so this site builds into dist/oss/ and dist/ is the root of
+// the domain. Until there is a page at the root to choose between them, `/`
+// redirects to /oss/. It is a 302 so no browser caches it past the day a
+// chooser replaces it. The docs' 404 page is copied to the root too, so a
+// mistyped URL outside /oss/ still lands on a page with a way back.
+
+import { copyFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { DOCS_BASE } from '../site-base.mjs'
+
+const dist = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist')
+
+await writeFile(join(dist, '_redirects'), `/ ${DOCS_BASE}/ 302\n`)
+await copyFile(join(dist, DOCS_BASE, '404.html'), join(dist, '404.html'))
diff --git a/docs-site/site-base.mjs b/docs-site/site-base.mjs
new file mode 100644
index 00000000..dcafc158
--- /dev/null
+++ b/docs-site/site-base.mjs
@@ -0,0 +1,5 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+// Where these docs are mounted on docs.ix-infra.com. The Kartr docs are meant
+// to sit beside them at /kartr/; see scripts/finalize-dist.mjs for the root.
+export const DOCS_BASE = '/oss'
diff --git a/docs-site/src/content/docs/index.mdx b/docs-site/src/content/docs/index.mdx
index 6ea511a8..be3fe7ed 100644
--- a/docs-site/src/content/docs/index.mdx
+++ b/docs-site/src/content/docs/index.mdx
@@ -6,11 +6,11 @@ hero:
title: |
Understand any codebase <span class="accent">instantly.</span>
image:
- html: '<img class="hero-demo" src="/demo.gif" width="960" height="540" alt="Ix mapping a repository and answering explain, trace and impact queries in a terminal" />'
+ html: '<img class="hero-demo" src="demo.gif" width="960" height="540" alt="Ix mapping a repository and answering explain, trace and impact queries in a terminal" />'
tagline: Ix maps your repository into a persistent graph of symbols, calls and imports. You and your coding agents query that graph instead of grepping and guessing.
actions:
- text: Get started
- link: /getting-started/quickstart/
+ link: getting-started/quickstart/
icon: right-arrow
variant: primary
- text: View on GitHub
@@ -61,10 +61,10 @@ ix impact verify_token # what breaks if I change this?
## Where to go next
<CardGrid>
- <LinkCard title="Quickstart" description="Install Ix, map a repo and run your first queries." href="/getting-started/quickstart/" />
- <LinkCard title="Connect your AI agent" description="Register Ix's MCP server with the clients you use." href="/integrations/overview/" />
- <LinkCard title="Command reference" description="Every ix command, grouped by the question it answers." href="/reference/commands/" />
- <LinkCard title="HTTP API" description="The local backend's endpoints, generated from the OpenAPI spec." href="/api/overview/" />
+ <LinkCard title="Quickstart" description="Install Ix, map a repo and run your first queries." href="getting-started/quickstart/" />
+ <LinkCard title="Connect your AI agent" description="Register Ix's MCP server with the clients you use." href="integrations/overview/" />
+ <LinkCard title="Command reference" description="Every ix command, grouped by the question it answers." href="reference/commands/" />
+ <LinkCard title="HTTP API" description="The local backend's endpoints, generated from the OpenAPI spec." href="api/overview/" />
</CardGrid>
Ix is open source under the Apache 2.0 license. Questions? Join us on [Discord](https://discord.gg/ncEYVHVqZ8).
diff --git a/docs-site/src/content/docs/integrations/overview.mdx b/docs-site/src/content/docs/integrations/overview.mdx
index dea09557..cc8cb87b 100644
--- a/docs-site/src/content/docs/integrations/overview.mdx
+++ b/docs-site/src/content/docs/integrations/overview.mdx
@@ -24,7 +24,7 @@ This detects the AI clients on your machine (**Claude Code, Codex, Cursor, VS Co
opencode**) and registers Ix's MCP server with each one. Then ask your agent a question about your codebase.
<CardGrid>
- <LinkCard title="MCP server" description="Tools, registration and repair." href="/integrations/mcp/" />
- <LinkCard title="Agent skill" description="Teach any agent to drive the CLI." href="/integrations/agent-skill/" />
- <LinkCard title="Native plugins" description="Claude Code, Codex, Cursor, Gemini, OpenCode and OpenClaw." href="/integrations/plugins/" />
+ <LinkCard title="MCP server" description="Tools, registration and repair." href="../mcp/" />
+ <LinkCard title="Agent skill" description="Teach any agent to drive the CLI." href="../agent-skill/" />
+ <LinkCard title="Native plugins" description="Claude Code, Codex, Cursor, Gemini, OpenCode and OpenClaw." href="../plugins/" />
</CardGrid>