Merge pull request #17 from AltimateAI/docs/switch-to-mkdocs-material

kulvirgit · web-flow · commit c5a5be8a8de7 · 2026-03-02T15:09:08.000-08:00
docs: switch from Jekyll to Material for MkDocs
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -22,17 +22,24 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install mkdocs-material
+        run: pip install mkdocs-material
+
+      - name: Build with MkDocs
+        run: mkdocs build -f docs/mkdocs.yml -d site
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: ./docs
-          destination: ./_site
-
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/site
 
   deploy:
     environment:
diff --git a/docs/Gemfile b/docs/Gemfile
diff --git a/docs/_config.yml b/docs/_config.yml
diff --git a/docs/docs/agent-modes.md b/docs/docs/agent-modes.md
@@ -1,9 +1,3 @@
----
-layout: default
-title: Agent Modes
-nav_order: 3
----
-
 # Agent Modes
 
 altimate-code runs in one of four specialized modes. Each mode has different permissions, tool access, and behavioral guardrails.
diff --git a/docs/docs/assets/images/favicon.png b/docs/docs/assets/images/favicon.png
diff --git a/docs/docs/assets/logo.png b/docs/docs/assets/logo.png
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -1,9 +1,3 @@
----
-layout: default
-title: Getting Started
-nav_order: 2
----
-
 # Getting Started
 
 ## Installation
diff --git a/docs/docs/guides/cost-optimization.md b/docs/docs/guides/cost-optimization.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Cost Optimization Guide
-parent: Guides
-nav_order: 1
----
-
 # Cost Optimization Guide
 
 altimate-code is your cost advocate. Here's how to use it to cut warehouse spend.
diff --git a/docs/docs/guides/index.md b/docs/docs/guides/index.md
@@ -0,0 +1,10 @@
+# Guides
+
+Practical guides for common data engineering workflows.
+
+| Guide | Description |
+|---|---|
+| [Cost Optimization](cost-optimization.md) | Find and fix expensive queries, right-size warehouses |
+| [Migration](migration.md) | Translate SQL across warehouse dialects |
+| [Using with Claude Code](using-with-claude-code.md) | Run altimate-code tools from Claude Code sessions |
+| [Using with Codex](using-with-codex.md) | Use your ChatGPT subscription as the LLM backend |
diff --git a/docs/docs/guides/migration.md b/docs/docs/guides/migration.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Migration Guide
-parent: Guides
-nav_order: 2
----
-
 # Migration Guide
 
 Use migrator mode to translate SQL across warehouse dialects while preserving lineage and correctness.
diff --git a/docs/docs/guides/using-with-claude-code.md b/docs/docs/guides/using-with-claude-code.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Using with Claude Code
-parent: Guides
-nav_order: 3
----
-
 # Using altimate-code with Claude Code
 
 altimate-code can work alongside Claude Code. While Claude Code handles general coding tasks, altimate-code provides specialized data engineering capabilities that Claude Code doesn't have.
diff --git a/docs/docs/guides/using-with-codex.md b/docs/docs/guides/using-with-codex.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Using with Codex
-parent: Guides
-nav_order: 4
----
-
 # Using altimate-code with Codex (ChatGPT Subscription)
 
 If you have a ChatGPT Plus or Pro subscription, you can use Codex as your LLM backend in altimate-code at no additional API cost. Your subscription covers all usage.
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Home
-nav_order: 1
-permalink: /
----
-
 # altimate-code
 
 **The data engineering agent for dbt, SQL, and cloud warehouses.**
@@ -82,5 +75,5 @@ altimate-code is model-agnostic. Use it with:
 
 ---
 
-{: .note }
-altimate-code is your cost advocate. Every tool is designed to minimize unnecessary warehouse spend. Cost prediction runs before every query, anti-patterns that burn credits are flagged automatically, and cheaper alternatives are always suggested.
+!!! note
+    altimate-code is your cost advocate. Every tool is designed to minimize unnecessary warehouse spend. Cost prediction runs before every query, anti-patterns that burn credits are flagged automatically, and cheaper alternatives are always suggested.
diff --git a/docs/docs/tools/dbt-tools.md b/docs/docs/tools/dbt-tools.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: dbt Tools
-parent: Tools
-nav_order: 5
----
-
 # dbt Tools
 
 ## dbt_run
diff --git a/docs/docs/tools/finops-tools.md b/docs/docs/tools/finops-tools.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: FinOps Tools
-parent: Tools
-nav_order: 3
----
-
 # FinOps Tools
 
 Cost optimization and warehouse governance. These tools help you find where money is being wasted and fix it.
diff --git a/docs/docs/tools/index.md b/docs/docs/tools/index.md
@@ -0,0 +1,14 @@
+# Tools Reference
+
+altimate-code has 55+ specialized tools organized by function.
+
+| Category | Tools | Purpose |
+|---|---|---|
+| [SQL Tools](sql-tools.md) | 12 tools | Analysis, optimization, translation, formatting, cost prediction |
+| [Schema Tools](schema-tools.md) | 7 tools | Inspection, search, PII detection, tagging, diffing |
+| [FinOps Tools](finops-tools.md) | 8 tools | Cost analysis, warehouse sizing, unused resources, RBAC |
+| [Lineage Tools](lineage-tools.md) | 1 tool | Column-level lineage tracing with confidence scoring |
+| [dbt Tools](dbt-tools.md) | 2 tools + 6 skills | Run, manifest parsing, test generation, scaffolding |
+| [Warehouse Tools](warehouse-tools.md) | 2 tools | Connection management and testing |
+
+All tools are available in the interactive TUI. The agent automatically selects the right tools based on your request.
diff --git a/docs/docs/tools/lineage-tools.md b/docs/docs/tools/lineage-tools.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Lineage Tools
-parent: Tools
-nav_order: 4
----
-
 # Lineage Tools
 
 ## lineage_check
diff --git a/docs/docs/tools/schema-tools.md b/docs/docs/tools/schema-tools.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Schema Tools
-parent: Tools
-nav_order: 2
----
-
 # Schema Tools
 
 ## schema_inspect
diff --git a/docs/docs/tools/sql-tools.md b/docs/docs/tools/sql-tools.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: SQL Tools
-parent: Tools
-nav_order: 1
----
-
 # SQL Tools
 
 ## sql_execute
diff --git a/docs/docs/tools/warehouse-tools.md b/docs/docs/tools/warehouse-tools.md
@@ -1,10 +1,3 @@
----
-layout: default
-title: Warehouse Tools
-parent: Tools
-nav_order: 6
----
-
 # Warehouse Tools
 
 ## warehouse_list
diff --git a/docs/guides/index.md b/docs/guides/index.md
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -0,0 +1,65 @@
+site_name: altimate-code
+site_description: The data engineering agent for dbt, SQL, and cloud warehouses
+site_url: https://altimateai.github.io/altimate-code
+repo_url: https://github.com/AltimateAI/altimate-code
+repo_name: AltimateAI/altimate-code
+
+copyright: "&copy; 2026 Altimate Inc. All rights reserved."
+
+theme:
+  name: material
+  logo: assets/logo.png
+  favicon: assets/images/favicon.png
+  font:
+    text: Roboto
+    code: Roboto Mono
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: white
+      accent: blue
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: blue
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - tables
+  - attr_list
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Agent Modes: agent-modes.md
+  - Tools:
+      - Overview: tools/index.md
+      - SQL Tools: tools/sql-tools.md
+      - Schema Tools: tools/schema-tools.md
+      - FinOps Tools: tools/finops-tools.md
+      - Lineage Tools: tools/lineage-tools.md
+      - dbt Tools: tools/dbt-tools.md
+      - Warehouse Tools: tools/warehouse-tools.md
+  - Guides:
+      - Overview: guides/index.md
+      - Cost Optimization: guides/cost-optimization.md
+      - Migration: guides/migration.md
+      - Using with Claude Code: guides/using-with-claude-code.md
+      - Using with Codex: guides/using-with-codex.md
diff --git a/docs/tools/index.md b/docs/tools/index.md
