Add "steppers"

[bmunkholm]

About

Convert numerous documentation pages across admin, install, integrate, feature, and start into stepper-based markup (:::::{stepper} / :::::{step}) — reorganizing headings and section wrappers into structured step blocks without changing anything else (except for spelling errors)

Like this:

There is a commit for each section of pages.

Preview

https://cratedb-guide--525.org.readthedocs.build/

The following pages has been updated:

Getting Started & Installation

• Getting Started
• Install on Windows
• Install from Tarball
• Install on Debian/Ubuntu
• Install on Red Hat
• Multi-node Setup

Integrations

• Grafana Tutorial
• Superset Usage
• Superset Sandbox
• Airflow Getting Started
• dbt Usage
• Apache Spark Usage
• Pandas Jupyter Tutorial
• Locust Tutorial
• Kafka Connect
• Node-RED MQTT Tutorial
• Debezium Tutorial
• Metabase Usage

Features

• Full-text Search Tutorial
• Document/Objects Tutorial

Administration

• Prometheus & Grafana Monitoring
• Diagnostics with System Tables
• Rolling Upgrade
• Full Restart Upgrade

[amotl]

Thank you for bringing in visual improvements, I like the appearance. However, the loss of headlines and anchors will be significant, for both users and machines (web crawlers, search indexers, others that use vector spaces / LLMs).

The typical structure of HTML and Markdown documents is well-known to them, and a proper document outline / structure made up of sensible headlines is crucial for understanding and navigational purposes. Maybe you can find a way to keep the semantic structure alive, but add the styling orthogonal to that?

[bmunkholm]

It's a great idea to have the simpler syntax! I'm not too sure that really matters in practice to loose the headings as many of them are just small steps in a tutorial. But nevertheless, I've given it a go at crate/crate-docs-theme#691 as using it is much simpler with that syntax. So this PR would also be much smaller when the new stepper is merged.

[kneth]

I like the idea of the stepper as it is more appealing visually.

The diff isn't well rendered all places, and I trust that the content is the same.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/integrate/spark/usage.md`:
- Around line 111-121: Fix the grammatical run-on in the example description: in
the sentence that mentions using a SQL query with spark.read and the
`sensor_data` example, change "You can also use a SQL query instead of a table
name you need to perform more complex data retrieval operations." to a clear
conditional form such as "You can also use a SQL query instead of a table name
if you need to perform more complex data retrieval operations." Ensure the
revised sentence references using `spark.read` with the JDBC URL/SQL query and
keeps "authentication" as corrected.

[bmunkholm]

I like the idea of the stepper as it is more appealing visually.

The diff isn't well rendered all places, and I trust that the content is the same.

@kneth All changes are now visible through the links above.

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/admin/upgrade/rolling.md (1)

124-175: Fix typos and capitalization in the new step text.

Minor doc quality issues: “omited” → “omitted”, “to to” → “to”, and “sql” → “SQL”.

📝 Proposed fix

-This step may be omited if you set the
+This step may be omitted if you set the
...
-there will not be enough nodes to to fulfill the required replicas.
+there will not be enough nodes to fulfill the required replicas.
...
-you can issue the following sql queries regularly.
+you can issue the following SQL queries regularly.

Also applies to: 184-185

docs/integrate/debezium/tutorial.md (1)

285-288: Add semicolon for SQL consistency.
Keeps the SQL examples consistent with the earlier blocks.

🔧 Suggested edit

 UPDATE erp.dbo.tbltest
 SET srcsystem = 'Updated successfully'
-WHERE id = 1
+WHERE id = 1;

🤖 Fix all issues with AI agents

In `@docs/feature/search/fts/tutorial.md`:
- Around line 42-43: Update the stepper directive to use seven colons for both
opening and closing tags: replace the opening "::::::{stepper}" with
":::::::{stepper}" and replace the closing "::::::" with ":::::::" so the
stepper matches the standard pattern used across docs (no explicit {step}
markers needed).

In `@docs/integrate/kafka/kafka-connect.md`:
- Around line 56-58: Replace the unhyphenated phrase "long term data analytics"
with the hyphenated compound adjective "long-term data analytics" in the
sentence that reads "This allows to do long term data analytics, like predicting
the weather trends for example." (search for the exact phrase "long term data
analytics" in the docs/integrate/kafka/kafka-connect.md content) to correct the
compound adjective formatting.

🧹 Nitpick comments (2)

docs/admin/upgrade/rolling.md (1)

182-182: Use a heading instead of emphasis for section title.

This should be a proper heading for structure/ToC.

♻️ Proposed fix

-**Observe the reallocation**
+### Observe the reallocation

docs/integrate/superset/sandbox.md (1)

63-63: Tighten wording.

Consider “To link the filesystem location…” for concision.