crate · amotl · Oct 8, 2025 · Oct 7, 2025 · Oct 7, 2025 · Oct 8, 2025
diff --git a/docs/admin/clustering/logical-replication-setup.md b/docs/admin/clustering/logical-replication-setup.md
@@ -59,7 +59,7 @@ For reaching each other, they will use the special `host.docker.internal` addres
 ## Setting up a publication
 
 :::{NOTE}
-All SQL statements in this section are executed on `cluster-publishing`.
+The following SQL statements are executed on `cluster-publishing`.
 :::
 
 Before setting up the replication, we create a simple table that is going to be
@@ -95,7 +95,7 @@ With this, we are already all set on the publication side.
 ## Setting up a subscription
 
 :::{NOTE}
-All SQL statements in this section are executed on `cluster-subscribing`.
+The following SQL statements are executed on `cluster-subscribing`.
 :::
 
 A subscription needs connection information to the publishing cluster as

diff --git a/docs/connect/application.md b/docs/connect/application.md
@@ -51,7 +51,7 @@ about it, please refer to its documentation at {ref}`crate-crash:index`.
 (connect-cli)=
 ## Command-line programs
 
-This section provides a quick overview about a few CLI programs, and how to
+A quick overview about a few CLI programs, and how to
 use them for connecting to CrateDB clusters. We recommend to use crash,
 psql, http ([HTTPie]), or curl.
 

diff --git a/docs/connect/drivers.md b/docs/connect/drivers.md
@@ -4,12 +4,14 @@
 :::{include} /_include/links.md
 :::
 
-This section lists drivers and adapters for supported programming languages,
+:::{div} sd-text-muted
+Drivers and adapters for supported programming languages,
 frameworks, and environments.
+:::
 
 ## PostgreSQL
 
-The drivers listed in this section all use the [CrateDB PostgreSQL interface].
+The drivers listed here all use the [CrateDB PostgreSQL interface].
 
 ::::{sd-table}
 :widths: 2 3 5 2
@@ -220,7 +222,7 @@ For connecting to CrateDB from Python, supporting Python's async implementations
 
 ## HTTP
 
-The drivers listed in this section all use the [CrateDB HTTP interface].
+The drivers listed here all use the [CrateDB HTTP interface].
 
 ::::{sd-table}
 :widths: 2 3 5 2

diff --git a/docs/connect/general.md b/docs/connect/general.md
@@ -5,6 +5,10 @@
 :::{include} /_include/links.md
 :::
 
+:::{div} sd-text-muted
+About connection properties for CrateDB.
+:::
+
 To connect to CrateDB properly, your application or driver needs to be
 configured with corresponding connection properties. Please note that different
 applications and drivers may obtain connection properties in different formats.

diff --git a/docs/connect/java.md b/docs/connect/java.md
@@ -2,6 +2,10 @@
 
 # Java
 
+:::{div} sd-text-muted
+Connect to CrateDB using JDBC.
+:::
+
 JDBC is a standard Java API that provides a common interface for accessing
 databases in Java.
 

diff --git a/docs/connect/javascript.md b/docs/connect/javascript.md
@@ -2,8 +2,9 @@
 
 # JavaScript
 
-This section provides a quick overview of available Node.js modules and
-drivers for CrateDB Cloud.
+:::{div} sd-text-muted
+Available Node.js modules and drivers for CrateDB and CrateDB Cloud.
+:::
 
 ## node-postgres
 

diff --git a/docs/connect/php.md b/docs/connect/php.md
@@ -2,8 +2,9 @@
 
 # PHP
 
-This section provides a quick overview of available PHP extensions for CrateDB
-Cloud.
+:::{div} sd-text-muted
+Available PHP extensions for CrateDB and CrateDB Cloud.
+:::
 
 ## PDO
 

diff --git a/docs/connect/python.md b/docs/connect/python.md
@@ -1,8 +1,11 @@
 (connect-python)=
 # Python
 
-This guide demonstrates how to connect to a CrateDB Cloud cluster using different
-kinds of Python drivers. Individual drivers offer specific features for specific
+:::{div} sd-text-muted
+Connect to CrateDB and CrateDB Cloud using different kinds of Python drivers.
+:::
+
+Individual drivers offer specific features for specific
 needs of your application, so consider reading this enumeration carefully.
 
 (python-drivers-official)=

diff --git a/docs/connect/ruby.md b/docs/connect/ruby.md
@@ -2,8 +2,11 @@
 
 # Ruby
 
-This section shows an example implementation of Ruby client library for CrateDB
-Cloud:
+:::{div} sd-text-muted
+How to connect to CrateDB using Ruby.
+:::
+
+An example implementation of Ruby client library for CrateDB Cloud:
 
 ```ruby
 require 'crate_ruby'

diff --git a/docs/feature/cursor/index.md b/docs/feature/cursor/index.md
@@ -21,7 +21,7 @@ and iterate it, fetching the rows progressively using
 {material-outlined}`construction;2em` This page is currently under construction.
 It includes not even the most basic essentials, and needs expansion. For example,
 the "Usage" and "Learn" sections are missing completely, and it's also not in the
-same shape like the other pages in this section.
+same shape as the other pages in this section.
 :::
 
 

diff --git a/docs/feature/search/fts/analyzer.md b/docs/feature/search/fts/analyzer.md
@@ -3,6 +3,10 @@
 
 # Analyzers, Tokenizers, and Filters
 
+:::{div} sd-text-muted
+Adjust the full-text search behaviour by using built-in and custom analyzers.
+:::
+
 CrateDB provides the capabilities to adjust the full-text search behaviour
 by using analyzers from the large array of open-source Lucene components,
 or by employing proprietary analyzers.
@@ -38,7 +42,7 @@ will become more fuzzy.
 
 :::{tip}
 CrateDB also provides a dedicated option for conducting [](#fuzzy-search),
-which is the recommended way to conduct fuzzy searches. This section
+which is the recommended way to conduct fuzzy searches. This example
 outlines how to achieve the same by using a custom analyzer.
 :::
 

diff --git a/docs/feature/storage/index.md b/docs/feature/storage/index.md
@@ -4,13 +4,16 @@
 :::{include} /_include/links.md
 :::
 
-The CrateDB storage layer is based on Lucene. By default, all fields are indexed,
+:::{div} sd-text-muted
+The CrateDB storage layer is based on Lucene.
+:::
+
+By default, all fields are indexed,
 nested or not, but the indexing can be turned off selectively.
 
-This page enumerates some concepts of Lucene, and the article [Indexing and Storage in
+This page enumerates some concepts of Lucene. The article [Indexing and Storage in
 CrateDB] goes into more details by exploring its internal workings.
 
-
 ## Lucene
 
 Lucene offers scalable and high-performance indexing which enables efficient search and
@@ -45,8 +48,8 @@ Elasticsearch are building upon the same technologies.
 
 ## Data structures
 
-This section enumerates the three main Lucene data structures that are used within
-CrateDB: Inverted indexes for text values, BKD trees for numeric values, and DocValues.
+CrateDB uses three main data structures of Lucene:
+Inverted indexes for text values, BKD trees for numeric values, and DocValues.
 
 - **Inverted index**
 
@@ -86,10 +89,6 @@ CrateDB: Inverted indexes for text values, BKD trees for numeric values, and Doc
   effective for sorting and aggregations.
 
 
-:::{todo}
-Bring page into the same shape like the others in this section.
-:::
-
 
 [column-based store]: https://cratedb.com/docs/crate/reference/en/latest/general/ddl/storage.html
 [Indexing and Storage in CrateDB]: https://cratedb.com/blog/indexing-and-storage-in-cratedb
diff --git a/docs/ingest/cdc/index.md b/docs/ingest/cdc/index.md
@@ -4,14 +4,17 @@
 :::{include} /_include/links.md
 :::
 
+:::{div} sd-text-muted
+Integrate CrateDB with CDC applications and frameworks.
+:::
+
 :::{div}
-Options to integrate CrateDB with third‑party CDC applications, typically via
-[CrateDB's PostgreSQL interface]. CrateDB also provides native adapter components
-to leverage advanced features.
+CDC applications typically use [CrateDB's PostgreSQL interface].
+CrateDB also provides native adapter components to leverage advanced features.
 
-This section lists ETL applications and frameworks that work with CrateDB, and
-outlines how to use them effectively. Additionally, see support for
-{ref}`generic ETL <etl>` solutions.
+Overview of CDC applications and frameworks that work
+with CrateDB, and how to use them effectively. Additionally, see
+support for {ref}`generic ETL <etl>` solutions.
 :::
 
 

diff --git a/docs/ingest/etl/index.md b/docs/ingest/etl/index.md
@@ -6,13 +6,16 @@
 :::{include} /_include/links.md
 :::
 
+:::{div} sd-text-muted
+Integrate CrateDB with ETL and ELT applications and frameworks.
+:::
+
 :::{div}
-Options to integrate CrateDB with third‑party ETL applications, typically via
-[CrateDB's PostgreSQL interface]. CrateDB also provides native adapter components
-to leverage advanced features.
+ETL applications typically use [CrateDB's PostgreSQL interface].
+CrateDB also provides native adapter components to leverage advanced features.
 
-This section lists ETL applications and frameworks that work with CrateDB, and
-outlines how to use them effectively. Additionally, see support for {ref}`cdc` solutions.
+Overview of ETL applications and frameworks that work with CrateDB, and
+how to use them effectively. Additionally, see support for {ref}`cdc` solutions.
 :::
 
 :::::{grid} 1 3 3 3

diff --git a/docs/ingest/index.md b/docs/ingest/index.md
@@ -1,7 +1,9 @@
 (ingest)=
 # CrateDB data ingestion
 
-All data ingestion methods for CrateDB at a glance.
+:::{div} sd-text-muted
+Data ingestion methods for CrateDB at a glance.
+:::
 
 :::::{grid} 1 2 2 2
 :margin: 4 4 0 0

diff --git a/docs/install/cloud/aws/index.rst b/docs/install/cloud/aws/index.rst
@@ -5,7 +5,7 @@ Run CrateDB on Amazon Web Services (AWS)
 Amazon Web Services (AWS) offers a wide range of cloud services, allowing to
 easily run and scale applications such as CrateDB.
 
-In this section, we explain particularities in setting up CrateDB on AWS to make the
+This section explains particularities in setting up CrateDB on AWS, to make the
 best use of its capabilities.
 
 .. rubric:: Table of contents

diff --git a/docs/install/container/index.rst b/docs/install/container/index.rst
@@ -4,6 +4,10 @@
 Container Setup
 ###############
 
+.. div:: sd-text-muted
+
+    Install CrateDB in container environments.
+
 CrateDB is ideal for containerized environments, creating and scaling a cluster
 takes minutes and your valuable data is always in sync and available.
 
@@ -44,7 +48,7 @@ official `CrateDB Docker image`_, use::
 Advanced
 ********
 
-This section demonstrates advanced container setup scenarios using Docker
+Advanced container setup scenarios using Docker
 and Kubernetes.
 
 .. toctree::

diff --git a/docs/install/container/kubernetes/kubernetes.rst b/docs/install/container/kubernetes/kubernetes.rst
@@ -4,9 +4,12 @@
 CrateDB and Kubernetes
 ======================
 
-CrateDB and `Docker`_ are a great match thanks to CrateDB’s `horizontally
-scalable`_ `shared-nothing architecture`_ that lends itself well to
-`containerization`_.
+.. div:: sd-text-muted
+
+    CrateDB and Kubernetes are a great match.
+
+CrateDB’s `horizontally scalable`_ `shared-nothing architecture` lends itself
+well to `containerization`_.
 
 `Kubernetes`_ is an open-source container orchestration system for the
 management, deployment, and scaling of containerized systems.
@@ -35,9 +38,8 @@ Managing Kubernetes
 
 Kubernetes deployments can be `managed`_ in many different ways. Which one
 makes sense for you will depend on your situation.
-
-This section shows you three basic commands you can use to create and update a
-resource.
+On Kubernetes, CrateDB is managed as a resource. The following commands
+will give you an idea of how.
 
 You can create a resource like so:
 
@@ -72,7 +74,7 @@ restart your pods with the new configuration one-by-one.
 Configuration
 =============
 
-This section provides four Kubernetes `configuration`_ snippets that can be
+A range of Kubernetes `configuration`_ snippets that can be
 used to create a three-node CrateDB cluster.
 
 

diff --git a/docs/install/index.rst b/docs/install/index.rst
@@ -4,9 +4,10 @@
 Install
 #######
 
-This section of the documentation covers the installation of CrateDB on different
-kinds of operating systems and environments, both suitable for on-premises and
-development sandbox operations.
+.. div:: sd-text-muted
+
+    Install CrateDB on different operating systems and environments,
+    for on-premises and development operations.
 
 .. toctree::
     :maxdepth: 3

diff --git a/docs/install/tarball.rst b/docs/install/tarball.rst
@@ -5,8 +5,11 @@
 Installation from Tarball Archive
 #################################
 
-This section of the documentation outlines how to use the release archives to
-install CrateDB. The walkthrough is suitable to install and run CrateDB on
+.. div:: sd-text-muted
+
+    How to use the release archives to install CrateDB.
+
+The walkthrough is suitable to install and run CrateDB on
 `Unix-like`_ systems, for example Linux and macOS.
 
 .. CAUTION::

diff --git a/docs/integrate/mcp/community.md b/docs/integrate/mcp/community.md
@@ -1,7 +1,9 @@
 # MCP Community Servers
 
-This section introduces popular community-run Model Context Protocol servers
+:::{div} sd-text-muted
+Popular community-run Model Context Protocol servers
 for PostgreSQL and CrateDB.
+:::
 
 ::::{grid} 1
 :gutter: 2

diff --git a/docs/integrate/mcp/cratedb-mcp.md b/docs/integrate/mcp/cratedb-mcp.md
@@ -1,11 +1,10 @@
 # CrateDB MCP Server
 
-:::{rubric} About
+:::{div} sd-text-muted
+The CrateDB MCP Server provides natural-language
+Text-to-SQL and documentation retrieval.
 :::
 
-The CrateDB MCP Server for natural-language Text-to-SQL and documentation
-retrieval specializes in CrateDB database clusters.
-
 The Model Context Protocol ([MCP]) is a protocol that standardizes providing
 context to language models and AI assistants.
 

diff --git a/docs/integrate/prefect/usage.md b/docs/integrate/prefect/usage.md
@@ -28,7 +28,7 @@ Now you are ready to build your first data workflows!
 
 ## Run your first ETL workflow with CrateDB
 
-This section walks you through a simple workflow that fetches data, applies a basic transformation, and loads it into CrateDB. It uses the [yellow taxi trip dataset](https://github.com/DataTalksClub/nyc-tlc-data/releases/download/yellow/yellow_tripdata_2021-01.csv.gz), which includes pickup time, geo‑coordinates, passenger count, and other fields. The goal is to write transformed data to a CrateDB table named `trip_data`:
+A simple workflow that fetches data, applies a basic transformation, and loads it into CrateDB. It uses the [yellow taxi trip dataset](https://github.com/DataTalksClub/nyc-tlc-data/releases/download/yellow/yellow_tripdata_2021-01.csv.gz), which includes pickup time, geo‑coordinates, passenger count, and other fields. The goal is to write transformed data to a CrateDB table named `trip_data`:
 
 ```python
 import pandas as pd

diff --git a/docs/performance/inserts/index.md b/docs/performance/inserts/index.md
@@ -14,9 +14,7 @@ each primary shard.
 
 You can reduce the processing overhead by either eliminating the needless
 repetition of some steps or by reducing the work needed to be done by one or
-more steps.
-
-This section of the guide will show you how.
+more steps. This guide will show you how.
 
 ```{eval-rst}
 .. rubric:: Table of contents
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,8 +2,9 @@ @@
     # PHP
-    This section provides a quick overview of available PHP extensions for CrateDB
-    Cloud.
+    :::{div} sd-text-muted
+    Available PHP extensions for CrateDB and CrateDB Cloud.
+    :::
     ## PDO
@@ Expand Down @@