Home: Add "Welcome to CrateDB" teaser text #234
Conversation
amotl
added
sanding-1200
|
Caution Review failedThe pull request is closed. WalkthroughRewrote and reorganized the documentation homepage with new hero messaging, feature and use-case rubrics, expanded Get Started and Resources sections, updated cards/links and copy; plus a minor Sphinx cross-reference change in the drivers docs. No code/API changes. Changes
Sequence Diagram(s)(omitted — changes are documentation/content only and do not affect control flow) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
docs/home/index.md (4)
44-46: Grammar: “set up” (verb) and lighter closing.Two minor fixes to tighten tone and grammar.
-We've put together some helpful guides for you to setup your CrateDB instance +We've put together some helpful guides to help you set up your CrateDB instance quickly and easily. Enjoy the reading! +``` +Optionally: +```diff -quickly and easily. Enjoy the reading! +quickly and easily. Enjoy reading!
53-56: Grammar: vendor list and GCP naming.Add the serial comma and use “GCP” (not pluralized).
-backups, and scaling of CrateDB clusters on AWS, Azure or GCPs, eliminating +backups, and scaling of CrateDB clusters on AWS, Azure, or GCP, eliminating
62-66: CTA copy polish.Smoother phrasing and hyphenation.
-**Start forever free cluster with 8 GB of storage** +**Start a forever-free cluster with 8 GB of storage**
78-78: Heading label nit.“Details” is a bit generic; “Overview” or “Learn more” can read more naturally here.
-## Details +## Overview
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/home/index.md(2 hunks)
🧰 Additional context used
🧠 Learnings (8)
📓 Common learnings
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
📚 Learning: 2025-05-18T13:25:11.786Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:36.393Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:38.681Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Applied to files:
docs/home/index.md
📚 Learning: 2025-06-05T14:29:15.512Z
Learnt from: amotl
PR: crate/cratedb-guide#207
File: docs/integrate/etl/iceberg-risingwave.md:205-207
Timestamp: 2025-06-05T14:29:15.512Z
Learning: The `records.Database("crate://", echo=True)` connection string for CrateDB works with defaults: localhost as host, "crate" as user, and blank password. This is valid and functional code in the records library.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-06T02:11:46.794Z
Learnt from: amotl
PR: crate/cratedb-guide#222
File: docs/integrate/powerbi/index.md:16-23
Timestamp: 2025-08-06T02:11:46.794Z
Learning: The `project:` role in MyST Markdown syntax like `[](project:#powerbi-desktop)` and `[](project:#powerbi-service)` is valid cross-reference syntax in the CrateDB Guide repository's MyST Markdown setup.
Applied to files:
docs/home/index.md
🔇 Additional comments (4)
docs/home/index.md (4)
13-20: Strong, welcoming intro.Clear positioning and value props. Reads well and sets context effectively.
21-31: “Why CrateDB” bullets read cleanly and scan well.Good balance of brevity and substance.
32-41: Use-case framing is concise and relevant.Good breadth without overloading the reader.
107-108: Resources section placement LGTM.Nice separation of intro vs. resource deep dives.
amotl
changed the title
|
Shouldn't the "Overview" section then be deleted - at least the intro section there seems redundant? |
|
Hi. We are happy to bring in more changes as we go. Either within this PR, or by using subsequent iterations. This patch derived from GitBook should really just be a start. Thanks!
So, you are recommending to delete this whole section? 
Currently, that section takes a more technical stance than the new Why CrateDB? vs. What Can You Build? approach. I will be happy to try that variant, and possibly remove many other details from this page, maybe even the whole PoC about the "Learn" section at the bottom added the other day? Let us go through it together and apply some collaborative spring cleaning, taking into consideration that "delete" could also be implemented as a "move" operation, when the content fits better elsewhere? |
docs/home/index.md
Outdated
| ## Overview | ||
|
|
||
| Welcome to the official CrateDB Documentation. Whether you are a developer, | ||
| database administrator, or just starting your journey with CrateDB, our |
There was a problem hiding this comment.
@bmunkholm: Are you referring to the body of this little section re. your comment about redundancies? Here, that is certainly the case, thanks. Let's just remove that teaser here?
at least the intro section there seems redundant?
Got it! ;]
There was a problem hiding this comment.
The fix is part of e16a134.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
docs/home/index.md (1)
135-147: Use internal ref for “Getting Started” card (consistency + version awareness).Earlier feedback suggested this; it still points to an absolute URL. Align it with the other “Getting Started” card above.
-:link: https://cratedb.com/docs/guide/getting-started.html +:link: getting-started +:link-type: ref
🧹 Nitpick comments (6)
docs/home/index.md (6)
69-71: Tighten wording: “includes analyzing” → “lets you analyze”; “within” → “in”.Reads more naturally and avoids awkward phrasing.
-* In a unified data platform approach, CrateDB includes analyzing relational, JSON, - time-series, geospatial, full-text, and vector data within a single system, +* In a unified data platform, CrateDB lets you analyze relational, JSON, + time-series, geospatial, full-text, and vector data in a single system, eliminating the need for multiple databases.
82-83: Article fix: “a HTTP” → “an HTTP”.Minor grammar polish.
-* PostgreSQL wire protocol compatibility and a HTTP interface provide versatile +* PostgreSQL wire protocol compatibility and an HTTP interface provide versatile integration capabilities.
91-92: Remove duplication: “helpful guides to help”.Streamline copy.
-We've put together some helpful guides to help you set up your CrateDB instance +We've put together guides to help you set up your CrateDB instance
102-103: Fix list punctuation and product name: “Azure, or GCP”; singular “GCP”.Grammar correctness and brand consistency.
-backups, and scaling of CrateDB clusters on AWS, Azure or GCPs, eliminating +backups, and scaling of CrateDB clusters on AWS, Azure, or GCP, eliminating
350-350: Trim trailing spaces in card titles.Avoid rendering/linters issues.
-:::{grid-item-card} CrateDB Examples +:::{grid-item-card} CrateDB Examples-:::{grid-item-card} Sample Apps +:::{grid-item-card} Sample AppsAlso applies to: 363-363
410-417: Remove unused footnote [Integrations] (dead anchor).No references use this footnote, and the on-page anchor “#integrate” isn’t defined. Remove to prevent confusion.
-[Integrations]: #integrateIf you prefer to keep it, add an on-page anchor above “Drivers and Integrations”:
(integrate)= :::{rubric} Drivers and Integrations :::
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/connect/drivers.md(1 hunks)docs/home/index.md(4 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/connect/drivers.md
🧰 Additional context used
🧠 Learnings (9)
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:36.393Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:38.681Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-10T17:09:32.616Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/azure-functions/index.md:31-36
Timestamp: 2025-08-10T17:09:32.616Z
Learning: In the CrateDB Guide documentation, RST files (`.rst`) use reStructuredText anchor syntax `.. _anchor-name:` while Markdown files (`.md`) use MyST syntax `(anchor-name)=`. Cross-references between MyST Markdown and reStructuredText files work correctly - a MyST `:link:` directive can reference an RST anchor and vice versa.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-10T18:17:49.380Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/mysql/index.md:51-55
Timestamp: 2025-08-10T18:17:49.380Z
Learning: In the CrateDB Guide documentation, the file `docs/integrate/mysql/import-csv.rst` contains the reStructuredText label `.. _mysql-import-csv:` which can be referenced from MyST Markdown files using `:link: mysql-import-csv` with `:link-type: ref`. This is another example of cross-format referencing between MyST and RST files working correctly in Sphinx.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T13:25:11.786Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Applied to files:
docs/home/index.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
🔇 Additional comments (2)
docs/home/index.md (2)
94-99: Correct intersphinx target for CrateDB Cloud (cloud:index).Good catch using the inherited intersphinx mapping. This is the correct and future-proof target per our shared theme configuration.
112-112: Cloud free-tier storage remains 8 GB
Verified against the CrateDB Cloud “Forever Free” plan (Aug 12, 2025): it still provides 8 GiB of storage. No change needed to the copy.
There was a problem hiding this comment.
Actionable comments posted: 0
🔭 Outside diff range comments (1)
docs/home/index.md (1)
287-293: Broken in-page link: define “integrate” anchorA reference definition exists for [Integrations] → “#integrate”, but no such anchor is defined on this page. Add an explicit anchor above the “Drivers and Integrations” rubric.
-:::{rubric} Drivers and Integrations +(integrate)= +:::{rubric} Drivers and Integrations
🧹 Nitpick comments (9)
docs/home/index.md (9)
82-83: Grammar: “an HTTP interface”Indefinite article before “HTTP” should be “an.”
-* PostgreSQL wire protocol compatibility and a HTTP interface provide versatile +* PostgreSQL wire protocol compatibility and an HTTP interface provide versatile integration capabilities.
100-104: Grammar: cloud providers list (comma + “GCP”)
- Use Oxford comma for readability.
- “GCPs” → “GCP”.
-Backups, and scaling of CrateDB clusters on AWS, Azure or GCPs, eliminating +Backups, and scaling of CrateDB clusters on AWS, Azure, or GCP, eliminating
135-147: Prefer internal ref for Getting Started (version-aware, consistent)Use a local ref rather than an absolute URL for “Getting Started.”
-:link: https://cratedb.com/docs/guide/getting-started.html +:link: getting-started +:link-type: ref :link-alt: Getting started with CrateDB
85-86: Style: “third-party” spellingPrefer “third-party” over “3rd party” for consistency and professional tone.
- with an extensive 3rd party ecosystem of AI/ML frameworks for advanced data + with an extensive third-party ecosystem of AI/ML frameworks for advanced data
290-292: Style: “third-party” spellingUse “third-party.”
-and integrations with 3rd-party applications and frameworks. +and integrations with third-party applications and frameworks.
320-323: Style: “third-party” spellingUse “third-party.”
-Learn about the variety of options to connect and integrate with 3rd-party applications. +Learn about the variety of options to connect and integrate with third-party applications.
81-81: Tighten wording: “search query and aggregation”“Search query and aggregation performance” reads awkwardly. Suggest simplifying.
-* Columnar storage enables fast search query and aggregation performance. +* Columnar storage enables fast query and aggregation performance.
49-55: Sharpen use-case phrasing for clarity and resonanceMore outcome-oriented phrasing improves readability and reduces abstraction.
-* Real-time **analytics applications** -* Elegant **hybrid search applications** -* Large-scale **IoT platforms** +* Real-time **dashboards and analytics** +* Hybrid **search and retrieval experiences** +* Large-scale **IoT telemetry and analytics** * Complex **geospatial applications** * Embedded **AI-driven insights** * Modern **industrial data backends**
201-213: Use intersphinx for Admin UIWe inherit the
crate-admin-uimapping. Prefer a ref over an absolute URL for stability and version-awareness.-:link: https://cratedb.com/docs/crate/admin-ui/ +:link: crate-admin-ui:index +:link-type: ref
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/connect/drivers.md(1 hunks)docs/home/index.md(4 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/connect/drivers.md
🧰 Additional context used
🧠 Learnings (9)
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:36.393Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:38.681Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-10T17:09:32.616Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/azure-functions/index.md:31-36
Timestamp: 2025-08-10T17:09:32.616Z
Learning: In the CrateDB Guide documentation, RST files (`.rst`) use reStructuredText anchor syntax `.. _anchor-name:` while Markdown files (`.md`) use MyST syntax `(anchor-name)=`. Cross-references between MyST Markdown and reStructuredText files work correctly - a MyST `:link:` directive can reference an RST anchor and vice versa.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-10T18:17:49.380Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/mysql/index.md:51-55
Timestamp: 2025-08-10T18:17:49.380Z
Learning: In the CrateDB Guide documentation, the file `docs/integrate/mysql/import-csv.rst` contains the reStructuredText label `.. _mysql-import-csv:` which can be referenced from MyST Markdown files using `:link: mysql-import-csv` with `:link-type: ref`. This is another example of cross-format referencing between MyST and RST files working correctly in Sphinx.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T13:25:11.786Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Applied to files:
docs/home/index.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Build docs
🔇 Additional comments (2)
docs/home/index.md (2)
94-99: Good use of intersphinx for CrateDB Cloud
:link: cloud:indexis correct per our shared mappings. Thanks for aligning with the inherited intersphinx configuration.
109-113: Free-tier storage claim is still accurateThe forever-free CrateDB Cloud cluster (CRFREE) continues to offer 8 GiB of storage as of August 12, 2025. Using “8 GB” in marketing copy is a common shorthand, so no update is required here.
There was a problem hiding this comment.
Actionable comments posted: 1
🔭 Outside diff range comments (1)
docs/home/index.md (1)
69-86: Replace brand-sensitive claim and update storage description in docs/home/index.mdPlease apply the following changes to avoid referencing external brands and clarify the storage format:
• File: docs/home/index.md
– Lines with “Elasticsearch/OpenSearch” (≈ 73)
– Line with “Columnar storage” (≈ 81)- * The fully distributed SQL query engine, built on top of Apache Lucene, - and inheriting technologies from Elasticsearch/OpenSearch, provides performant - aggregations and advanced SQL features like JOINs and CTEs on large datasets - of semi-structured data. + * The fully distributed SQL query engine, built on Apache Lucene, + delivers fast aggregations and advanced SQL features (e.g., JOINs, CTEs) + on large semi-structured datasets. - * Columnar storage enables fast query and aggregation performance. + * Optimized on-disk data structures enable fast query and aggregation performance.If you’d like to retain an explicit “columnar” reference, please confirm that the current storage layout is indeed columnar before publishing.
🧹 Nitpick comments (5)
docs/home/index.md (5)
248-286: Connectivity section: add small caveat about JDBC auth syntaxPer prior team learning, JDBC doesn’t support user:password@ in the connection string. A brief note reduces friction for new users.
Through corresponding drivers, adapters, and client libraries, CrateDB is compatible with [ODBC], [JDBC], and other database API specifications. + + Note: Some PostgreSQL drivers (for example, JDBC) require credentials to be + supplied as connection parameters rather than using the `user:password@` URL form.
53-54: Tune two use-case bullets for clarityThese two read a bit abstract. Suggest more concrete phrasing.
-* Embedded **AI-driven insights** -* Modern **industrial data backends** +* **AI-powered features** embedded in your apps +* **Industrial IoT** data backends
353-364: Grammar polish for the Examples card textMinor readability improvement.
-A collection of clear and concise examples how to work with CrateDB. +A collection of clear, concise examples of how to work with CrateDB.
366-377: Clarify Sample Apps descriptionTighten phrasing to quickly convey value.
-Different client libraries used by canonical guestbook demo web applications. +Canonical guestbook demo applications implemented with different client libraries.
6-11: Remove unused CSS helper
.sd-hide-link-textisn’t used on this page. Consider removing to reduce noise.-<style> -/* Cards with links */ -.sd-hide-link-text { - height: 0; -} -</style>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/home/index.md(11 hunks)
🧰 Additional context used
🧠 Learnings (12)
📚 Learning: 2025-08-09T16:19:43.966Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/azure-functions/learn.rst:1-1
Timestamp: 2025-08-09T16:19:43.966Z
Learning: In the CrateDB Guide documentation, main integration anchors (e.g., `azure-functions`) are intentionally placed in the `index.md` files of their respective integration folders, while detailed tutorials use the `-learn` suffix (e.g., `azure-functions-learn`) in their `learn.rst` or `learn.md` files. This is a deliberate architectural pattern for the documentation restructuring.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-08T16:50:14.965Z
Learnt from: amotl
PR: crate/cratedb-guide#234
File: docs/home/index.md:47-50
Timestamp: 2025-08-08T16:50:14.965Z
Learning: In the CrateDB Guide docs (MyST), the correct intersphinx target for the CrateDB Cloud documentation homepage is `cloud:index` (not `cloud:docs-index` or `cloud-docs-index`). Use `:link: cloud:index` on cards/links. The `cloud` mapping is inherited via crate-docs-theme.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:08.311Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:11-11
Timestamp: 2025-08-07T23:11:08.311Z
Learning: In the CrateDB Guide repository, intersphinx mappings like "cloud" are defined within the root project `crate-docs-theme` and inherited by the documentation projects, so they don't need to be explicitly defined in individual `docs/conf.py` files.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:36.393Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.393Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T12:50:38.681Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.681Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-07T23:11:09.657Z
Learnt from: amotl
PR: crate/cratedb-guide#232
File: docs/_include/links.md:1-1
Timestamp: 2025-08-07T23:11:09.657Z
Learning: In the CrateDB Guide repository, intersphinx mappings like `crate-admin-ui` are inherited from the root project `crate-docs-theme` rather than being defined locally in `docs/conf.py`. This allows shared documentation configurations across multiple CrateDB documentation projects.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-10T17:09:32.616Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/azure-functions/index.md:31-36
Timestamp: 2025-08-10T17:09:32.616Z
Learning: In the CrateDB Guide documentation, RST files (`.rst`) use reStructuredText anchor syntax `.. _anchor-name:` while Markdown files (`.md`) use MyST syntax `(anchor-name)=`. Cross-references between MyST Markdown and reStructuredText files work correctly - a MyST `:link:` directive can reference an RST anchor and vice versa.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-10T18:17:49.380Z
Learnt from: amotl
PR: crate/cratedb-guide#241
File: docs/integrate/mysql/index.md:51-55
Timestamp: 2025-08-10T18:17:49.380Z
Learning: In the CrateDB Guide documentation, the file `docs/integrate/mysql/import-csv.rst` contains the reStructuredText label `.. _mysql-import-csv:` which can be referenced from MyST Markdown files using `:link: mysql-import-csv` with `:link-type: ref`. This is another example of cross-format referencing between MyST and RST files working correctly in Sphinx.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-09T21:40:46.154Z
Learnt from: amotl
PR: crate/cratedb-guide#238
File: docs/integrate/streamsets/index.md:18-21
Timestamp: 2025-08-09T21:40:46.154Z
Learning: In the CrateDB Guide documentation, reStructuredText files (`.rst`) use the RST label syntax `.. _label:` while MyST Markdown files (`.md`) use the syntax `(label)=`. Both formats are used throughout the repository and labels can be cross-referenced between them.
Applied to files:
docs/home/index.md
📚 Learning: 2025-05-18T13:25:11.786Z
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.786Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-09T11:03:33.178Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/ingest/etl/index.md:22-23
Timestamp: 2025-08-09T11:03:33.178Z
Learning: In the CrateDB Guide documentation, MyST Markdown files can use `{ref}` directives to reference labels defined in reStructuredText files using the RST syntax `.. _label:`. This cross-format referencing between MyST and RST is supported by Sphinx.
Applied to files:
docs/home/index.md
📚 Learning: 2025-08-05T07:14:57.416Z
Learnt from: hammerhead
PR: crate/cratedb-guide#221
File: docs/connect/configure.md:58-66
Timestamp: 2025-08-05T07:14:57.416Z
Learning: In CrateDB connection strings, the user:password@ syntax is valid for HTTP Basic authentication on port 4200, but PostgreSQL JDBC drivers do not support this format and require credentials as query parameters (?user=<user>&password=<password>) instead.
Applied to files:
docs/home/index.md
🔇 Additional comments (4)
docs/home/index.md (4)
13-20: Strong, clear hero + teaser structure reads wellThe new headline, positioning, and the two-column “Why CrateDB?” / “What Can You Build?” grid are crisp and on-message. Good use of MyST grid/cards and concise bullets.
Also applies to: 21-58
202-229: Good use of intersphinx mappings for Admin UI and Crash CLINice job using inherited mappings (
crate-admin-ui:index,crate-crash:index). This aligns with the project’s shared configuration via crate-docs-theme.Also applies to: 216-228
94-113: All CrateDB Cloud CTA details are up-to-date
- Free-tier remains “up to 8 GiB storage”
- Quick-start URL (https://cratedb.com/docs/cloud/tutorials/quick-start.html) is the recommended entry point
- Feature names “SQL Scheduler” and “Table Policies” match current product docs
No changes required.
150-152: Verified that:link: indexcorrectly targets the CrateDB Guide root
The(index)=anchor is defined at docs/index.md:1, so:link: indexwith:link-type: refresolves to the main index page as intended.
- docs/index.md:1
(index)=
2 participants
About
This patch is implementing a suggestion to add a preamble to the "Home" page of the CrateDB Guide. It includes two sections "Why CrateDB?" and "What Can You Build?".
Source: https://cratedb.gitbook.io/cratedb-docs/K3l1K4ZBSqj0AL16dbZi
Preview: https://cratedb-guide--234.org.readthedocs.build/home/
References