docs: sync from help-docs (source of truth) - #1083
Conversation
📝 WalkthroughWalkthroughThe documentation site now has page metadata across major sections, revised branding and internal links, expanded landing content, and updated MkDocs navigation. YAML examples use quoted descriptions where needed. ChangesDocumentation refresh
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
This PR doesn't fully meet our contributing guidelines and PR template. What needs to be fixed:
Please edit this PR description to address the above within 2 hours, or it will be automatically closed. If you believe this was flagged incorrectly, please let a maintainer know. |
d1dec56 to
c824ebc
Compare
c824ebc to
b18bbf3
Compare
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Claude Code Review
This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.
Tip: disable this comment in your organization's Code Review settings.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/docs/data-engineering/tools/dbt-tools.md`:
- Around line 91-92: Update the generated Description value in the documented
dbt output to remain on a single line, keeping the closing quote on the same
line; only represent a newline with an explicit escape if that is the tool’s
actual output.
In `@docs/docs/index.md`:
- Line 28: Change the six documentation card headings, including “Quickstart”
and the headings at the referenced locations, from level-three (`###`) to
level-two (`##`) headings while preserving their existing text and links.
In `@docs/mkdocs.yml`:
- Around line 69-191: Update the Altimate MCP navigation section in the mkdocs
nav configuration so every datamates/... target points to an existing
documentation file under docs/docs/datamates, adding the missing target files as
needed, or remove entries whose pages do not exist. Ensure no broken datamates
navigation links remain.
- Line 4: Update docs/docs/llms.txt entries to remove the outdated /code/ prefix
so every link matches the root-relative routing established by site_url in
docs/mkdocs.yml and docs/docs/index.md. Modify docs/docs/llms.txt lines 4-42;
docs/mkdocs.yml lines 4-4 and docs/docs/index.md lines 16-16 require no direct
changes and serve as routing references.
- Around line 66-68: Restore valid callable Material emoji settings under
pymdownx.emoji by replacing the null emoji_index and emoji_generator values with
the original Material extensions or equivalent !!python/name callables. Ensure
Material emoji shortcodes render successfully during MkDocs builds.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 18bb33a8-8d51-4469-8ec8-9ccd300edd56
📒 Files selected for processing (75)
docs/docs/configure/acp.mddocs/docs/configure/agents.mddocs/docs/configure/bedrock-custom-endpoints.mddocs/docs/configure/commands.mddocs/docs/configure/config.mddocs/docs/configure/context-management.mddocs/docs/configure/custom-tools.mddocs/docs/configure/formatters.mddocs/docs/configure/governance.mddocs/docs/configure/index.mddocs/docs/configure/keybinds.mddocs/docs/configure/lsp.mddocs/docs/configure/mcp-servers.mddocs/docs/configure/models.mddocs/docs/configure/permissions.mddocs/docs/configure/providers.mddocs/docs/configure/rules.mddocs/docs/configure/skills.mddocs/docs/configure/themes.mddocs/docs/configure/tools.mddocs/docs/configure/tools/config.mddocs/docs/configure/tools/core-tools.mddocs/docs/configure/tools/custom.mddocs/docs/configure/tools/index.mddocs/docs/configure/trace.mddocs/docs/configure/warehouses.mddocs/docs/data-engineering/agent-modes.mddocs/docs/data-engineering/guides/clickhouse.mddocs/docs/data-engineering/guides/cost-optimization.mddocs/docs/data-engineering/guides/data-parity.mddocs/docs/data-engineering/guides/index.mddocs/docs/data-engineering/guides/migration.mddocs/docs/data-engineering/guides/using-with-claude-code.mddocs/docs/data-engineering/guides/using-with-codex.mddocs/docs/data-engineering/tools/dbt-tools.mddocs/docs/data-engineering/tools/finops-tools.mddocs/docs/data-engineering/tools/index.mddocs/docs/data-engineering/tools/lineage-tools.mddocs/docs/data-engineering/tools/memory-tools.mddocs/docs/data-engineering/tools/schema-tools.mddocs/docs/data-engineering/tools/sql-tools.mddocs/docs/data-engineering/tools/warehouse-tools.mddocs/docs/data-engineering/training/index.mddocs/docs/data-engineering/training/team-deployment.mddocs/docs/data-engineering/validators.mddocs/docs/develop/ecosystem.mddocs/docs/develop/plugins.mddocs/docs/develop/sdk.mddocs/docs/develop/server.mddocs/docs/drivers.mddocs/docs/examples/index.mddocs/docs/getting-started.mddocs/docs/getting-started/index.mddocs/docs/getting-started/quickstart-new.mddocs/docs/getting-started/quickstart.mddocs/docs/index.mddocs/docs/llms.txtdocs/docs/quickstart.mddocs/docs/reference/changelog.mddocs/docs/reference/network.mddocs/docs/reference/security-faq.mddocs/docs/reference/telemetry.mddocs/docs/reference/troubleshooting.mddocs/docs/reference/windows-wsl.mddocs/docs/usage/check.mddocs/docs/usage/ci-headless.mddocs/docs/usage/cli.mddocs/docs/usage/dbt-pr-review-corpus.mddocs/docs/usage/dbt-pr-review.mddocs/docs/usage/github.mddocs/docs/usage/gitlab.mddocs/docs/usage/ide.mddocs/docs/usage/tui.mddocs/docs/usage/web.mddocs/mkdocs.yml
| <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 3 14h7l-1 8 10-12h-7l1-8z"/></svg> | ||
| </div> | ||
|
|
||
| ### [Quickstart](/getting-started/) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use level-two headings for the documentation cards.
Each card heading follows the page level-one heading. Level-three headings skip level two and create an invalid heading outline. Change all six card headings from ### to ##.
Proposed fix
-### [Quickstart](/getting-started/)
+## [Quickstart](/getting-started/)
-### [Tools](/configure/tools/)
+## [Tools](/configure/tools/)
-### [Interfaces](/usage/tui/)
+## [Interfaces](/usage/tui/)
-### [Configure](/configure/)
+## [Configure](/configure/)
-### [Governance](/configure/governance/)
+## [Governance](/configure/governance/)
-### [Develop & Extend](/develop/sdk/)
+## [Develop & Extend](/develop/sdk/)Also applies to: 41-41, 54-54, 67-67, 80-80, 93-93
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 28-28: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/index.md` at line 28, Change the six documentation card headings,
including “Quickstart” and the headings at the referenced locations, from
level-three (`###`) to level-two (`##`) headings while preserving their existing
text and links.
Source: Linters/SAST tools
| site_description: The open-source data engineering harness. 100+ tools for building, validating, optimizing, and shipping data products. | ||
| site_description: The open-source data engineering harness. 100+ tools for building, | ||
| validating, optimizing, and shipping data products. | ||
| site_url: https://docs.altimate.sh |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
origin="${DOCS_ORIGIN:-https://docs.altimate.sh}"
for path in /quickstart/ /code/quickstart/; do
printf '%s%s -> ' "$origin" "$path"
curl -sS -o /dev/null -w '%{http_code}\n' -L "$origin$path"
doneRepository: AltimateAI/altimate-code
Length of output: 255
Remove the outdated /code/ route set.
docs/mkdocs.yml#L4-L4 and docs/docs/index.md#L16-L16 use root-relative docs.altimate.sh paths. docs/docs/llms.txt still points every link under /code/, which does not resolve at the deployed docs origin. Update docs/docs/llms.txt to remove the /code/ prefix or regenerate it from the canonical routing policy.
📍 Affects 3 files
docs/mkdocs.yml#L4-L4(this comment)docs/docs/index.md#L16-L16docs/docs/llms.txt#L4-L42
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/mkdocs.yml` at line 4, Update docs/docs/llms.txt entries to remove the
outdated /code/ prefix so every link matches the root-relative routing
established by site_url in docs/mkdocs.yml and docs/docs/index.md. Modify
docs/docs/llms.txt lines 4-42; docs/mkdocs.yml lines 4-4 and docs/docs/index.md
lines 16-16 require no direct changes and serve as routing references.
| - pymdownx.emoji: | ||
| emoji_index: null | ||
| emoji_generator: null |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Configured Markdown extension:"
sed -n '57,68p' docs/mkdocs.yml
echo "Potential emoji shortcodes:"
rg -n ':[A-Za-z0-9_+-]+:' docs/docs || true
echo "Installed MkDocs and PyMdown dependency declarations:"
fd -HI '^(requirements.*\.(txt|in)|pyproject\.toml|poetry\.lock|uv\.lock)$' . \
-x rg -n 'mkdocs|pymdown|material' {}Repository: AltimateAI/altimate-code
Length of output: 4332
🌐 Web query:
pymdownx.emoji emoji_index null emoji_generator null MkDocs extension documentation
💡 Result:
In the context of the PyMdown Extensions Emoji extension used with MkDocs, emoji_index and emoji_generator are configuration parameters that define how emojis are retrieved and rendered [1][2]. Because MkDocs uses YAML for configuration, these parameters cannot be set with simple string names; they must be provided as Python object references using the!!python/name: prefix [1][3]. Parameter Overview: 1. emoji_index: This parameter specifies the function that provides the mapping (index) between shortcodes (e.g.,:smile:) and emoji data [1][2]. The extension comes with default indexes like emojione, gemoji, and twemoji [1][4]. 2. emoji_generator: This parameter specifies the function that converts the emoji data into the final output format (e.g., an HTML image tag or Unicode character) [1][2]. Configuration in MkDocs: To configure these in your mkdocs.yml file, you use the!!python/name: prefix to point to the specific Python function [1][5]. For example, when using the Material for MkDocs theme, the configuration is typically set as follows [6][5]: markdown_extensions: - pymdownx.emoji: emoji_index:!!python/name:material.extensions.emoji.twemoji emoji_generator:!!python/name:material.extensions.emoji.to_svg In this example,!!python/name: tells the YAML parser to import the specified Python function rather than treating it as a literal string [1][7]. You can substitute these references with custom modules or other built-in options provided by the PyMdown Extensions package (e.g.,!!python/name:pymdownx.emoji.to_png) depending on your requirements [1][3].
Citations:
- 1: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
- 2: https://github.com/wohugb/pymdown-extensions/blob/master/docs/src/markdown/extensions/emoji.md
- 3: https://facelessuser.github.io/pymdown-extensions/faq/
- 4: https://wohugb.github.io/pymdown-extensions/extensions/emoji/
- 5: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
- 6: https://github.com/squidfunk/mkdocs-material/blob/4c0004e1/docs/reference/icons-emojis.md
- 7: Adding custom icons in custom theme extending Material for MkDocs squidfunk/mkdocs-material#7371
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
try:
import pymdownx.emoji
import inspect
settings = getattr(pymdownx.emoji, 'DEFAULT_SETTINGS', None)
print('pymdownx.emoji available')
print('DEFAULT_SETTINGS:', settings)
for name in ('emoji_index', 'emoji_generator'):
if settings:
print(name, 'default type:', type(settings.get(name)).__name__, 'default:', repr(settings.get(name)))
except Exception as e:
print('pymdownx.emoji unavailable:', repr(e))
try:
import pymdownx.emoji
ext = pymdownx.emoji.EmojiExtension()
config = {'emoji_index': None, 'emoji_generator': None}
ret = ext.on_config(config) or config
print('on_config returns', type(ret).__name__ if ret is not None else None)
print('emoji_index after config:', type(ret.get('emoji_index')).__name__ if 'emoji_index' in ret else 'absent', repr(ret.get('emoji_index')))
print('emoji_generator after config:', type(ret.get('emoji_generator')).__name__ if 'emoji_generator' in ret else 'absent', repr(ret.get('emoji_generator')))
except Exception as e:
print('configuration test failed:', repr(type(e).__name__ + ': ' + str(e)))
PYRepository: AltimateAI/altimate-code
Length of output: 317
🌐 Web query:
MkDocs Material icons emojis emoji_index null emoji_generator null
💡 Result:
In Material for MkDocs, the configuration settings for emoji_index and emoji_generator within the pymdownx.emoji extension must be set to specific Python functions rather than null. Setting these to null is generally an error caused by misconfiguration or issues with third-party hosting platforms like Read the Docs parsing the YAML file incorrectly [1]. To correctly enable icons and emojis in your mkdocs.yml, you should use the following configuration [2][3][4]: markdown_extensions: - pymdownx.emoji: emoji_index:!!python/name:material.extensions.emoji.twemoji emoji_generator:!!python/name:material.extensions.emoji.to_svg Historical note: If you are using a very old version of Material for MkDocs (prior to version 9.4.0), you may see references to the older materialx.emoji package [5][6]. However, in all modern versions, the logic has been moved into the core theme, and material.extensions.emoji is the required path [5][6][7]. If these values are appearing as null in your build process, verify that your YAML file is not being modified or stripped by your CI/CD environment or hosting provider during the build process [1].
Citations:
- 1: MkDocs builds perfectly locally, but gets stuck on Read the Docs readthedocs/readthedocs.org#7865
- 2: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
- 3: https://squidfunk.github.io/mkdocs-material/setup/extensions/
- 4: emoji not being printed/rendered squidfunk/mkdocs-material#7270
- 5: Icons broken on
mastersquidfunk/mkdocs-material#6054 - 6: https://github.com/facelessuser/mkdocs-material-extensions/blob/master/materialx/emoji.py
- 7: https://github.com/squidfunk/mkdocs-material/blob/ae05a534/material/extensions/emoji.py
🌐 Web query:
"def test_emoji_null" "mkdocs-material" "emoji_index" "emoji_generator" "None"
💡 Result:
There is no standard or built-in function named test_emoji_null within the Material for MkDocs codebase [1][2]. The configuration of emojis and icons in Material for MkDocs relies on the pymdownx.emoji extension, which requires two primary components specified in your mkdocs.yml file [3][4]: 1. emoji_index: A callable that returns the dictionary of available emojis/icons (e.g.,!!python/name:material.extensions.emoji.twemoji) [1][3]. 2. emoji_generator: A callable that converts an icon shortcode into an SVG element (e.g.,!!python/name:material.extensions.emoji.to_svg) [1][3]. If you are encountering references to test_emoji_null, it is likely a user-defined function or a placeholder from custom internal testing code, rather than a part of the official Material for MkDocs library or its associated extensions [1][5][2]. For production configurations, you should use the official paths provided in the documentation [3][4]. If you are developing custom emoji logic, ensure your Python code properly imports and utilizes the existing material.extensions.emoji module [1][2].
Citations:
- 1: https://github.com/squidfunk/mkdocs-material/blob/ae05a534/material/extensions/emoji.py
- 2: Adding custom icons in custom theme extending Material for MkDocs squidfunk/mkdocs-material#7371
- 3: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
- 4: emoji not being printed/rendered squidfunk/mkdocs-material#7270
- 5: Custom emoji generator causes unnecessary deprecation warning squidfunk/mkdocs-material#7276
Restore the Material emoji generators before release.
emoji_index and emoji_generator are required callable settings for pymdownx.emoji when emoji shortcodes such as :material-cog:{ .lg .middle } are rendered. Setting them to null leaves no valid index or generator for those icons and can break MkDocs builds on pages that use Material emojis. Keep the original Material extensions or replace them with valid !!python/name:... callables.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/mkdocs.yml` around lines 66 - 68, Restore valid callable Material emoji
settings under pymdownx.emoji by replacing the null emoji_index and
emoji_generator values with the original Material extensions or equivalent
!!python/name callables. Ensure Material emoji shortcodes render successfully
during MkDocs builds.
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
| - attr_list | ||
| - md_in_html | ||
| - pymdownx.emoji: | ||
| emoji_index: null |
There was a problem hiding this comment.
WARNING: pymdownx.emoji index/generator dropped to null — breaks the Material icon shortcodes still used in the docs.
The sync replaced the required !!python/name:material.extensions.emoji.twemoji / to_svg tags with null. Those !!python/name: tags cannot survive a plain YAML parse/reserialize (a likely sync_to_oss.py artifact), but Material for MkDocs needs them to render the :octicons-*: / :material-*: shortcodes that are still present in the synced content (e.g. [:octicons-arrow-right-24: Browse more examples] in docs/docs/getting-started/index.md). With null, those shortcodes either render as literal text (silently — CI's mkdocs build may not catch it) or fail the build outright, depending on the pinned pymdownx version. Restore the tags:
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svgReply with @kilocode-bot fix it to have Kilo Code address this issue.
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Incremental review (since
No new findings. The previously-raised Files Reviewed (33 files)Front-matter cleanup (29):
Functional content (4):
Previous Review Summary (commit 96579c7)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit 96579c7)Status: 1 Issue Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
Files Reviewed (70 files)
Reviewed by glm-5.2 · Input: 33.7K · Output: 5.1K · Cached: 310K Review guidance: REVIEW.md from base branch |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
5 issues found across 75 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/mkdocs.yml">
<violation number="1" location="docs/mkdocs.yml:67">
P2: The emoji config was changed from Material's twemoji/to_svg to `emoji_index: null`/`emoji_generator: null`, but the synced pages still use `:material-*:` / `:octicons-*:` icon shortcodes. Those will no longer resolve and will render as raw literal text (e.g. `:octicons-arrow-right-24:`) across getting-started/index.md, configure/index.md, governance.md, etc. Restore the Material emoji index/generator, or migrate the shortcodes if disabling emoji is intentional.</violation>
<violation number="2" location="docs/mkdocs.yml:150">
P2: The regenerated nav references 38 `datamates/...` pages that don't exist anywhere in this repo (no `docs/docs/datamates/` directory), and the docs CI just runs `mkdocs build` without populating them. MkDocs will warn about missing pages and the whole 'Altimate MCP' section will render without working links on the public docs. Either sync the datamates content into this repo or prune those nav entries (in help-docs) so the nav matches what ships.</violation>
</file>
<file name="docs/docs/usage/ide.md">
<violation number="1" location="docs/docs/usage/ide.md:36">
P3: The updated command-palette steps now reference "Altimate MCP", while the rest of this page still tells the reader to search for and install the "Datamates" extension. If the command palette namespace has genuinely been renamed to "Altimate MCP", consider aligning the other references (extension name, the Windsurf "search Datamates" step, and the intro link label) so the guide uses one product name; if the extension display name should stay "Datamates", then clarify that the command namespace differs. This is a consistency nitpick but easy for readers to trip over mid-setup.</violation>
</file>
<file name="docs/docs/llms.txt">
<violation number="1" location="docs/docs/llms.txt:10">
P2: The de-prefixing pass stripped the `https://help.altimate.ai` domain from these links but left the `/code/` path segment in place, e.g. `/code/quickstart/`. Since the deployed site's routes (per mkdocs.yml nav) don't have a `/code/` prefix, these llms.txt links won't resolve at the deployed docs origin.</violation>
</file>
<file name="docs/docs/index.md">
<violation number="1" location="docs/docs/index.md:28">
P3: These new card headings jump from the page's h1 straight to h3, skipping h2, which creates an invalid heading outline (flagged by markdownlint MD001). Change `### [Quickstart](/getting-started/)` and the other five card headings to `##`.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| - Server API: develop/server.md | ||
| - Plugins: develop/plugins.md | ||
| - Ecosystem: develop/ecosystem.md | ||
| - Altimate MCP: |
There was a problem hiding this comment.
P2: The regenerated nav references 38 datamates/... pages that don't exist anywhere in this repo (no docs/docs/datamates/ directory), and the docs CI just runs mkdocs build without populating them. MkDocs will warn about missing pages and the whole 'Altimate MCP' section will render without working links on the public docs. Either sync the datamates content into this repo or prune those nav entries (in help-docs) so the nav matches what ships.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/mkdocs.yml, line 150:
<comment>The regenerated nav references 38 `datamates/...` pages that don't exist anywhere in this repo (no `docs/docs/datamates/` directory), and the docs CI just runs `mkdocs build` without populating them. MkDocs will warn about missing pages and the whole 'Altimate MCP' section will render without working links on the public docs. Either sync the datamates content into this repo or prune those nav entries (in help-docs) so the nav matches what ships.</comment>
<file context>
@@ -15,142 +14,178 @@ theme:
+ - Server API: develop/server.md
+ - Plugins: develop/plugins.md
+ - Ecosystem: develop/ecosystem.md
+- Altimate MCP:
+ - Overview: datamates/index.md
+ - Introduction: datamates/user-guide/home.md
</file context>
| emoji_index: null | ||
| emoji_generator: null |
There was a problem hiding this comment.
P2: The emoji config was changed from Material's twemoji/to_svg to emoji_index: null/emoji_generator: null, but the synced pages still use :material-*: / :octicons-*: icon shortcodes. Those will no longer resolve and will render as raw literal text (e.g. :octicons-arrow-right-24:) across getting-started/index.md, configure/index.md, governance.md, etc. Restore the Material emoji index/generator, or migrate the shortcodes if disabling emoji is intentional.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/mkdocs.yml, line 67:
<comment>The emoji config was changed from Material's twemoji/to_svg to `emoji_index: null`/`emoji_generator: null`, but the synced pages still use `:material-*:` / `:octicons-*:` icon shortcodes. Those will no longer resolve and will render as raw literal text (e.g. `:octicons-arrow-right-24:`) across getting-started/index.md, configure/index.md, governance.md, etc. Restore the Material emoji index/generator, or migrate the shortcodes if disabling emoji is intentional.</comment>
<file context>
@@ -15,142 +14,178 @@ theme:
+- attr_list
+- md_in_html
+- pymdownx.emoji:
+ emoji_index: null
+ emoji_generator: null
nav:
</file context>
| emoji_index: null | |
| emoji_generator: null | |
| emoji_index: !!python/name:material.extensions.emoji.twemoji | |
| emoji_generator: !!python/name:material.extensions.emoji.to_svg |
| - [Quickstart (5 min)](https://help.altimate.ai/code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes. | ||
| - [Full Setup Guide](https://help.altimate.ai/code/getting-started/): Complete installation, warehouse configuration for all 8 supported warehouses, LLM provider setup, and first-run walkthrough. | ||
| - [Network & Proxy](https://help.altimate.ai/code/reference/network/): Proxy configuration, CA certificate setup, firewall requirements. | ||
| - [Quickstart (5 min)](/code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes. |
There was a problem hiding this comment.
P2: The de-prefixing pass stripped the https://help.altimate.ai domain from these links but left the /code/ path segment in place, e.g. /code/quickstart/. Since the deployed site's routes (per mkdocs.yml nav) don't have a /code/ prefix, these llms.txt links won't resolve at the deployed docs origin.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/llms.txt, line 10:
<comment>The de-prefixing pass stripped the `https://help.altimate.ai` domain from these links but left the `/code/` path segment in place, e.g. `/code/quickstart/`. Since the deployed site's routes (per mkdocs.yml nav) don't have a `/code/` prefix, these llms.txt links won't resolve at the deployed docs origin.</comment>
<file context>
@@ -1,42 +1,42 @@
-- [Quickstart (5 min)](https://help.altimate.ai/code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes.
-- [Full Setup Guide](https://help.altimate.ai/code/getting-started/): Complete installation, warehouse configuration for all 8 supported warehouses, LLM provider setup, and first-run walkthrough.
-- [Network & Proxy](https://help.altimate.ai/code/reference/network/): Proxy configuration, CA certificate setup, firewall requirements.
+- [Quickstart (5 min)](/code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes.
+- [Full Setup Guide](/code/getting-started/): Complete installation, warehouse configuration for all 8 supported warehouses, LLM provider setup, and first-run walkthrough.
+- [Network & Proxy](/code/reference/network/): Proxy configuration, CA certificate setup, firewall requirements.
</file context>
| - [Quickstart (5 min)](/code/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes. | |
| - [Quickstart (5 min)](/quickstart/): Install altimate, configure your LLM provider, connect your warehouse, and run your first query in under 5 minutes. |
| 2. Type `Datamates` | ||
| 3. Select **Datamates: Open Altimate Code Chat** | ||
| 2. Type `Altimate MCP` | ||
| 3. Select **Altimate MCP: Open Altimate Code Chat** |
There was a problem hiding this comment.
P3: The updated command-palette steps now reference "Altimate MCP", while the rest of this page still tells the reader to search for and install the "Datamates" extension. If the command palette namespace has genuinely been renamed to "Altimate MCP", consider aligning the other references (extension name, the Windsurf "search Datamates" step, and the intro link label) so the guide uses one product name; if the extension display name should stay "Datamates", then clarify that the command namespace differs. This is a consistency nitpick but easy for readers to trip over mid-setup.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/usage/ide.md, line 36:
<comment>The updated command-palette steps now reference "Altimate MCP", while the rest of this page still tells the reader to search for and install the "Datamates" extension. If the command palette namespace has genuinely been renamed to "Altimate MCP", consider aligning the other references (extension name, the Windsurf "search Datamates" step, and the intro link label) so the guide uses one product name; if the extension display name should stay "Datamates", then clarify that the command namespace differs. This is a consistency nitpick but easy for readers to trip over mid-setup.</comment>
<file context>
@@ -27,8 +32,8 @@ Install the Datamates extension for your IDE:
-2. Type `Datamates`
-3. Select **Datamates: Open Altimate Code Chat**
+2. Type `Altimate MCP`
+3. Select **Altimate MCP: Open Altimate Code Chat**
This opens the Altimate Code chat panel where you can interact with altimate agents and use all 100+ data engineering tools.
</file context>
| <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 3 14h7l-1 8 10-12h-7l1-8z"/></svg> | ||
| </div> | ||
|
|
||
| ### [Quickstart](/getting-started/) |
There was a problem hiding this comment.
P3: These new card headings jump from the page's h1 straight to h3, skipping h2, which creates an invalid heading outline (flagged by markdownlint MD001). Change ### [Quickstart](/getting-started/) and the other five card headings to ##.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/index.md, line 28:
<comment>These new card headings jump from the page's h1 straight to h3, skipping h2, which creates an invalid heading outline (flagged by markdownlint MD001). Change `### [Quickstart](/getting-started/)` and the other five card headings to `##`.</comment>
<file context>
@@ -1,10 +1,107 @@
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="M13 2 3 14h7l-1 8 10-12h-7l1-8z"/></svg>
+</div>
+
+### [Quickstart](/getting-started/)
+
+Install, connect a warehouse and an LLM, and make your first run in under five minutes.
</file context>
…+ corrections Regenerated from help-docs docs/code (branch docs/reconcile-both-changed). Includes the reconciled both-changed files plus post-review corrections: - quickstart-new: telemetry link -> reference/telemetry.md and canonical ALTIMATE_TELEMETRY_DISABLED=true (was OPENCODE_DISABLE_TELEMETRY=1) - stranded closing double-quotes joined onto their value line (front matter, fenced YAML examples, CLI output) - providers.md Cortex prompt-caching + refreshed model catalog - llms.txt kept on absolute help.altimate.ai URLs nav regenerated from help-docs (section prefix stripped). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011fcN8kPwzjDeBysYUzKfJU
96579c7 to
1b8a056
Compare
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/docs/getting-started/index.md`:
- Line 54: Change all documentation card headings from level-three to level-two
headings: update the six card headings at docs/docs/getting-started/index.md
lines 54, 67, 80, 93, 106, and 119, and the six card headings at
docs/docs/index.md lines 28, 41, 54, 67, 80, and 93.
In `@docs/docs/usage/ide.md`:
- Around line 1-3: Update the references around the IDE installation and usage
instructions to use one consistent extension name, preferably Datamates,
matching the title and the extension identifier
altimateai.vscode-altimate-mcp-server. Replace the `Altimate MCP` wording on the
affected lines without changing the CLI command or other setup details.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: d15578e1-b386-4f62-a71f-e508acbbfb5d
📒 Files selected for processing (75)
docs/docs/configure/acp.mddocs/docs/configure/agents.mddocs/docs/configure/bedrock-custom-endpoints.mddocs/docs/configure/commands.mddocs/docs/configure/config.mddocs/docs/configure/context-management.mddocs/docs/configure/custom-tools.mddocs/docs/configure/formatters.mddocs/docs/configure/governance.mddocs/docs/configure/index.mddocs/docs/configure/keybinds.mddocs/docs/configure/lsp.mddocs/docs/configure/mcp-servers.mddocs/docs/configure/models.mddocs/docs/configure/permissions.mddocs/docs/configure/providers.mddocs/docs/configure/rules.mddocs/docs/configure/skills.mddocs/docs/configure/themes.mddocs/docs/configure/tools.mddocs/docs/configure/tools/config.mddocs/docs/configure/tools/core-tools.mddocs/docs/configure/tools/custom.mddocs/docs/configure/tools/index.mddocs/docs/configure/trace.mddocs/docs/configure/warehouses.mddocs/docs/data-engineering/agent-modes.mddocs/docs/data-engineering/guides/clickhouse.mddocs/docs/data-engineering/guides/cost-optimization.mddocs/docs/data-engineering/guides/data-parity.mddocs/docs/data-engineering/guides/index.mddocs/docs/data-engineering/guides/migration.mddocs/docs/data-engineering/guides/using-with-claude-code.mddocs/docs/data-engineering/guides/using-with-codex.mddocs/docs/data-engineering/tools/dbt-tools.mddocs/docs/data-engineering/tools/finops-tools.mddocs/docs/data-engineering/tools/index.mddocs/docs/data-engineering/tools/lineage-tools.mddocs/docs/data-engineering/tools/memory-tools.mddocs/docs/data-engineering/tools/schema-tools.mddocs/docs/data-engineering/tools/sql-tools.mddocs/docs/data-engineering/tools/warehouse-tools.mddocs/docs/data-engineering/training/index.mddocs/docs/data-engineering/training/team-deployment.mddocs/docs/data-engineering/validators.mddocs/docs/develop/ecosystem.mddocs/docs/develop/plugins.mddocs/docs/develop/sdk.mddocs/docs/develop/server.mddocs/docs/drivers.mddocs/docs/examples/index.mddocs/docs/getting-started.mddocs/docs/getting-started/index.mddocs/docs/getting-started/quickstart-new.mddocs/docs/getting-started/quickstart.mddocs/docs/index.mddocs/docs/llms.txtdocs/docs/quickstart.mddocs/docs/reference/changelog.mddocs/docs/reference/network.mddocs/docs/reference/security-faq.mddocs/docs/reference/telemetry.mddocs/docs/reference/troubleshooting.mddocs/docs/reference/windows-wsl.mddocs/docs/usage/check.mddocs/docs/usage/ci-headless.mddocs/docs/usage/cli.mddocs/docs/usage/dbt-pr-review-corpus.mddocs/docs/usage/dbt-pr-review.mddocs/docs/usage/github.mddocs/docs/usage/gitlab.mddocs/docs/usage/ide.mddocs/docs/usage/tui.mddocs/docs/usage/web.mddocs/mkdocs.yml
🚧 Files skipped from review as they are similar to previous changes (69)
- docs/docs/configure/tools/core-tools.md
- docs/docs/develop/server.md
- docs/docs/configure/themes.md
- docs/docs/data-engineering/tools/sql-tools.md
- docs/docs/develop/sdk.md
- docs/docs/examples/index.md
- docs/docs/data-engineering/guides/data-parity.md
- docs/docs/configure/agents.md
- docs/docs/configure/acp.md
- docs/docs/configure/commands.md
- docs/docs/configure/keybinds.md
- docs/docs/configure/warehouses.md
- docs/docs/drivers.md
- docs/docs/configure/formatters.md
- docs/docs/usage/ci-headless.md
- docs/docs/develop/ecosystem.md
- docs/docs/configure/tools/index.md
- docs/docs/data-engineering/training/team-deployment.md
- docs/docs/data-engineering/guides/using-with-codex.md
- docs/docs/quickstart.md
- docs/docs/configure/models.md
- docs/docs/configure/custom-tools.md
- docs/docs/configure/tools/custom.md
- docs/docs/data-engineering/guides/index.md
- docs/docs/data-engineering/validators.md
- docs/docs/configure/bedrock-custom-endpoints.md
- docs/docs/data-engineering/tools/warehouse-tools.md
- docs/docs/usage/cli.md
- docs/docs/usage/gitlab.md
- docs/docs/configure/tools/config.md
- docs/docs/configure/context-management.md
- docs/docs/data-engineering/agent-modes.md
- docs/docs/data-engineering/tools/memory-tools.md
- docs/docs/configure/index.md
- docs/docs/configure/lsp.md
- docs/docs/develop/plugins.md
- docs/docs/configure/permissions.md
- docs/docs/usage/check.md
- docs/docs/data-engineering/tools/index.md
- docs/docs/configure/providers.md
- docs/docs/usage/tui.md
- docs/docs/configure/tools.md
- docs/docs/data-engineering/guides/cost-optimization.md
- docs/docs/data-engineering/tools/dbt-tools.md
- docs/docs/data-engineering/tools/finops-tools.md
- docs/docs/data-engineering/guides/migration.md
- docs/docs/usage/dbt-pr-review-corpus.md
- docs/docs/reference/network.md
- docs/docs/configure/skills.md
- docs/docs/reference/changelog.md
- docs/docs/getting-started.md
- docs/docs/reference/troubleshooting.md
- docs/docs/data-engineering/tools/schema-tools.md
- docs/docs/data-engineering/training/index.md
- docs/docs/configure/mcp-servers.md
- docs/docs/configure/config.md
- docs/docs/usage/dbt-pr-review.md
- docs/docs/configure/governance.md
- docs/docs/reference/telemetry.md
- docs/docs/configure/rules.md
- docs/docs/usage/web.md
- docs/docs/reference/security-faq.md
- docs/docs/data-engineering/guides/clickhouse.md
- docs/docs/configure/trace.md
- docs/docs/data-engineering/guides/using-with-claude-code.md
- docs/docs/getting-started/quickstart.md
- docs/docs/reference/windows-wsl.md
- docs/docs/usage/github.md
- docs/docs/data-engineering/tools/lineage-tools.md
| <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round"><path d="M17.5 19a4.5 4.5 0 1 0-2.45-8.28A6.5 6.5 0 0 0 4 13.5a4.5 4.5 0 0 0 4.5 4.5h9z"/></svg> | ||
| </div> | ||
|
|
||
| ### [Bring Your Own LLM](/configure/providers/) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use level-two headings for documentation card headings.
Both pages use ### for cards without a level-two parent. This creates an invalid heading outline. Change the affected card headings to ##.
docs/docs/getting-started/index.md#L54-L54: change the six card headings at Lines 54, 67, 80, 93, 106, and 119.docs/docs/index.md#L28-L28: change the six card headings at Lines 28, 41, 54, 67, 80, and 93.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 54-54: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
📍 Affects 2 files
docs/docs/getting-started/index.md#L54-L54(this comment)docs/docs/index.md#L28-L28
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/getting-started/index.md` at line 54, Change all documentation card
headings from level-three to level-two headings: update the six card headings at
docs/docs/getting-started/index.md lines 54, 67, 80, 93, 106, and 119, and the
six card headings at docs/docs/index.md lines 28, 41, 54, 67, 80, and 93.
Source: Linters/SAST tools
| --- | ||
| title: "IDE Integration — Altimate Code in VS Code" | ||
| description: "Use Altimate Code inside VS Code via the Datamates extension. Requires the altimate-code CLI to be installed." |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repo files matching ide.md:"
fd -a 'ide\.md$' . || true
file="docs/docs/usage/ide.md"
if [ -f "$file" ]; then
echo
echo "File size:"
wc -l "$file"
echo
echo "Relevant occurrences:"
rg -n -i "Datamates|Altimate MCP|extension|marketplace|Altimate|installation|Install" "$file" || true
echo
echo "Full file with line numbers (bounded lines 1-120):"
sed -n '1,120p' "$file" | nl -ba
fi
echo
echo "Search repository for Datamates/Altimate MCP references:"
rg -n -i "Datamates|Altimate MCP" . --glob '!node_modules' --glob '!dist' --glob '!build' | head -200Repository: AltimateAI/altimate-code
Length of output: 4071
🌐 Web query:
altimateai vscode-altimate-mcp-server marketplace Datamates extension
💡 Result:
The Datamates extension for Visual Studio Code is officially listed on the Microsoft Visual Studio Marketplace under the identifier altimateai.vscode-altimate-mcp-server [1]. It serves as a local-first Model Context Protocol (MCP) server and integration layer developed by Altimate AI [2][3]. Key details regarding the extension include: Functionality: It integrates various data engineering tools (such as dbt, Snowflake, Databricks, Airflow, Jira, and others) directly into IDEs like VS Code, Cursor, and Windsurf [1][2][4]. It enables features like AI-powered chat, context management via Knowledge Hub and Memory Hub, and data pipeline automation [1][4]. Installation: While the extension is primarily identified as Datamates in the marketplace [1], it is frequently referred to in documentation as the Altimate MCP server or Altimate Datamates [5][6][7]. Users can install it directly from the VS Code marketplace [1][4]. For other environments like Cursor or Open VSX-compatible editors, it is available via the Open VSX Registry [4][3][7]. Technical Context: The extension works by connecting to your Altimate AI instance to configure specific data connections [5][6]. It manages an MCP server locally on the user's machine, ensuring that credentials and sensitive data do not leave the environment [2][6]. Troubleshooting: If the extension is not visible in the marketplace search, official documentation suggests checking for stable internet connectivity, ensuring the VS Code version is 1.95.0 or higher, or using the command line install command: code --install-extension altimateai.vscode-altimate-mcp-server [8].
Citations:
- 1: https://marketplace.visualstudio.com/items?itemName=altimateai.vscode-altimate-mcp-server
- 2: https://datamates-docs.myaltimate.com/
- 3: https://help.altimate.ai/resources/marketplace/
- 4: https://help.altimate.ai/code/usage/ide/
- 5: https://datamates-docs.myaltimate.com/user-guide/setup/vscode-setup/
- 6: https://help.altimate.ai/datamates/user-guide/setup/vscode-setup/
- 7: https://help.altimate.ai/datamates/user-guide/setup/setup/
- 8: https://help.altimate.ai/datamates/faq/troubleshooting/
Make the command and extension name consistent.
The extension is Datamates (altimateai.vscode-altimate-mcp-server), but lines 35-36 use Altimate MCP. Keep the extension name as Datamates or change all Datamates references to Altimate MCP; users should not need both terms.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/usage/ide.md` around lines 1 - 3, Update the references around the
IDE installation and usage instructions to use one consistent extension name,
preferably Datamates, matching the title and the extension identifier
altimateai.vscode-altimate-mcp-server. Replace the `Altimate MCP` wording on the
affected lines without changing the CLI command or other setup details.
| - pymdownx.emoji: | ||
| emoji_index: null | ||
| emoji_generator: null |
There was a problem hiding this comment.
CRITICAL — mkdocs build fails outright; the docs deploy is broken
The YAML round-trip replaced the !!python/name: tags with null, and pymdownx.emoji calls inspect.getfullargspec() on emoji_index. Building this branch aborts:
ERROR - Config value 'markdown_extensions': Failed to load extension 'pymdownx.emoji'.
File ".../pymdownx/emoji.py", line 257, in _set_index
if len(inspect.getfullargspec(index).args):
TypeError: unsupported callable
Aborted with a configuration error!
main builds clean (exit 0); this branch does not. .github/workflows/docs.yml runs exactly mkdocs build -f docs/mkdocs.yml -d site, so the Pages job fails and nothing publishes. GitHub Pages keeps serving the last successful build, so the site does not go dark — it silently freezes, and every future docs change fails to deploy with no user-visible signal.
The extension is genuinely in use: 17 :octicons-arrow-right-24: plus :material-github:, :material-palette:, :material-puzzle:.
Fix — restore the tags, and make the sync preserve unknown YAML tags (or patch only the nav: key instead of rewriting the whole file):
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svgPatching just these two lines makes the build succeed, which is how the remaining issues below were confirmed.
| - Altimate MCP: | ||
| - Overview: datamates/index.md | ||
| - Introduction: datamates/user-guide/home.md | ||
| - Altimate Code Chat: datamates/user-guide/components/altimate-code.md | ||
| - Altimate LLM Gateway: datamates/user-guide/components/llm-gateway.md | ||
| - Setup: | ||
| - Overview: datamates/user-guide/setup/setup.md | ||
| - Cursor: datamates/user-guide/setup/cursor-setup.md | ||
| - Claude Code: datamates/user-guide/setup/claude-code-setup.md | ||
| - Cline: datamates/user-guide/setup/cline-setup.md | ||
| - VS Code: datamates/user-guide/setup/vscode-setup.md | ||
| - Components: | ||
| - Overview: datamates/user-guide/components/components_overview.md | ||
| - Integrations: | ||
| - Overview: datamates/user-guide/components/integrations/integrations.md | ||
| - Airflow: datamates/user-guide/components/integrations/airflow.md | ||
| - Altimate: datamates/user-guide/components/integrations/altimate.md | ||
| - BigQuery: datamates/user-guide/components/integrations/bigquery.md | ||
| - Dagster: datamates/user-guide/components/integrations/dagster.md | ||
| - Databricks: datamates/user-guide/components/integrations/databricks.md | ||
| - dbt: datamates/user-guide/components/integrations/dbt.md | ||
| - GitHub: datamates/user-guide/components/integrations/github.md | ||
| - Google Sheets: datamates/user-guide/components/integrations/google_sheets.md | ||
| - Jira: datamates/user-guide/components/integrations/jira.md | ||
| - Linear: datamates/user-guide/components/integrations/linear.md | ||
| - PostgreSQL: datamates/user-guide/components/integrations/postgresql.md | ||
| - Snowflake: datamates/user-guide/components/integrations/snowflake.md | ||
| - Knowledge Hub: datamates/user-guide/components/knowledgehub.md | ||
| - Memory Hub: datamates/user-guide/components/memory.md | ||
| - Guardrails: datamates/user-guide/components/guardrails.md | ||
| - Examples: | ||
| - Showcase: examples/index.md | ||
| - Use: | ||
| - Agents: | ||
| - Agent Modes: data-engineering/agent-modes.md | ||
| - Agent Config: configure/agents.md | ||
| - Tools: | ||
| - Overview: configure/tools/index.md | ||
| - Built-in Tools: configure/tools/config.md | ||
| - Core Tools: configure/tools/core-tools.md | ||
| - SQL Tools: data-engineering/tools/sql-tools.md | ||
| - Schema Tools: data-engineering/tools/schema-tools.md | ||
| - FinOps Tools: data-engineering/tools/finops-tools.md | ||
| - Lineage Tools: data-engineering/tools/lineage-tools.md | ||
| - dbt Tools: data-engineering/tools/dbt-tools.md | ||
| - Warehouse Tools: data-engineering/tools/warehouse-tools.md | ||
| - Memory Tools: data-engineering/tools/memory-tools.md | ||
| - Custom Tools: configure/tools/custom.md | ||
| - Skills: configure/skills.md | ||
| - Commands: configure/commands.md | ||
| - Validators: data-engineering/validators.md | ||
| - Trace: configure/trace.md | ||
| - Interfaces: | ||
| - TUI: usage/tui.md | ||
| - CLI: usage/cli.md | ||
| - SQL Check: usage/check.md | ||
| - Web UI: usage/web.md | ||
| - CI: usage/ci-headless.md | ||
| - IDE: usage/ide.md | ||
| - GitHub: usage/github.md | ||
| - GitLab: usage/gitlab.md | ||
| - dbt PR Review: usage/dbt-pr-review.md | ||
| - dbt PR Review — Issue Corpus: usage/dbt-pr-review-corpus.md | ||
| - Guides: | ||
| - Cost Optimization: data-engineering/guides/cost-optimization.md | ||
| - Migration: data-engineering/guides/migration.md | ||
| - Data Parity: data-engineering/guides/data-parity.md | ||
| - Using with Claude Code: data-engineering/guides/using-with-claude-code.md | ||
| - Using with Codex: data-engineering/guides/using-with-codex.md | ||
| - ClickHouse: data-engineering/guides/clickhouse.md | ||
| - Configure: | ||
| - Overview: configure/index.md | ||
| - Warehouses: configure/warehouses.md | ||
| - LLMs: | ||
| - Providers: configure/providers.md | ||
| - Models: configure/models.md | ||
| - Bedrock Custom Endpoints: configure/bedrock-custom-endpoints.md | ||
| - MCPs & ACPs: | ||
| - MCP Servers: configure/mcp-servers.md | ||
| - ACP Support: configure/acp.md | ||
| - Appearance: | ||
| - Themes: configure/themes.md | ||
| - Keybinds: configure/keybinds.md | ||
| - Training: | ||
| - Overview: data-engineering/training/index.md | ||
| - Team Deployment: data-engineering/training/team-deployment.md | ||
| - Additional Config: | ||
| - LSP Servers: configure/lsp.md | ||
| - Network: reference/network.md | ||
| - Windows / WSL: reference/windows-wsl.md | ||
| - Config File Reference: configure/config.md | ||
| - Governance: | ||
| - Overview: configure/governance.md | ||
| - Rules: configure/rules.md | ||
| - Permissions: configure/permissions.md | ||
| - Context Management: configure/context-management.md | ||
| - Formatters: configure/formatters.md | ||
| - Reference: | ||
| - Changelog: reference/changelog.md | ||
| - Telemetry: reference/telemetry.md | ||
| - Security FAQ: reference/security-faq.md | ||
| - Troubleshooting: reference/troubleshooting.md | ||
| - Extend: | ||
| - SDK: develop/sdk.md | ||
| - Server API: develop/server.md | ||
| - Plugins: develop/plugins.md | ||
| - Ecosystem: develop/ecosystem.md | ||
| - Overview: datamates/examples/examples.md | ||
| - Build, Test, Docs for dbt Models: datamates/examples/build-test-document-dbt-model.md | ||
| - Find Broken Views in Snowflake: datamates/examples/find-broken-views-snowflake.md | ||
| - Optimize Cost and Performance: datamates/examples/optimize-costs-and-performance.md | ||
| - Migrate a pyspark project to dbt: datamates/examples/migrate-pyspark-dbt.md | ||
| - Debug an Airflow DAG: datamates/examples/debug-airflow-dag.md | ||
| - Write Snowflake UDFs: datamates/examples/write-snowflake-udfs.md | ||
| - FAQ: | ||
| - Security FAQs: datamates/faq/security.md | ||
| - Pricing FAQs: datamates/faq/pricing-faqs.md | ||
| - Troubleshooting: datamates/faq/troubleshooting.md |
There was a problem hiding this comment.
MAJOR — 36 nav entries point at files that don't exist
This entire Altimate MCP section was lifted from the unified help-docs nav, but the content was never copied: docs/docs/datamates/ does not exist in this repo. main has zero datamates/ nav entries.
With the emoji fix applied so the build can run, MkDocs emits 36 warnings:
WARNING - A reference to 'datamates/index.md' is included in the 'nav' configuration, which is not found in the documentation files.
WARNING - A reference to 'datamates/user-guide/home.md' ...
... (36 total)
These are warnings, not build failures — strict is unset — so this ships rather than failing CI. Confirmed against the built artifact: the rendered index.html contains the Altimate MCP section with 37 datamates references emitted as raw unprocessed paths:
href="datamates/examples/examples.md"
href="datamates/faq/security.md"So these publish as dead links pointing at .md files. Note this also becomes a hard build failure the moment anyone sets strict: true.
Fix — either sync the datamates/** content, or have the sync prune nav subtrees whose targets aren't in the mirrored file set and replace this section with a single external link to https://help.altimate.ai/datamates/.
| - [Power User for dbt](/dbt-power-user/) — Best dbt extension for VS Code / Cursor. | ||
| - [Altimate MCP](/datamates/) — A local-first MCP server for your data stack. | ||
| - [Altimate Lite for Snowflake](/snowflake-native-app/) — More out of your Snowflake compute, without your data leaving your account. |
There was a problem hiding this comment.
MAJOR — root-relative cross-product links 404 on this domain
This repo deploys standalone: docs/docs/CNAME is docs.altimate.sh and site_url: https://docs.altimate.sh. The unified-site "de-prefixing" rewrote working fully-qualified URLs into root-relative paths that only resolve on help.altimate.ai.
git grep confirms 0 such links on main, 8 on this branch. On docs.altimate.sh, /datamates/, /dbt-power-user/, and /snowflake-native-app/ are all 404s — and /datamates/ is unreachable in this repo regardless, since that content was never synced.
Fix — keep cross-product links fully qualified (https://help.altimate.ai/...). De-prefixing is only correct for pages that exist within this mirror.
All three targets here are external products, so all three should be absolute URLs.
|
|
||
| - **BYOK (Bring Your Own Key)** — Free and unlimited. Configure any of the [35+ supported providers](../configure/providers.md) (Anthropic, OpenAI, AWS Bedrock, Azure OpenAI, etc.) | ||
| - **[Altimate LLM Gateway](https://help.altimate.ai/datamates/user-guide/components/llm-gateway/)** — Managed LLM access with dynamic model routing. 10M tokens free to get started — no API keys to manage | ||
| - **[Altimate LLM Gateway](/datamates/user-guide/components/llm-gateway/)** — Managed LLM access with dynamic model routing. 10M tokens free to get started — no API keys to manage |
There was a problem hiding this comment.
MAJOR — de-prefixed link now 404s on docs.altimate.sh
This is the clearest instance of the regression — a working fully-qualified URL was rewritten into a path that only resolves on help.altimate.ai:
--- **[Altimate LLM Gateway](https://help.altimate.ai/datamates/user-guide/components/llm-gateway/)** — ...
-+- **[Altimate LLM Gateway](/datamates/user-guide/components/llm-gateway/)** — ...This repo publishes to docs.altimate.sh (CNAME + site_url), where /datamates/... does not exist. The LLM Gateway link is the most damaging of the eight, since it appears in provider setup, quickstart, and IDE guidance.
Fix — restore the fully-qualified https://help.altimate.ai/datamates/user-guide/components/llm-gateway/.
| ``` | ||
|
|
||
| For pricing, security, and data handling details, see the [Altimate LLM Gateway guide](https://help.altimate.ai/datamates/user-guide/components/llm-gateway/). | ||
| For pricing, security, and data handling details, see the [Altimate LLM Gateway guide](/datamates/user-guide/components/llm-gateway/). |
There was a problem hiding this comment.
MAJOR — de-prefixed link now 404s on docs.altimate.sh
This is the clearest instance of the regression — a working fully-qualified URL was rewritten into a path that only resolves on help.altimate.ai:
--- **[Altimate LLM Gateway](https://help.altimate.ai/datamates/user-guide/components/llm-gateway/)** — ...
-+- **[Altimate LLM Gateway](/datamates/user-guide/components/llm-gateway/)** — ...This repo publishes to docs.altimate.sh (CNAME + site_url), where /datamates/... does not exist. The LLM Gateway link is the most damaging of the eight, since it appears in provider setup, quickstart, and IDE guidance.
Fix — restore the fully-qualified https://help.altimate.ai/datamates/user-guide/components/llm-gateway/.
|
|
||
| [Get Started](quickstart.md){ .md-button .md-button--primary } | ||
| [See Examples](../examples/index.md){ .md-button } | ||
| [Get Started](/getting-started/quickstart/){ .md-button .md-button--primary } |
There was a problem hiding this comment.
MAJOR — same CTA mis-target as the homepage
/getting-started/quickstart/ resolves to getting-started/quickstart.md — the page titled "Setup Guide", which this PR removes from the nav — not to the nav-labeled Quickstart (quickstart-new.md).
| <div class="doc-links" markdown> | ||
|
|
||
| **Learn More** — [Quickstart](quickstart.md) | [Examples](../examples/index.md) | [Use](../data-engineering/agent-modes.md) | [Configure](../configure/index.md) | [Interfaces](../usage/tui.md) | [Reference](../reference/security-faq.md) | ||
| **Learn More** — [Quickstart](/getting-started/quickstart/) | [Examples](/examples/) | [Use](/data-engineering/agent-modes/) | [Configure](/configure/) | [Interfaces](/usage/tui/) | [Reference](/reference/security-faq/) |
There was a problem hiding this comment.
MINOR — same CTA mis-target in the footer links
[Quickstart](/getting-started/quickstart/) resolves to the "Setup Guide" page rather than the nav-labeled Quickstart (quickstart-new.md).
| @@ -1,7 +1,7 @@ | |||
| # altimate-code llms.txt | |||
| # AI-friendly documentation index for altimate-code | |||
| # Generated: 2026-03-18 | Version: v0.5.0 | |||
There was a problem hiding this comment.
MINOR — this file was touched but left materially stale
Two routes were corrected here (both good — verified they now point at real pages), but the file still contradicts docs shipped in this same commit:
llms.txt claim |
Reality in this repo |
|---|---|
Version: v0.5.0, generated 2026-03-18 |
packages/opencode/package.json = 1.17.9 |
| "all 8 supported warehouses" (line 11) | configure/warehouses.md documents 13 |
| "7 specialized agents (Builder, Analyst, Validator, Migrator, Researcher, Trainer, Executive)" (line 16) | configure/agents.md and data-engineering/agent-modes.md document 3: Builder, Analyst, Plan |
This is the file AI consumers read as the canonical product index, and it now disagrees with its own sibling pages.
Fix — regenerate from source data rather than hand-editing individual URLs.
| --- | ||
| title: altimate-code | ||
| title: Altimate Code | ||
| hide: | ||
| - toc | ||
| - navigation | ||
| --- |
There was a problem hiding this comment.
MINOR — the homepage is the one page with no SEO description
Of the 73 changed markdown files, 72 received both title and description. This one — the new landing page and the highest-value SEO surface in the site — has title and hide but no description, so it falls back to the generic site-wide site_description.
Fix — add a description matching this page's actual pitch.
| ## Full Altimate MCP Documentation | ||
|
|
||
| The Datamates extension offers additional capabilities beyond Altimate Code Chat, including MCP server integrations, Knowledge Hub, Memory Hub, and Guardrails. See the [Datamates documentation](https://help.altimate.ai/datamates/) for full setup guides, integration configuration, and feature details. | ||
| The Datamates extension offers additional capabilities beyond Altimate Code Chat, including MCP server integrations, Knowledge Hub, Memory Hub, and Guardrails. See the [Altimate MCP documentation](/datamates/) for full setup guides, integration configuration, and feature details. |
There was a problem hiding this comment.
MINOR — brand rename is half-applied
The "Datamates" → "Altimate MCP" rename was applied to command-palette labels and headings but not body copy. This line reads:
The Datamates extension offers additional capabilities … See the [Altimate MCP documentation]
…under a heading that says "Full Altimate MCP Documentation" — three names for one thing in two sentences. Six "Datamates" references remain in this file (lines 3, 8, 20, 24, 28, 73) plus develop/ecosystem.md:22.
Fix — if the VS Code marketplace listing is still literally named "Datamates", state that once explicitly ("the Altimate MCP extension, listed as Datamates in the marketplace") rather than alternating between the two names.
Review summary — requesting changesReviewed at 15 inline comments cover the issues that map to specific lines: 1 critical, 9 major, 5 minor. One clarification on severityThe 36 missing
MkDocs treats missing nav targets as warnings unless Issues not tied to a specific lineMINOR — the do-not-edit safeguard described in the PR is absentThe description says "each file carries a do-not-edit banner; this copy is regenerated automatically." Of the 74 markdown files under The whole migration rests on people not editing this mirror. Without the guardrail, local edits get silently clobbered on the next sync — which is exactly the problem the 13 reconciled edits represent. Fix — emit an HTML-comment banner at the top of every synced file, plus a CI check that fails when a file in the synced set changes without a corresponding MINOR — no pre-merge docs validation in CI
Fix — add a A strict PR-triggered build would have caught the emoji failure and the 36 dead nav targets outright, and would have surfaced the absolute-link warnings behind the cross-product and CTA issues. It would not, on its own, prove the CTA points at the semantically wrong page — that needs an explicit route assertion. NitsSync rewrites YAML inside fenced code blocks — The normalizer added quotes to Cosmetic YAML churn inflates the diff — Roughly 100 of the 297 changed lines in this file are pure round-trip noise: re-quoting Worth verifying before merge (not counted as defects)
Pre-existing debt (not introduced here)Nine files sit outside the nav. Eight pre-date this PR. The one worth acting on is What's done well
Suggested merge order
|
2 participants
Initial docs sync from AltimateAI/help-docs, which is now the source of truth for documentation.
tools/sync_to_oss.py.mkdocs.ymlnav regenerated from help-docs.First sync is large because help-docs content was developed substantially post-migration. Please review; anything here that should live in help-docs instead can be pulled back before merge.
🤖 Generated with Claude Code
Summary by cubic
Full docs sync from
AltimateAI/help-docs, reconciling the 13 previously excluded local edits. Ships a new homepage and refreshed Getting Started, overhauls nav (adds “Altimate MCP”), and standardizes SEO front matter, routes, and copy.Migration
AltimateAI/help-docs; this repo mirrors viahelp-docs/tools/sync_to_oss.py.Refactors
mkdocs.ymland nav (Overview at root; Use/Configure/Governance/Reference; new “Altimate MCP” section)./index.mdand Getting Started with new CTAs and example cards./usage/ci-headless.md, examples to/examples/, LLM Gateway to/datamates/..., trace to/configure/trace/, quickstart CTAs to/getting-started/quickstart/).llms.txtnow uses canonical absolutehttps://help.altimate.ai/code/URLs and reflects moved routes./reference/telemetry/and normalized env var toALTIMATE_TELEMETRY_DISABLED=true.Written for commit 1b8a056. Summary will update on new commits.
Summary by CodeRabbit