Navigation: Dissolve cross-tree references #362

amotl · 2025-10-03T22:16:31Z

About

References pointing across the document tree have been reported to display confusing navigation behaviour.

Details

Discovered per ag "\.\.\/".

Preview

Discovered per `ag "\.\.\/"`.

coderabbitai · 2025-10-03T22:16:41Z

Walkthrough

Updated documentation navigation and content: Admin index removed the performance toctree and revised captions; Start index toctree entries adjusted and “going-further” added; new pages for ingest and search were added; query index retargets search link; modelling/fulltext link style switched to reStructuredText cross-references.

Changes

Cohort / File(s)	Summary
Admin navigation updates `docs/admin/index.md`	Removed `../performance/index` toctree entry; updated Cluster card text to omit performance-tuning phrasing; replaced performance-focused caption; expanded Software Upgrades description.
Start section toctree adjustments `docs/start/index.md`, `docs/start/query/index.md`	Replaced explicit toctree links with shorthand references (`ingest`, `search`); added `going-further`; kept `application/index`.
New ingestion page `docs/start/ingest.md`	Added ingest overview covering COPY FROM (local/HTTP/FTP/cloud), supported formats (CSV, JSON Lines), batch/incremental loads, FDW usage, integrations (e.g., ingestr), ETL workflows and use cases.
New search page `docs/start/query/search.md`	Added search overview describing native full-text (Lucene/BM25), geospatial, vector, and hybrid search via SQL; included scalability/compatibility notes and an overview card.
Link style refactor `docs/start/modelling/fulltext.md`	Converted inline links to reStructuredText cross-reference style; added reference definitions; no semantic content changes.

Sequence Diagram(s)

sequenceDiagram
  participant U as User (Docs site)
  participant R as Router
  participant P as Page Renderer

  rect rgba(100,150,255,0.08)
    U->>R: Request "start/ingest" or "start/query/search"
    R->>P: Resolve route -> new page (`ingest` / `search`)
    P-->>U: Serve new ingest/search content
  end

  rect rgba(200,230,150,0.08)
    U->>R: Request "admin/index"
    R->>P: Resolve updated admin index (performance toctree removed)
    P-->>U: Serve updated admin index
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Layout: Curated index page for "Administration" and "Performance Guides" #265 — Overlaps edits to docs/admin/index.md Cluster card toctree/captions (adds/removes performance entry).
Ingest: Add page about ingestion methods #230 — Adds/updates ingestion documentation and navigation; directly related to new ingest page.
Getting started: Rework whole section #232 — Modifies start navigation and start-section pages; related to toctree and new page additions.

Suggested labels

new content

Suggested reviewers

bmunkholm
kneth
surister

Poem

I hopped through toctrees with a twitchy ear,
Pulled in "ingest" and "search" for readers near.
I nudged a caption, moved a link with care,
Now docs bloom like carrots — tidy, bright, and fair! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title clearly and concisely summarizes the primary change by indicating that cross-tree navigation references are being removed, which aligns directly with the modifications made to toctree entries and link targets throughout the documentation. It avoids unnecessary detail and focuses on the main intent, making it easily understandable in a glance.
Description Check	✅ Passed	The description appropriately outlines the motivation for removing cross-tree references, describes how the issue was discovered, and provides preview links for verification, all of which are directly relevant to the changes in navigation and link structure within the documentation.
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 dissolve-cross-toc-refs

📜 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 1123249 and afe1325.

📒 Files selected for processing (1)

docs/start/index.md (1 hunks)

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

docs/start/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

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

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

bmunkholm · 2025-10-05T19:50:58Z

docs/start/index.md

-Ingesting data <../ingest/index>
+ingest
 application/index
+going-further


It was intentional that this was below "First Steps". It should perhaps just be moved into "First Steps" as it's basically an overview of the remaining TOC + some. Having it in the end seems very odd as that's after half the references in there.

Something more needs done, but for this iteration I prefer to keep it as it was.

It was intentional that this was below "First Steps".

You are just referring to the going-further item? If so, fixed per afe1325.

It should perhaps just be moved into "First Steps" as it's basically an overview of the remaining TOC + some. Having it in the end seems very odd as that's after half the references in there.

@coderabbitai: Please carry this over into a dedicated ticket to be discussed with @bmunkholm. Thanks.

Start/Index: Refactor "Going further" to "Learn more" on index page #368 will resolve it already.

bmunkholm · 2025-10-05T19:55:02Z

docs/start/ingest.md

+(start-ingest)=
+# Ingesting data
+
+:::{card} All data ingestion methods for CrateDB at a glance 


Should this card be moved to the bottom to basically act as "Next Step"?

Sure. Fixed with 1123249.

bmunkholm · 2025-10-05T20:04:20Z

docs/start/query/search.md

+(start-search)=
+# Search
+
+:::{card} All search features of CrateDB at a glance 


Move card down at end?

Sure. Fixed with 1123249.

amotl · 2025-10-06T17:45:50Z

docs/start/index.md

 modelling/index
 query/index
-Ingesting data <../ingest/index>
+ingest


@kneth was also complaining about this navigational hiccup today. 🍀

Navigation: Dissolve cross-toc references

f54057b

Discovered per `ag "\.\.\/"`.

amotl marked this pull request as ready for review October 3, 2025 22:16

This comment was marked as resolved.

Sign in to view

amotl added refactoring Changing shape or layout, or moving content around. cross linking Linking to different locations of the documentation. labels Oct 3, 2025

amotl requested review from bmunkholm and kneth October 3, 2025 22:24

amotl changed the title ~~Navigation: Dissolve cross-toc references~~ Navigation: Dissolve cross-tree references Oct 3, 2025

amotl requested a review from surister October 3, 2025 22:31

bmunkholm reviewed Oct 5, 2025

View reviewed changes

Navigation: Move linked cards to bottom to act as "Next step"

1123249

amotl requested a review from bmunkholm October 5, 2025 20:24

Navigation: Move going-further below first-steps

afe1325

amotl added the sanding-1200 Fine sanding. label Oct 5, 2025

amotl mentioned this pull request Oct 5, 2025

Start/Index: Refactor "Going further" to "Learn more" on index page #368

Merged

amotl commented Oct 6, 2025

View reviewed changes

amotl merged commit abf2747 into main Oct 6, 2025
3 checks passed

amotl deleted the dissolve-cross-toc-refs branch October 6, 2025 20:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Navigation: Dissolve cross-tree references #362

Navigation: Dissolve cross-tree references #362

Uh oh!

amotl commented Oct 3, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Oct 3, 2025 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

bmunkholm Oct 5, 2025

Uh oh!

bmunkholm Oct 5, 2025

Uh oh!

This comment was marked as off-topic.

Uh oh!

amotl Oct 5, 2025 •

edited

Loading

Uh oh!

amotl Oct 5, 2025

Uh oh!

bmunkholm Oct 5, 2025

Uh oh!

amotl Oct 5, 2025

Uh oh!

bmunkholm Oct 5, 2025

Uh oh!

amotl Oct 5, 2025

Uh oh!

amotl Oct 6, 2025

Uh oh!

Uh oh!

Uh oh!

Navigation: Dissolve cross-tree references #362

Navigation: Dissolve cross-tree references #362

Uh oh!

Conversation

amotl commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

About

Details

Preview

Uh oh!

coderabbitai bot commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Pre-merge checks and finishing touches

Uh oh!

This comment was marked as resolved.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as off-topic.

Uh oh!

amotl Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

amotl commented Oct 3, 2025 •

edited

Loading

coderabbitai bot commented Oct 3, 2025 •

edited

Loading

amotl Oct 5, 2025 •

edited

Loading