Add Mintlify preview site

cockroachlabs-preview-main/.github/workflows/merge-navigation.yml

@@ -0,0 +1,31 @@
+name: Merge navigation into docs.json
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - "navigation/**"
+      - "docs.base.json"
+      - "redirects.json"
+      - "scripts/merge_navigation.py"
+
+jobs:
+  merge:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run merge_navigation.py
+        run: python3 scripts/merge_navigation.py
+
+      - name: Commit updated docs.json
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs.json
+          git diff --cached --quiet || git commit -m "chore: rebuild docs.json from navigation files"
+          git push

cockroachlabs-preview-main/.gitignore

@@ -0,0 +1,10 @@
+*py
+.venv
+_migration
+scripts/
+
+config.json
+urls.json
+url_list_part3_online.md
+url_list_tabs.md
+versioned_pages_to_review.md

cockroachlabs-preview-main/.mintignore

@@ -0,0 +1,6 @@
+scripts/
+*py
+.venv
+docs-backup/*
+
+VERSION_PLACEHOLDER_LINKS.md

cockroachlabs-preview-main/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mintlify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cockroachlabs-preview-main/README.md

@@ -0,0 +1,43 @@
+# Mintlify Starter Kit
+
+Use the starter kit to get your docs deployed and ready to customize.
+
+Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
+
+- Guide pages
+- Navigation
+- Customizations
+- API reference pages
+- Use of popular components
+
+**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
+
+## Development
+
+Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
+
+```
+npm i -g mint
+```
+
+Run the following command at the root of your documentation, where your `docs.json` is located:
+
+```
+mint dev
+```
+
+View your local preview at `http://localhost:3000`.
+
+## Publishing changes
+
+Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
+
+## Need help?
+
+### Troubleshooting
+
+- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
+- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+
+### Resources
+- [Mintlify documentation](https://mintlify.com/docs)

cockroachlabs-preview-main/VERSION_PLACEHOLDER_LINKS.md

@@ -0,0 +1,85 @@
+# How `VERSION_PLACEHOLDER` Links Work
+
+This repository uses shared MDX snippets across multiple versioned docs pages. Some of those snippets need internal docs links that point to the correct docs version for the page that imports them.
+
+To support that, shared snippets use links like:
+
+```html
+<a href="/docs/VERSION_PLACEHOLDER/cockroachcloud/authorization" data-versioned="true">Authorization</a>
+```
+
+## Why this was created
+
+A snippet under `snippets/` can be imported into many different pages, such as:
+
+- `docs/stable/...`
+- `docs/v25.3/...`
+- `docs/v24.3/...`
+
+If the snippet hardcoded one version like `/docs/stable/...`, that same snippet would be wrong when rendered inside `v25.3` or `v24.3` docs pages.
+
+`VERSION_PLACEHOLDER` keeps the snippet version-agnostic until the page renders.
+
+## How the replacement happens
+
+Each versioned page that imports one of these snippets defines a `PatchVersion` component. For example, `docs/stable/cockroachcloud/alerts-page.mdx` contains:
+
+```jsx
+export const PatchVersion = () => {
+  if (typeof document !== "undefined") {
+    requestAnimationFrame(() => {
+      document.querySelectorAll("[data-versioned]").forEach((a) => {
+        a.href = a.href.replace("VERSION_PLACEHOLDER", "stable");
+      });
+    });
+  }
+  return null;
+};
+```
+
+That page then renders:
+
+```jsx
+<PatchVersion />
+<AlertsPage />
+```
+
+When the page loads in the browser, `PatchVersion`:
+
+1. Finds all elements marked with `data-versioned`.
+2. Reads each link's `href`.
+3. Replaces `VERSION_PLACEHOLDER` with the current page's version string, such as `stable` or `v24.3`.
+
+## Example flow
+
+Shared snippet:
+
+- `snippets/cockroachcloud/alerts-page.mdx`
+- Contains links like `/docs/VERSION_PLACEHOLDER/cockroachcloud/authorization`
+
+Versioned page:
+
+- `docs/stable/cockroachcloud/alerts-page.mdx`
+- Imports the snippet
+- Defines `PatchVersion`
+- Replaces `VERSION_PLACEHOLDER` with `stable`
+
+Equivalent pages in other version directories use the same pattern, but replace the placeholder with their own version:
+
+- `docs/v25.3/...` -> `v25.3`
+- `docs/v24.3/...` -> `v24.3`
+
+## Rules for authors
+
+- Use `VERSION_PLACEHOLDER` only for internal docs links that must resolve to the importing page's version.
+- Add `data-versioned="true"` to each link that should be rewritten.
+- Keep the snippet itself free of hardcoded version prefixes when it is intended for reuse across multiple docs versions.
+- Ensure the importing versioned page includes a `PatchVersion` component before rendering the shared snippet.
+
+## When not to use it
+
+Do not use `VERSION_PLACEHOLDER` for:
+
+- External links
+- Links that should always point to a fixed location regardless of docs version
+- Snippets that are only ever used in one versioned location and do not need cross-version reuse