|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is the official **Meilisearch Documentation** repository - a content-only repository for the documentation website of Meilisearch, an open-source search engine API. The documentation is built with Mintlify, written in MDX format, and deployed on Vercel. |
| 8 | + |
| 9 | +**Important**: This is a content-only repository. Local development is NOT possible as the website code lives elsewhere. |
| 10 | + |
| 11 | +## Common Development Commands |
| 12 | + |
| 13 | +```bash |
| 14 | +# Markdown linting |
| 15 | +npm run marklint # Check markdown files for style issues |
| 16 | +npm run marklint:fix # Auto-fix markdown issues |
| 17 | + |
| 18 | +# Prose linting with Vale |
| 19 | +npm run proselint # Check prose quality and style |
| 20 | +``` |
| 21 | + |
| 22 | +## Architecture and Structure |
| 23 | + |
| 24 | +### Content Organization |
| 25 | +- `/learn/` - Learning resources and conceptual guides |
| 26 | +- `/guides/` - Implementation guides for various technologies |
| 27 | +- `/reference/` - API reference documentation |
| 28 | +- `/snippets/samples/` - Reusable code samples (included via MDX) |
| 29 | +- `/assets/` - Images and datasets organized by feature/guide |
| 30 | + |
| 31 | +### Key Configuration Files |
| 32 | +- `docs.json` - Mintlify configuration (theme, navigation, search) |
| 33 | +- `.markdownlint.jsonc` - Markdown linting rules |
| 34 | +- `.vale/` - Prose style guidelines and custom vocabulary |
| 35 | +- `docs-scraper.config.json` - Meilisearch indexing configuration with OpenAI embeddings |
| 36 | + |
| 37 | +### Documentation Features |
| 38 | +- **Search**: Self-indexed using Meilisearch with semantic search via OpenAI embeddings |
| 39 | +- **Theme**: Dark/light mode support with custom branding |
| 40 | +- **Navigation**: Hierarchical structure defined in docs.json |
| 41 | +- **Code Samples**: Modular snippets system for consistent examples across languages |
| 42 | + |
| 43 | +## Writing Guidelines |
| 44 | + |
| 45 | +### Content Format |
| 46 | +- All documentation files use **MDX** format (Markdown with JSX support) |
| 47 | +- Code samples are stored separately in `/snippets/samples/` and included via MDX |
| 48 | +- Images must use **raw GitHub URLs** (not relative paths): |
| 49 | + ```markdown |
| 50 | +  |
| 51 | + ``` |
| 52 | + |
| 53 | +### Style Rules |
| 54 | +- **Capitalization**: Sentence-style for headings (except proper nouns like AWS, Docker) |
| 55 | +- **Spelling**: British English preferred |
| 56 | +- **Grammar**: Oxford comma usage |
| 57 | +- **Bold/Italics**: Use `*` for bold, `_` for italics |
| 58 | +- **First Person**: Avoid "I", "me", "my" unless in FAQs |
| 59 | +- **Accessibility**: Write for non-native English speakers |
| 60 | + |
| 61 | +### Contributing Process |
| 62 | +1. Check existing issues before creating new ones |
| 63 | +2. PRs should solve existing issues or fix small errors |
| 64 | +3. All code samples must run without errors |
| 65 | +4. Updates may require changes to multiple related pages |
| 66 | +5. Response required within 7 days for PR feedback |
| 67 | + |
| 68 | +## Important Notes |
| 69 | + |
| 70 | +- This repository contains **only content** - no build system or local preview |
| 71 | +- Changes are reviewed for accuracy, clarity, and code functionality |
| 72 | +- The documentation philosophy emphasizes being Efficient, Accessible, Thorough, and Open source |
| 73 | +- Vale prose linting enforces consistent style and terminology |
0 commit comments