Create Resources section with migration guides, comparisons, and restructured content

.claude/commands/check-links.md

@@ -0,0 +1,26 @@
+Scan the documentation for broken internal links, orphaned pages, and redirect chain issues.
+
+## Steps
+
+### 1. Broken internal links
+Search all .mdx files (excluding `snippets/`, `reference/api_v0/`, `changelog/`) for markdown links matching the pattern `](/path...)`. For each link:
+- Strip any anchor (`#...`) from the path
+- Check if a corresponding .mdx file exists at that path
+- If not, check if the path is covered by a redirect in docs.json
+- Report any links that point to neither an existing file nor a redirect
+
+### 2. Orphaned pages
+List all .mdx files under the main content directories (`getting_started/`, `learn/`, `reference/`, `resources/`, `guides/`) and check if each appears in the docs.json navigation. Exclude:
+- `snippets/` (include files, expected orphans)
+- `reference/api_v0/` (archived, in .mintignore)
+- Files that are the target of an `openapi:` directive
+- `home.mdx` (Mintlify landing page)
+
+### 3. Redirect chains
+Check the `redirects` array in docs.json for chains: where a redirect's `destination` is itself a `source` of another redirect. Report any chains found.
+
+### 4. Missing nav pages
+Check every page listed in docs.json navigation and verify the corresponding .mdx file exists on disk.
+
+## Output
+Report findings grouped by category. For broken links, show the file containing the link and the broken target path. For orphaned pages, list the file paths. Keep the output concise.

.claude/commands/check-redirects.md

@@ -0,0 +1,45 @@
+Analyze redirects using real traffic data from Fathom Analytics. Finds missing redirects (old URLs people still visit) and unused redirects (redirects nobody hits).
+
+## Prerequisites
+
+Requires `FATHOM_API_KEY` and `FATHOM_SITE_ID` in `.env` at the repo root.
+
+## Steps
+
+### 1. Run the script
+
+Run `node scripts/check-missing-redirects.mjs` and wait for it to complete. The script:
+- Fetches all `/docs/*` page views from Fathom Analytics (last 90 days)
+- Fetches the production sitemap to know all live pages (including OpenAPI-generated routes)
+- Walks local .mdx files for pages not yet deployed
+- Compares traffic against known pages + existing redirects in docs.json
+- Reports two lists: missing redirects and unused redirects
+- Filters out junk URLs (trailing dots, double /docs/, internal Mintlify props, error pages)
+- Only reports URLs with >= 10 views
+
+### 2. Review missing redirects
+
+For each missing redirect, find the best destination page:
+- Search local .mdx files and docs.json navigation for the matching topic
+- Check the production sitemap for similar paths
+- Prefer the most specific match (e.g. `/guides/laravel_scout` -> `/getting_started/frameworks/laravel`)
+- If no good match exists, redirect to the closest parent or overview page
+
+### 3. Review unused redirects
+
+These are redirects in docs.json that got zero traffic in 90 days. They are safe to remove to keep docs.json clean. Remove them from the `redirects` array.
+
+### 4. Apply changes
+
+- Add missing redirects to the `redirects` array in docs.json
+- Remove unused redirects from docs.json
+- Validate docs.json is still valid JSON
+- Re-run the script to confirm 0 missing and 0 unused
+
+## Output
+
+Report:
+- How many missing redirects were found and added (with the top 5 by traffic)
+- How many unused redirects were removed
+- Final redirect count in docs.json
+- Confirmation that the re-run shows 0/0

.claude/commands/move-page.md

@@ -0,0 +1,18 @@
+Move a documentation page from one path to another, handling all side effects.
+
+Arguments: $ARGUMENTS (format: `<old-path> <new-path>`, e.g. `resources/self_hosting/docker resources/self_hosting/getting_started/docker`)
+
+## Steps
+
+1. **Validate**: Check that the source .mdx file exists and the destination directory exists (create it if needed)
+2. **Move the file**: Use `git mv` to move the .mdx file from old path to new path
+3. **Update docs.json navigation**: Find the old path in the `pages` arrays and replace it with the new path
+4. **Add a redirect**: Add a redirect entry in the `redirects` array of docs.json mapping the old path to the new path
+5. **Fix redirect destinations**: Check if any existing redirects in docs.json have the old path as their `destination` and update them to point to the new path (prevent redirect chains)
+6. **Fix all internal links**: Search ALL .mdx files in the repo (excluding `snippets/`, `reference/api_v0/`, and `changelog/`) for links containing the old path and update them to the new path. Be careful to preserve anchors (e.g. `old-path#section` becomes `new-path#section`)
+7. **Report**: List all files modified and the total number of links updated
+
+Important:
+- Paths should NOT include the `.mdx` extension or leading `/`
+- Do NOT modify links inside the `redirects` array source fields (those are backward-compat sources)
+- Do NOT touch files in `snippets/`, `reference/api_v0/`, or `changelog/`

.claude/commands/new-capability.md

@@ -0,0 +1,37 @@
+Scaffold a new capability in the Learn tab following the standard structure.
+
+Arguments: $ARGUMENTS (the capability name, e.g. `geosearch` or `faceted_search`)
+
+## Steps
+
+1. **Create the directory**: `learn/<capability_name>/`
+
+2. **Create the pages** with proper frontmatter. Each page should have a `title` and `description` field. Create the following files:
+
+   - `overview.mdx` - What this capability is, why it matters, key features, how it works at a high level. Include a CardGroup at the bottom linking to the other pages in the group.
+   - `getting_started.mdx` - Step-by-step tutorial to use this capability for the first time. Prerequisites, minimal working example, expected results.
+   - `how_to.mdx` - Task-oriented guides for common use cases. Each section answers "How do I do X?"
+   - `advanced.mdx` - Deep-dive content: edge cases, performance tuning, architecture details, advanced configuration.
+   - `reference.mdx` - Configuration options, API parameters, settings reference specific to this capability. Link to the relevant API reference pages.
+
+3. **Add to docs.json navigation**: Add a new group in the Learn tab:
+   ```json
+   {
+     "group": "<Capability Name>",
+     "pages": [
+       "learn/<capability_name>/overview",
+       "learn/<capability_name>/getting_started",
+       "learn/<capability_name>/how_to",
+       "learn/<capability_name>/advanced",
+       "learn/<capability_name>/reference"
+     ]
+   }
+   ```
+
+4. **Ask the user** where in the Learn tab nav order this group should be placed (after which existing group).
+
+## Writing rules
+- Never use em dashes in content
+- Use Meilisearch Cloud examples first, then self-hosted alternatives
+- Include code examples with curl and at least one SDK
+- Add `<Tip>` callouts for Meilisearch Cloud when relevant

.claude/commands/new-comparison.md

@@ -0,0 +1,67 @@
+Create a new comparison page for Meilisearch vs another product.
+
+Arguments: $ARGUMENTS (the product name, e.g. `Typesense` or `Elasticsearch`)
+
+## Template
+
+Create the file at `resources/comparisons/<product_lowercase>.mdx` following this structure:
+
+```mdx
+---
+title: Meilisearch vs <Product>
+sidebarTitle: <Product>
+description: Compare Meilisearch and <Product>. Learn key differences and when to choose each.
+---
+
+<One paragraph introducing the product: what it is, when it was created, what it's built with, its primary focus.>
+
+## Quick comparison
+
+|  | Meilisearch | <Product> |
+|---|:---:|:---:|
+| **License** | MIT (CE) / BUSL-1.1 (EE) | ... |
+| **Built with** | Rust | ... |
+| **Data storage** | Disk (memory-mapped) | ... |
+| **Sharding** | Yes (Enterprise Edition) | ... |
+| **Language support** | Optimized for CJK, Arabic, Hebrew, Thai | ... |
+| **Embedding generation** | Built-in local (Candle) + any HTTP API provider | ... |
+| **Conversational search** | Yes (built-in chat) | ... |
+
+## When to choose Meilisearch
+
+<Lead with Meilisearch's strengths. Be confident but honest. Highlight: disk-based storage, Rust stability/safety, sharding, multilingual support, embedding flexibility, conversational search, MIT license, analytics dashboard, developer experience.>
+
+## What <Product> does well
+
+<Honestly acknowledge the competitor's genuine strengths. Scope them where appropriate (e.g. "for small datasets", "if you already use X ecosystem").>
+
+## When to choose <Product>
+
+Consider <Product> if:
+- <bullet points for genuine use cases where the competitor is a better fit>
+
+## Migration resources
+
+If you're considering Meilisearch:
+- [Meilisearch quick start](/getting_started/first_project)
+- [AI-powered search](/learn/ai_powered_search/getting_started_with_ai_search)
+- [Conversational search](/learn/chat/getting_started_with_chat)
+- <Add migration guide link if one exists>
+
+<Note>
+<Product> is a registered trademark of <Company>. This comparison is based on publicly available information and our own analysis.
+</Note>
+```
+
+## Steps
+
+1. Create the file from the template above
+2. Add the page to docs.json in the "Comparisons" group under the Resources tab
+3. Ask the user to fill in product-specific details or research publicly available information
+4. Never lie or invent features. If unsure about a competitor feature, ask the user.
+
+## Tone
+- Write from Meilisearch's perspective: confident, not neutral
+- Highlight Meilisearch strengths before competitor strengths
+- Be honest about competitor advantages but scope them appropriately
+- Never use em dashes

.claude/commands/update-api-ref.md

@@ -0,0 +1,41 @@
+Update the API reference documentation from the OpenAPI spec.
+
+## Steps
+
+1. **Fetch the latest OpenAPI spec** from the Meilisearch repository:
+   ```
+   npm run fetch-meilisearch-openapi-file
+   ```
+
+2. **Generate the Mintlify-compatible OpenAPI file**:
+   ```
+   npm run generate-mintlify-openapi-file
+   ```
+
+3. **Check for new routes** that need coverage:
+   ```
+   npm run check-openapi-routes-coverage
+   ```
+
+4. **Generate code sample snippets**:
+   ```
+   npm run generate-code-sample-snippets-file
+   ```
+
+5. **Check code samples**:
+   ```
+   npm run check-openapi-code-samples
+   npm run check-code-samples-usage
+   npm run check-missing-sdk-samples
+   npm run check-unused-sdk-samples
+   ```
+
+6. **Report**: Summarize what changed:
+   - New routes added (if any)
+   - Missing code samples (if any)
+   - Any errors from the scripts
+
+If new routes were added, remind the user that they may need to:
+- Add MDX stub files for new endpoints
+- Update the docs.json navigation if new route groups were created
+- Add code samples for the new endpoints

.claude/commands/update-changelog.md

@@ -0,0 +1,19 @@
+Update the changelog from GitHub releases.
+
+## Steps
+
+1. **Generate the changelog**:
+   ```
+   npm run generate-changelog
+   ```
+
+2. **Review the output**: Check for any errors or warnings from the script.
+
+3. **Verify the generated files**: Look at the changelog directory for new or updated entries. Show the user a summary of what releases were added or updated.
+
+4. **Check docs.json**: If new changelog pages were generated, verify they are included in the Changelog tab navigation in docs.json. Add any missing entries.
+
+5. **Report**: Summarize what was generated:
+   - Number of new releases added
+   - Any releases that failed to generate
+   - Whether docs.json navigation needs updating

.gitignore

@@ -136,3 +136,6 @@ yarn-error.log
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
+
+# Script output
+missing-redirects.txt

CLAUDE.md

@@ -1,5 +1,15 @@
 # Meilisearch Documentation
 
+## Documentation structure
+
+The documentation is organized into five tabs:
+
+- **Getting Started**: Where everyone starts. First steps with Meilisearch, SDK quick starts, framework integrations.
+- **Learn** (soon renamed to **Capabilities**): All Meilisearch capabilities documented. Each capability follows the structure: Overview, Getting Started, How To, Advanced, References.
+- **References**: API reference documentation for the HTTP API. Generated from the OpenAPI spec. Must be updated whenever there is a new route. See scripts in `package.json`.
+- **Resources**: Secondary references. Self-hosting, comparisons and migration guides for alternatives, under the hood internals, demos, and other resources.
+- **Changelog**: Changelog of the Engine (and soon Cloud too). Automatically generated from GitHub releases. See scripts in `package.json`.
+
 ## Writing style
 
 - **Never use em dashes (`—`)** in documentation content. Use commas, parentheses, or rewrite the sentence instead.