Move "Getting started" to the root of the TOC

[bmunkholm]

Summary of the changes / Why this is an improvement

Move Getting Started to the root of the TOC after the first Overview page.

This requires coordinated released of the theme: crate/crate-docs-theme#627, assuming this is released as 0.42.0.

Preview

See https://cratedb-guide--348.org.readthedocs.build/

The TOC looks like this at first level:

Checklist

• Link to issue this PR refers to (if applicable): Fixes #https://github.com/crate/tech-content/issues/167

[coderabbitai]

Walkthrough

This PR reorganizes documentation: cleans front matter in docs/home/index.md, replaces the verbose docs/index.md homepage with a minimal top-level toctree, adds a new handbook landing page at docs/handbook/index.md, and updates the docs theme dependency in docs/requirements.txt.

Changes

Cohort / File(s)	Summary
Docs front matter cleanup docs/home/index.md	Removed orphan: true from front matter; collapsed extra leading blank lines.
Homepage restructure docs/index.md	Replaced rich homepage content with a concise top-level toctree; added overview and handbook entries; included inline migration note for sidebar updates.
New handbook landing docs/handbook/index.md	Added handbook index with grid/card sections (Guides, Features, Ingestion, Solutions, Topics) and a toctree referencing major sections.
Docs theme bump docs/requirements.txt	Updated crate-docs-theme version constraint from >=0.40.0.dev0 to >=0.41.0.dev1.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10–15 minutes

Possibly related PRs

• Layout NG: Folder structure and naming things #236 — Also streamlines docs/index.md to a toctree-focused homepage; overlaps in top-level navigation changes.
• Getting started: Rework whole section #232 — Adjusts docs/index.md toctree entries (e.g., start/index), similar navigation restructuring.
• Ingest: Add page about ingestion methods #230 — Introduces ingest/index and updates toctree; related to this PR’s ingest entry adjustments.

Suggested labels

sanding-1200, refactoring, guidance

Suggested reviewers

• surister
• amotl
• karynzv
• kneth

Poem

I hop through docs with tidy feet,
Sweeping grids to paths so neat.
A handbook burrow, freshly spun,
A toctree trail to guide the run.
With themes bumped high and clutter low—
Thump-thump! The docs are good to go. 🐇📚

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly and accurately describes the main change of moving the “Getting Started” section to the root level of the documentation table of contents, which aligns directly with the pull request’s primary objective.
Description Check	✅ Passed	The description clearly outlines the restructuring of the TOC, notes the required theme release, provides a live preview link with screenshots, and references the related issue, all of which directly pertain to the documentation changes made in this pull request.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bm/move-getting-started-1

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5446196 and 3a0f51c.

📒 Files selected for processing (3)

• docs/handbook/index.md (1 hunks)
• docs/index.md (1 hunks)
• docs/requirements.txt (1 hunks)

✅ Files skipped from review due to trivial changes (1)

• docs/handbook/index.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/requirements.txt

🔇 Additional comments (2)

docs/index.md (2)

3-9: Helpful inline theme reminder

Appreciate the embedded pointer to the sidebartoc update—will save future friction when the top-level nav shifts again.

---

14-16: Top-level TOC update looks solid

Placing start/index alongside Overview and the new handbook entry cleanly promotes Getting Started to the root level as intended.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[bmunkholm]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/guides/index.md (1)

305-305: Drop the unused link reference.

The [Overview of CrateDB integration tutorials] definition is never referenced, triggering MD053. Please either use it or remove the definition.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 97508b8 and 99f48f2.

📒 Files selected for processing (4)

• docs/guides/index.md (1 hunks)
• docs/home/index.md (0 hunks)
• docs/index.md (1 hunks)
• docs/requirements.txt (1 hunks)

💤 Files with no reviewable changes (1)

• docs/home/index.md

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

docs/guides/index.md

131-131: Images should have alternate text (alt text)

(MD045, no-alt-text)

---

305-305: Link and image reference definitions should be needed
Unused link or image reference definition: "overview of cratedb integration tutorials"

(MD053, link-image-reference-definitions)

[amotl]

Thanks for submitting your hack to the docs theme. I am not yet convinced if the quirkyness satisfies the outcome, but let's try on behalf of a preview release.

• crate/crate-docs-theme#627 (comment)

[amotl]

Do we need to relocate this file, or can we do it differently?

[bmunkholm]

I can't see any other way. It also seems logical to me as this becomes a submenu now.

[amotl]

Understood, thanks.

[bmunkholm]

@amotl Preview now available: See https://cratedb-guide--348.org.readthedocs.build/

[amotl]

We need to relocate the previous docs/index page here, as this becomes a submenu now, and the "root" page will no longer exist.

Can you rename this to handbook, to accompany the other patch?

• Naming things: Per Diátaxis, using "Guides" is not applicable. Use "Handbook" instead. crate-docs-theme#635

[amotl]

Understood, thanks.

[amotl]

As the patch includes mostly refactoring, let's give it a try. Thanks again for going down the rabbithole on attempting to hack our Sphinx setup. Please understand I can't promise anything if this is suitable for the long term. Yet, let's integrate your patch swiftly now if it gets your job done.

[amotl]

Problem

This happens on the first hit to request a newly uploaded package when pulling it from PyPI, as if that action would hit an empty cache slot that does not automatically populate from its source in a blocking way.

ERROR: Could not find a version that satisfies the requirement crate-docs-theme>=0.41.0.dev1

-- https://app.readthedocs.org/projects/cratedb-guide/builds/29836496/
-- https://github.com/crate/cratedb-guide/actions/runs/18284854940/job/52057054285?pr=348#step:4:113

Solution

Just hit "Rebuild" or "Re-run" once.

-- https://app.readthedocs.org/projects/cratedb-guide/builds/29840753/
-- https://github.com/crate/cratedb-guide/actions/runs/18284854940/job/52079768265?pr=348

Outlook

Subsequent package pulls will no longer fail, as caches are correctly populated now.