Restructure Guides navigation with numbered sections #34
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Reorganized navigation structure with numbered sections (1-whats-recce, 2-getting-started, etc.) - Created new folder structure for better organization - Added new sections like 'Downstream impacts', 'Data Diffing', 'Collaborate Validation', etc. - Restructured existing content into logical groupings - Moved old content to archived folder - Updated mkdocs.yml navigation structure See details: https://www.notion.so/infuseai/Recce-Doc-v2-25579451d357807bb104efb129028f61
doriwilson
requested changes
Sep 11, 2025
Contributor
doriwilson
left a comment
doriwilson
left a comment
There was a problem hiding this comment.
I have added two commits where I did some changes directly. However, I have left some comments about a couple different sections.
| @@ -0,0 +1,76 @@ | |||
| --- | |||
Contributor
There was a problem hiding this comment.
this page is where we need to have an embedded quickstart video that walks through these steps
Contributor
Author
There was a problem hiding this comment.
yes, we need a quick start video. Either here or create a page for it as a tutorial.
Not a blocker for this PR. Will do it later
Contributor
Author
There was a problem hiding this comment.
|
|
||
| ## Supported Diff | ||
|
|
||
| In addition to lineage diff, other types of diff also support node selection. You can find these features in the **...** button in the top right corner. Currently supported diffs include: |
Contributor
There was a problem hiding this comment.
i added an extra note here that the currently supported "node-based" diffs. Just to make it extra clear there are more.
Contributor
Author
There was a problem hiding this comment.
what is "node based" diff? by node, do you mean model? so that's model diff?
Contributor
There was a problem hiding this comment.
I meant that by selecting the node you can see the diffs of the things downstream of the node. So it's model diff but focused only on the node & it's downstream tables you selected.
| icon: octicons/diff-modified-24 | ||
| --- | ||
|
|
||
| **Breaking Change Analysis** examines modified models and categorizes changes into three types: |
Contributor
There was a problem hiding this comment.
Are we going to change the "breaking" code word? Or keep it as is for now & a later time reword it?
Contributor
Author
There was a problem hiding this comment.
We havn't have conclusion of "breaking", so keep it here.
|
|
||
| ### Basic Sharing | ||
|
|
||
| If your Recce is already connected to Recce Cloud: |
Contributor
There was a problem hiding this comment.
can they not just share the url of the Recce session they are in?
Contributor
Author
There was a problem hiding this comment.
we need to update this part. It's the OSS connect to Cloud share, not directly share in Cloud. Another issue https://linear.app/recce/issue/PLA-498/rewrite-share-to-adopt-cloud
Contributor
Author
|
@popcornylu please review (the structure only) and the @doriwilson please see the comments. |
popcornylu
requested changes
Sep 12, 2025
Contributor
popcornylu
left a comment
popcornylu
left a comment
There was a problem hiding this comment.
- Some broken images
- [NitPick] In getting started doc. See if we would like to two top-level section for dbt-core and dbt-cloud
|  | ||
|
|
||
|
|
||
| ## Start with dbt Cloud |
Contributor
There was a problem hiding this comment.
Just a nitpick
I feel the doc is too long if we include this in the doc. I we want to put all these in the same doc, i would prefer to have two top-level section
Start with dbt core
Start with dbt cloud
Current doc layout.
Contributor
Author
There was a problem hiding this comment.
we'll have 2 level of toggles, imagine
- users would see this top level toggle in navigation
2. when they click Getting Started, the 2nd level toggle like this
it will be done in https://linear.app/recce/issue/DRC-1710/update-the-navigation-ui-of-recce-docs after this PR
| ## Sharing Methods Overview | ||
|
|
||
| <figure markdown> | ||
| {: .shadow} |
Contributor
|
FYI @popcornylu @ijac13 this is a list of warnings and issues I see when running WARNING - Doc file 'index.md' contains a link '../2-getting-started/oss-vs-cloud.md', but the target is not found among documentation files.
WARNING - Doc file 'index.md' contains a link '../assets/images/1-whats-recce/lineage-readme1.png', but the target is not found among documentation files.
WARNING - Doc file 'index.md' contains a link '../assets/images/1-whats-recce/diff-readme2.png', but the target is not found among documentation files.
WARNING - Doc file 'index.md' contains a link '../assets/images/1-whats-recce/checklist-readme3.png', but the target is not found among documentation files.
INFO - Doc file '2-getting-started/installation.md' contains an unrecognized relative link './get-started-jaffle-shop/', it was left as is. Did you mean
'get-started-jaffle-shop.md'?
WARNING - Doc file '3-visualized-change/lineage.md' contains a link './node-selection.md', but the target '3-visualized-change/node-selection.md' is not found among documentation
files.
WARNING - Doc file '3-visualized-change/lineage.md' contains a link './node-selection.md', but the target '3-visualized-change/node-selection.md' is not found among documentation
files.
WARNING - Doc file '3-visualized-change/lineage.md' contains a link 'code-diff.md', but the target '3-visualized-change/code-diff.md' is not found among documentation files.
WARNING - Doc file '4-downstream-impacts/impact-radius.md' contains a link './column-level-lineage.md', but the target '4-downstream-impacts/column-level-lineage.md' is not found among
documentation files.
WARNING - Doc file '5-data-diffing/query.md' contains a link 'lineage.md#value-diff', but the target '5-data-diffing/lineage.md' is not found among documentation files.
INFO - Doc file '7-cicd/index.md' contains an absolute link '/get-started/', it was left as is.
WARNING - Doc file '7-cicd/index.md' contains a link './getting-started-recce-cloud.md', but the target '7-cicd/getting-started-recce-cloud.md' is not found among documentation files.
WARNING - Doc file '7-cicd/index.md' contains a link '../assets/images/recce-cloud/pr-checks-all-approved.png', but the target 'assets/images/recce-cloud/pr-checks-all-approved.png' is
not found among documentation files.
WARNING - Doc file '7-cicd/recce-debug.md' contains a link '../get-started.md', but the target 'get-started.md' is not found among documentation files.
WARNING - Doc file '7-cicd/recce-debug.md' contains a link '../guides/best-practices-prep-env.md', but the target 'guides/best-practices-prep-env.md' is not found among documentation
files.
WARNING - Doc file '7-cicd/recce-debug.md' contains a link './recce-run.md', but the target '7-cicd/recce-run.md' is not found among documentation files.
WARNING - Doc file '7-cicd/recce-summary.md' contains a link './recce-summary-example.md', but the target '7-cicd/recce-summary-example.md' is not found among documentation files.
WARNING - Doc file '7-cicd/recce-summary.md' contains a link '../guides/scenario-ci.md', but the target 'guides/scenario-ci.md' is not found among documentation files.
WARNING - Doc file '7-cicd/scenario-pr-review.md' contains a link '../features/state-file.md', but the target 'features/state-file.md' is not found among documentation files.
WARNING - Doc file '8-technical-concepts/state-file.md' contains a link './recce-run.md', but the target '8-technical-concepts/recce-run.md' is not found among documentation files.
INFO - Doc file 'archived/configure-diff.md' contains an unrecognized relative link './get-started-jaffle-shop/', it was left as is.
WARNING - Doc file 'archived/configure-diff.md' contains a link 'assets/images/configure-diff/environment-info.png', but the target
'archived/assets/images/configure-diff/environment-info.png' is not found among documentation files.
WARNING - Doc file 'archived/demo.md' contains a link 'features/lineage.md#value-diff', but the target 'archived/features/lineage.md' is not found among documentation files.
WARNING - Doc file 'archived/demo.md' contains a link 'assets/images/demo/clv-value-diff-fs8.png', but the target 'archived/assets/images/demo/clv-value-diff-fs8.png' is not found
among documentation files.
WARNING - Doc file 'archived/demo.md' contains a link 'features/lineage.md#profile-diff', but the target 'archived/features/lineage.md' is not found among documentation files.
WARNING - Doc file 'archived/demo.md' contains a link 'assets/images/demo/clv-profile-diff-fs8.png', but the target 'archived/assets/images/demo/clv-profile-diff-fs8.png' is not found
among documentation files.
WARNING - Doc file 'archived/demo.md' contains a link 'features/query.md', but the target 'archived/features/query.md' is not found among documentation files.
WARNING - Doc file 'archived/demo.md' contains a link 'assets/images/demo/clv-query-diff-fs8.png', but the target 'archived/assets/images/demo/clv-query-diff-fs8.png' is not found
among documentation files.
WARNING - Doc file 'archived/get-started.md' contains a link './get-started-jaffle-shop.md', but the target 'archived/get-started-jaffle-shop.md' is not found among documentation
files.
WARNING - Doc file 'archived/security.md' contains a link '../../assets/images/recce-cloud/sse-c.png', but the target '../assets/images/recce-cloud/sse-c.png' is not found among
documentation files.
WARNING - Doc file 'archived/start-with-dbt-cloud.md' contains a link 'assets/images/dbt-cloud/login-dbt-cloud.png', but the target
'archived/assets/images/dbt-cloud/login-dbt-cloud.png' is not found among documentation files.
WARNING - Doc file 'archived/start-with-dbt-cloud.md' contains a link 'assets/images/dbt-cloud/select-run-job.png', but the target 'archived/assets/images/dbt-cloud/select-run-job.png'
is not found among documentation files.
WARNING - Doc file 'archived/start-with-dbt-cloud.md' contains a link 'assets/images/dbt-cloud/prod-artifacts.png', but the target 'archived/assets/images/dbt-cloud/prod-artifacts.png'
is not found among documentation files.
WARNING - Doc file 'archived/start-with-dbt-cloud.md' contains a link 'assets/images/dbt-cloud/dev-artifacts.png', but the target 'archived/assets/images/dbt-cloud/dev-artifacts.png'
is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/expose-recce-instance-visibility.md' contains a link 'index.md#launch-the-recce-server-in-the-cloud-mode', but the target
'archived/recce-cloud/index.md' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/expose-recce-instance-visibility.md' contains a link '../assets/images/recce-cloud/ngrok-expose.png', but the target
'archived/assets/images/recce-cloud/ngrok-expose.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/expose-recce-instance-visibility.md' contains a link '../assets/images/recce-cloud/tailscale-dashboard-fs8.png', but the target
'archived/assets/images/recce-cloud/tailscale-dashboard-fs8.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/expose-recce-instance-visibility.md' contains a link '../assets/images/recce-cloud/tailscale-expose.png', but the target
'archived/assets/images/recce-cloud/tailscale-expose.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/sign-in.png', but the target
'archived/assets/images/recce-cloud/sign-in.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/sign-in-authorize.png', but the target
'archived/assets/images/recce-cloud/sign-in-authorize.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/app-install.png', but the target
'archived/assets/images/recce-cloud/app-install.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/app-install-authorize.png', but the target
'archived/assets/images/recce-cloud/app-install-authorize.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/repo-list.png', but the target
'archived/assets/images/recce-cloud/repo-list.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/github-token.png', but the target
'archived/assets/images/recce-cloud/github-token.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/query-diff.png', but the target
'archived/assets/images/recce-cloud/query-diff.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../features/state-file.md', but the target 'archived/features/state-file.md' is not found
among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/pr-checks-wo-approved.png', but the target
'archived/assets/images/recce-cloud/pr-checks-wo-approved.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/checks.png', but the target
'archived/assets/images/recce-cloud/checks.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/getting-started-recce-cloud.md' contains a link '../assets/images/recce-cloud/pr-checks-all-approved.png', but the target
'archived/assets/images/recce-cloud/pr-checks-all-approved.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-actions.md' contains a link '../assets/images/recce-cloud/setup-architecture.png', but the target
'archived/assets/images/recce-cloud/setup-architecture.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-actions.md' contains a link 'index.md#prerequisite', but the target 'archived/recce-cloud/index.md' is not found among documentation
files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-actions.md' contains a link '../features/recce-summary.md', but the target 'archived/features/recce-summary.md' is not found among
documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-actions.md' contains a link '../assets/images/recce-cloud/dbt-cloud-api-trigger.png', but the target
'archived/assets/images/recce-cloud/dbt-cloud-api-trigger.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-actions.md' contains a link '../assets/images/recce-cloud/dbt-cloud-deploy-generate-docs.png', but the target
'archived/assets/images/recce-cloud/dbt-cloud-deploy-generate-docs.png' is not found among documentation files.
INFO - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains an unrecognized relative link 'index.md/#sign-up-the-recce-cloud', it was left as is.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/recce-cloud-home.png', but the target
'archived/assets/images/recce-cloud/recce-cloud-home.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/recce-cloud-open-pr.png', but the target
'archived/assets/images/recce-cloud/recce-cloud-open-pr.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/create-in-codespace.png', but the target
'archived/assets/images/recce-cloud/create-in-codespace.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/codespaces-queued.png', but the target
'archived/assets/images/recce-cloud/codespaces-queued.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/recce-active.png', but the target
'archived/assets/images/recce-cloud/recce-active.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../features/state-file.md', but the target 'archived/features/state-file.md' is not found among
documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/check-codespace-in-github.png', but the target
'archived/assets/images/recce-cloud/check-codespace-in-github.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/open-codespace-in-browser.png', but the target
'archived/assets/images/recce-cloud/open-codespace-in-browser.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/codespace-troubleshoot-1.png', but the target
'archived/assets/images/recce-cloud/codespace-troubleshoot-1.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/codespace-troubleshoot-2.png', but the target
'archived/assets/images/recce-cloud/codespace-troubleshoot-2.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/set-prebuild-specific-regions.png', but the target
'archived/assets/images/recce-cloud/set-prebuild-specific-regions.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/branch-merged-delete-codespace.png', but the target
'archived/assets/images/recce-cloud/branch-merged-delete-codespace.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/setup-gh-codespaces.md' contains a link '../assets/images/recce-cloud/delete-codespace-in-github.png', but the target
'archived/assets/images/recce-cloud/delete-codespace-in-github.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/architecture/self-hosted.md' contains a link '../../assets/images/recce-cloud/self-hosted-architecture.png', but the target
'archived/assets/images/recce-cloud/self-hosted-architecture.png' is not found among documentation files.
WARNING - Doc file 'archived/recce-cloud/architecture/self-hosted.md' contains a link '../../assets/images/recce-cloud/self-hosted-instance-lifecycle.png', but the target
'archived/assets/images/recce-cloud/self-hosted-instance-lifecycle.png' is not found among documentation files.
INFO - Doc file '3-visualized-change/lineage.md' contains a link '#multi-nodes-selection', but there is no such anchor on this page.
INFO - Doc file '3-visualized-change/multi-models.md' contains a link './lineage.md#lineage-diff', but the doc '3-visualized-change/lineage.md' does not contain an anchor
'#lineage-diff'. |
doriwilson
approved these changes
Sep 12, 2025
Contributor
doriwilson
left a comment
doriwilson
left a comment
There was a problem hiding this comment.
lgtm for now, may do another deep dive later.
Contributor
Author
|
@gcko thanks for reminding. I fixed the mkdocs serve warnings. I didn't take care on it so I wasted time on asking Claude to check the broken images and URL 😢 . The remain warnings are all about "archived" articles. I want to keep them because some we'll rewrite. How can we keep the content that we might want to rewrite? |
Contributor
@ijac13 you can archive by adding an underscore "_" in front of a filename EDIT Because the files are under the |
Move archive files out of the docs directory Signed-off-by: Jared Scott <jared.scott@datarecce.io>
Contributor
|
After migrating 
|
Contributor
Author
|
thanks @gcko for the update. It's also ok to be merged since the URL mapping is done. I'll merge it Monday. |
ijac13
deleted the
feature/pla-488-update-doc-structure-with-existing-content
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR
Restructure highlight
See details: https://www.notion.so/infuseai/Recce-Doc-v2-25579451d357807bb104efb129028f61
Review analysis
https://www.notion.so/infuseai/Documentation-Restructure-Report-26a79451d35780a6b682d112b1de1fa2