Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

chore(docs): one documentation site, not two (#2784)

Tejas Chopra3c10e8ff00f8
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index e22833c03..0fd773191 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,26 +1,27 @@
-name: Deploy Documentation
+name: Validate Docs
+
+# There is ONE documentation site: the Next.js/Fumadocs app in `docs/`, published
+# at https://headroom-docs.vercel.app by Vercel's own Git integration. That URL is
+# what README and `pyproject.toml` (Homepage, Documentation) point at.
+#
+# This workflow therefore only *validates* — it deploys nothing. Vercel owns
+# deployment; duplicating it here is what produced a `deploy-vercel` job that
+# failed 30 times on main without ever deploying (no VERCEL_* secrets were set).
+#
+# A second site used to be built from `wiki/` by MkDocs and published to GitHub
+# Pages off the `gh-pages` branch. It was linked from nowhere in the repo, it meant
+# every documented change had to be written twice, and each Pages deploy
+# force-pushed `gh-pages` — which Vercel then tried to build, failing with
+# "The specified Root Directory 'docs' does not exist" because that branch holds
+# only the rendered site. Removed. `wiki/` stays in the repo as unpublished
+# markdown pending migration of the pages `docs/` does not yet cover (notably
+# `wiki/cli.md`); nothing builds or publishes it, so it needs no syncing.
on:
pull_request:
branches: [main]
paths:
- 'docs/**'
- - 'wiki/**'
- - 'mkdocs.yml'
- - '.github/workflows/docs.yml'
- # Push only deploys GitHub Pages, and `mkdocs.yml` sets `docs_dir: wiki` — so the
- # sources that matter here are wiki/ and mkdocs.yml, NOT docs/ (that is the
- # Next.js site, which Vercel deploys through its own Git integration).
- #
- # wiki/** was missing, so a merge touching only wiki/ never triggered this
- # workflow and the published Pages site silently went stale. docs/** was present
- # but mkdocs never reads it, so it only bought a no-op Pages rebuild.
- push:
- branches:
- - main
- paths:
- - 'wiki/**'
- - 'mkdocs.yml'
- '.github/workflows/docs.yml'
workflow_dispatch:
@@ -28,35 +29,8 @@ permissions:
contents: read
jobs:
- validate-mkdocs:
- name: Validate mkdocs build
- if: github.event_name == 'pull_request'
- runs-on: ubuntu-latest
- timeout-minutes: 10
- steps:
- - uses: actions/checkout@v7
-
- - name: Set up Python
- uses: actions/setup-python@v6
- with:
- python-version: '3.11'
-
- - name: Cache pip
- uses: actions/cache@v6
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip-docs-${{ hashFiles('mkdocs.yml') }}
- restore-keys: ${{ runner.os }}-pip-docs-
-
- - name: Install dependencies
- run: pip install mkdocs-material
-
- - name: Build docs
- run: mkdocs build
-
validate-nextjs:
name: Validate Next.js build
- if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
@@ -76,43 +50,3 @@ jobs:
- name: Build docs
run: npm run build
working-directory: docs
-
- deploy-github-pages:
- name: Deploy GitHub Pages
- if: github.event_name != 'pull_request'
- runs-on: ubuntu-latest
- permissions:
- contents: write
- steps:
- - uses: actions/checkout@v7
- with:
- fetch-depth: 0
-
- - name: Set up Python
- uses: actions/setup-python@v6
- with:
- python-version: '3.11'
-
- - name: Cache pip
- uses: actions/cache@v6
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip-docs-${{ hashFiles('mkdocs.yml') }}
- restore-keys: ${{ runner.os }}-pip-docs-
-
- - name: Install dependencies
- run: pip install mkdocs-material
-
- - name: Build and deploy
- run: mkdocs gh-deploy --force
-
-# The Next.js docs site is deployed by Vercel's own Git integration, so there is no
-# deploy job for it here. A `deploy-vercel` job used to run `npx vercel deploy
-# --prod` on every push to main, but VERCEL_TOKEN / VERCEL_ORG_ID /
-# VERCEL_PROJECT_ID are not configured as secrets (repo or org), so it invoked the
-# CLI with an empty `--token=` and exited 1. It therefore never deployed anything:
-# 30 failed runs on main between 2026-07-14 and 2026-08-04. `deploy-github-pages`
-# succeeded in those same runs — only this job failed — so the red was pure noise.
-#
-# `Validate Next.js build` above still guards docs/** on pull requests, so a broken
-# MDX change is caught before merge.
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdx
index c4bf1bc8f..40ee56530 100644
--- a/docs/content/docs/configuration.mdx
+++ b/docs/content/docs/configuration.mdx
@@ -399,7 +399,7 @@ precedence rules: explicit argument > per-resource env var > derived
from canonical root > default. Every legacy env var continues to work
unchanged.
-See the **[Filesystem Contract](https://github.com/headroomlabs-ai/headroom/blob/main/wiki/filesystem-contract.md)**
+See the **[Filesystem Contract](/docs/filesystem-contract)**
page for the full bucket table, plugin-author guidance, and the Docker
naming overlap note (`HEADROOM_WORKSPACE` is *not* the same as
`HEADROOM_WORKSPACE_DIR`).
diff --git a/mkdocs.yml b/mkdocs.yml
deleted file mode 100644
index 5d41f8b3c..000000000
--- a/mkdocs.yml
+++ /dev/null
@@ -1,136 +0,0 @@
-site_name: Headroom
-docs_dir: wiki
-site_description: "The Context Optimization Layer for LLM Applications — compress everything your AI agent reads."
-site_url: https://chopratejas.github.io/headroom
-repo_url: https://github.com/chopratejas/headroom
-repo_name: chopratejas/headroom
-edit_uri: edit/main/docs/
-
-theme:
- name: material
- custom_dir: docs/overrides
- palette:
- - media: "(prefers-color-scheme: light)"
- scheme: default
- primary: deep purple
- accent: amber
- toggle:
- icon: material/brightness-7
- name: Switch to dark mode
- - media: "(prefers-color-scheme: dark)"
- scheme: slate
- primary: deep purple
- accent: amber
- toggle:
- icon: material/brightness-4
- name: Switch to light mode
- font:
- text: Inter
- code: JetBrains Mono
- features:
- - content.code.copy
- - content.code.annotate
- - content.tabs.link
- - navigation.instant
- - navigation.instant.progress
- - navigation.tabs
- - navigation.tabs.sticky
- - navigation.sections
- - navigation.expand
- - navigation.top
- - navigation.indexes
- - search.highlight
- - search.suggest
- - search.share
- - toc.follow
- - header.autohide
- icon:
- repo: fontawesome/brands/github
- logo: material/layers-outline
-
-plugins:
- - search
-
-extra_css:
- - stylesheets/extra.css
-
-markdown_extensions:
- - admonition
- - attr_list
- - def_list
- - md_in_html
- - tables
- - toc:
- permalink: true
- - pymdownx.highlight:
- anchor_linenums: true
- line_spans: __span
- pygments_lang_class: true
- - pymdownx.inlinehilite
- - pymdownx.snippets
- - pymdownx.superfences:
- custom_fences:
- - name: mermaid
- class: mermaid
- format: !!python/name:pymdownx.superfences.fence_code_format
- - pymdownx.tabbed:
- alternate_style: true
- - pymdownx.details
- - pymdownx.emoji:
- emoji_index: !!python/name:material.extensions.emoji.twemoji
- emoji_generator: !!python/name:material.extensions.emoji.to_svg
- - pymdownx.tasklist:
- custom_checkbox: true
-
-nav:
- - Home: index.md
- - Getting Started:
- - Quickstart: quickstart.md
- - Installation: getting-started.md
- - Docker-Native Install: docker-install.md
- - Persistent Installs: persistent-installs.md
- - Configuration: configuration.md
- - User Guide:
- - Proxy Server: proxy.md
- - Compression Pipeline: compression.md
- - CCR (Lossless Retrieval): ccr.md
- - Image Compression: image-compression.md
- - Memory System: memory.md
- - Shared Context: shared-context.md
- - Failure Learning: learn.md
- - Integrations:
- - Overview: integration-guide.md
- - Vertex AI: vertex.md
- - LangChain: langchain.md
- - Agno: agno.md
- - Strands: strands.md
- - MCP Tools: mcp.md
- - How It Works:
- - Architecture: ARCHITECTURE.md
- - Transforms Pipeline: transforms.md
- - Text Compression: text-compression.md
- - LLMLingua: llmlingua.md
- - Benchmarks:
- - Accuracy: benchmarks.md
- - Latency: LATENCY_BENCHMARKS.md
- - Limitations: LIMITATIONS.md
- - Reference:
- - CLI: cli.md
- - API: api.md
- - SDK: sdk.md
- - Differential Network Capture: network-diff-capture.md
- - Metrics & Observability: metrics.md
- - Error Codes: errors.md
- - Troubleshooting: troubleshooting.md
- - Deployment:
- - macOS LaunchAgent: macos-deployment.md
-
-extra:
- social:
- - icon: fontawesome/brands/github
- link: https://github.com/chopratejas/headroom
- - icon: fontawesome/brands/python
- link: https://pypi.org/project/headroom-ai/
- - icon: fontawesome/brands/discord
- link: https://discord.gg/yRmaUNpsPJ
- generator: false