Refine "home" and "connect" entry point pages #237
Conversation
WalkthroughDocumentation content and navigation were reorganized and expanded across README.md, DEVELOP.md, docs/index.md, and docs/connect/index.md; setup instructions were clarified and connection-related pages were restructured into clearer categories. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
✨ 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 (
|
amotl
added
sanding-1200
amotl
force-pushed
the
refine-20250809
branch
3 times, most recently
from
6e1aaee to
51dc863
Compare
amotl
changed the title
amotl
changed the title
![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 (3)
README.md (2)
58-61: Minor grammar tweak: “order how” → “order in which”Polish the sentence for natural phrasing.
Apply this diff:
-The order of the items -enumerated below is the order how they are currently enumerated within the primary +The order of the items +enumerated below is the order in which they are currently enumerated within the primary
62-71: Avoid “[sic!]” and clarify singular folder name“Sic!” is Latin and can be jarring in user-facing docs. Prefer an explicit clarification that “topic” is intentionally singular to match folder naming.
Apply this diff:
-- `topic` A category section bundling different topics [sic!] and application domains. +- `topic` A category section bundling different topics and application domains (intentional singular folder name).docs/index.md (1)
197-201: Standardize English variant: “Analyse” → “Analyze”The page already uses “analyzing” earlier; switch to American English for consistency.
Apply this diff:
-:link-alt: Analyse information with CrateDB +:link-alt: Analyze information with CrateDB
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
DEVELOP.md(1 hunks)README.md(3 hunks)docs/connect/index.md(1 hunks)docs/index.md(6 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- DEVELOP.md
- docs/connect/index.md
🧰 Additional context used
🧠 Learnings (10)
📚 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:
README.mddocs/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:
README.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:
README.mddocs/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:
README.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:
README.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/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/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/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/index.md
📚 Learning: 2025-08-09T10:59:42.066Z
Learnt from: amotl
PR: crate/cratedb-guide#236
File: docs/connect/ide.md:2-2
Timestamp: 2025-08-09T10:59:42.066Z
Learning: In the CrateDB Guide documentation, legacy anchor labels (like `(ide)=`) should be retained alongside newer, more specific ones (like `(connect-ide)=`) to maintain backward compatibility for external projects that might reference them, even if they appear redundant within the repository.
Applied to files:
docs/index.md
🪛 LanguageTool
README.md
[style] ~67-~67: To make your text as clear as possible to all readers, do not use this foreign term. Possible alternatives are “in the original”, “thus used”, or “thus spelled”.
Context: ...gory section bundling different topics [sic!] and application domains. - use A ca...
(SIC)
docs/index.md
[uncategorized] ~200-~200: Do not mix variants of the same word (‘analyse’ and ‘analyze’) within a single text.
Context: ...ce 🔗 bi :link-type: ref :link-alt: Analyse information with CrateDB :padding: 3 :t...
(EN_WORD_COHERENCY)
⏰ 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 (11)
README.md (3)
30-30: Section rename/readability improvement looks goodRenaming “Usage” to “About” clarifies intent on first glance. No issues spotted.
47-55: General information section reads wellClear, concise overview of stack and authoring preference (Markdown forward). No changes needed.
86-86: Authoring Guide reference is helpfulGood cross-link to central guidance in crate-docs-theme. Link target looks correct.
Also applies to: 97-97
docs/index.md (8)
16-27: Card swap to prioritize Getting Started is sensibleLink and metadata look consistent. Nice UX improvement.
30-41: Installation card updates align with new orderAll parameters look correct and consistent.
89-136: Feature Highlights restructure reads wellRenamed cards and links are coherent. No issues spotted here.
138-185: Data Ingestion section addition is clear and well-scopedETL, CDC, and Telemetry grouping is logical. Looks good.
269-303: Use Cases split improves scannabilityCard links and metadata appear consistent. No changes needed.
307-320: ToC updates align with new structureIngestion entry and ordering look coherent. LGTM.
323-332: Note block is concise and actionableGood guidance for contributors on how to navigate to GitHub from docs pages.
16-41: All documentation link targets verified
Ran a comprehensive search for MyST(label)=and RST.. _label:definitions across the repo; all referenced:link:targets in docs/index.md (and the other grid-item-card sections) exist. No broken references detected.
| :::{card} Introduction | ||
| :link: all-features | ||
| :link-type: ref | ||
|
|
||
| CrateDB is a distributed and scalable SQL database for storing and analyzing | ||
| massive amounts of data in near real-time, even with complex queries. It is | ||
| based on Lucene, combines a unique set of features, and is PostgreSQL-compatible. | ||
|
|
||
|  | ||
| +++ | ||
| Read about all features of CrateDB at a glance. | ||
| ::: |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add accessible alt text and consider hosting the image locally
- The Markdown image has empty alt text, which hurts accessibility.
- Hot-linking to cratedb.com may break previews/offline builds; prefer a local asset in docs/_static if feasible.
Apply this diff to add alt text; consider replacing the URL with a local asset path maintained in the repo:
-
+I can provide a follow-up PR snippet to store and reference a local copy if desired.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| :::{card} Introduction | |
| :link: all-features | |
| :link-type: ref | |
| CrateDB is a distributed and scalable SQL database for storing and analyzing | |
| massive amounts of data in near real-time, even with complex queries. It is | |
| based on Lucene, combines a unique set of features, and is PostgreSQL-compatible. | |
|  | |
| +++ | |
| Read about all features of CrateDB at a glance. | |
| ::: | |
| :::{card} Introduction | |
| :link: all-features | |
| :link-type: ref | |
| CrateDB is a distributed and scalable SQL database for storing and analyzing | |
| massive amounts of data in near real-time, even with complex queries. It is | |
| based on Lucene, combines a unique set of features, and is PostgreSQL-compatible. | |
|  | |
| +++ | |
| Read about all features of CrateDB at a glance. | |
| ::: |
🤖 Prompt for AI Agents
In docs/index.md around lines 75 to 86, the image tag uses empty alt text and an
external hot-link; update the alt text to a meaningful, accessible description
(e.g., "CrateDB native SQL illustration") and replace the external URL with a
relative path to a local asset (place the image under docs/_static and reference
that path). Ensure the alt text is non-empty and descriptive, and if you add the
file to the repo, update any build configs so the docs builder serves
docs/_static correctly.
| The main content tree of the CrateDB Guide includes a wide array of topics. | ||
|
|
||
| If you are looking for something specific, please use the search feature on | ||
| GitHub, for example, [searching for "flink"], or clone the repository and | ||
| use a local search tool like `ripgrep` or the Silver Searcher. | ||
|
|
There was a problem hiding this comment.
Fix mismatch between “GitHub search” wording and the linked target
The sentence says “use the search feature on GitHub” but the link reference points to the docs site search. Align the target with the wording by pointing to GitHub Code Search.
Apply this diff to update the link reference:
-[searching for "flink"]: https://cratedb.com/docs/guide/search.html?q=flink
+[searching for "flink"]: https://github.com/search?q=repo%3Acrate%2Fcratedb-guide%20flink&type=codeAlso applies to: 97-97, 104-104
🤖 Prompt for AI Agents
In README.md around lines 41 to 46 (and also lines 97 and 104), the text says
“use the search feature on GitHub” but the linked URL currently points to the
docs site search; update the link target to GitHub Code Search
(https://github.com/search) so the wording and link match, and apply the same
replacement for the other occurrences at lines 97 and 104.
1 participant
About
Just a few touches and copy-editing.
Preview