added initial claude #783
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| # Lint MDX Documentation | ||
|
|
||
| Check MDX files for formatting, structure, and Mintlify component usage. | ||
|
|
||
| Reference `mintlify-reference.md` for correct component syntax. | ||
|
|
||
| ## Scope | ||
|
|
||
| **By default, only check changed files:** | ||
| 1. Run `git diff --name-only HEAD` to get uncommitted changes | ||
| 2. Run `git diff --name-only master...HEAD` to include committed changes on this branch | ||
| 3. Filter to only `.mdx` files in `docs/` | ||
|
|
||
| **If `$ARGUMENTS` is provided:** | ||
| - `all` — check all MDX files in `docs/` | ||
| - A specific path — check only that file/folder (e.g., `docs/api`) | ||
|
|
||
| ## Steps | ||
|
|
||
| 1. Determine which files to check (changed files, all, or specific path) | ||
| 2. Check each file for the issues below | ||
| 3. Report issues with file path and line number | ||
| 4. Suggest fixes for each issue | ||
|
|
||
| ## Checks to perform | ||
|
|
||
| ### Frontmatter | ||
| - Every MDX file should have frontmatter with at least `title` and `description` | ||
| - Frontmatter must be valid YAML between `---` fences | ||
|
|
||
| ### Heading structure | ||
|
Contributor
There was a problem hiding this comment. It may also be good as a basic lint to include a check if no headers exist at all as header tags help SEO/LLM-SEO optimize so we should have at least one on every page, even if it is <h1 (ie, h3).
Contributor
There was a problem hiding this comment. This could also be a warning that we can choose not to enforce |
||
| - No skipped heading levels (e.g., h1 → h3) | ||
| - Only one h1 per page (or none if title is in frontmatter) | ||
|
|
||
| ### Code blocks | ||
| - All code blocks must specify a language (```javascript not just ```) | ||
| - Code inside `<CodeGroup>` blocks should have both language AND label (```javascript Node.js) | ||
|
|
||
| ### Mintlify components | ||
| Check for correct syntax on these components: | ||
|
|
||
| **Callouts** — must be self-closing or have content: | ||
| - `<Note>`, `<Tip>`, `<Warning>`, `<Info>`, `<Check>` | ||
|
|
||
| **Structural** — check for proper nesting: | ||
| - `<Steps>` must contain `<Step title="...">` children | ||
| - `<Tabs>` must contain `<Tab title="...">` children | ||
| - `<AccordionGroup>` must contain `<Accordion title="...">` children | ||
|
|
||
| **Cards** — check required attributes: | ||
| - `<Card>` should have `title` and `href` | ||
| - `<CardGroup>` should have `cols` attribute | ||
|
|
||
| **API docs** — check required attributes: | ||
| - `<ParamField>` needs `path|body|query|header`, `type`, and ideally `required` or `default` | ||
| - `<ResponseField>` needs `name` and `type` | ||
|
|
||
| **Media**: | ||
| - Images should be wrapped in `<Frame>` | ||
| - `<img>` tags should have `alt` attributes | ||
|
|
||
| ### Common mistakes to flag | ||
| - Unclosed MDX components (e.g., `<Note>` without `</Note>`) | ||
| - Using HTML comments `<!-- -->` instead of MDX `{/* */}` | ||
| - Broken internal links (files that don't exist in docs/) | ||
| - Empty code blocks | ||
| - Components with typos (e.g., `<Warnings>` instead of `<Warning>`) | ||
|
|
||
| ## Output format | ||
|
|
||
| ``` | ||
| ## Lint Results | ||
|
|
||
| ### Files checked | ||
| - 3 changed files (use `/lint all` to check entire docs/) | ||
|
|
||
| ### ❌ Errors (must fix) | ||
| - `docs/getting-started.mdx:15` — Code block missing language specifier | ||
| - `docs/api/users.mdx:42` — Unclosed <Note> component | ||
|
|
||
| ### ⚠️ Warnings (should fix) | ||
| - `docs/guides/auth.mdx:8` — Image not wrapped in <Frame> | ||
|
|
||
| ### ✅ Summary | ||
| - 3 files checked, 2 errors, 1 warning | ||
| ``` | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| # Documentation Repository | ||
|
|
||
| ## Stack | ||
| - Mintlify for documentation site | ||
| - MDX files in `docs/` folder | ||
| - Storybook for component demos | ||
|
|
||
| ## Git | ||
|
Collaborator
There was a problem hiding this comment. Is this necessary? If I'm building a new page on a branch, does claude need to know the primary branch? I dont think so. |
||
| - Primary branch: `master` | ||
|
|
||
| ## Key References | ||
| - `mintlify-reference.md` — Mintlify component syntax and usage | ||
| - `content-instructions.md` — Content guidelines | ||
| - `global-tone-voice.mdx` — Tone and voice standards | ||
| - `docs.json` — Site navigation and configuration | ||
|
|
||
| ## Conventions | ||
| - Use American English spelling | ||
| - Sentence case for headings | ||
| - All images wrapped in `<Frame>` | ||
| - Code blocks must specify a language | ||
| - Use Mintlify callouts sparingly (`<Note>`, `<Tip>`, `<Warning>`, `<Info>`, `<Check>`) | ||
|
|
||
| ## Commands | ||
| - `/lint` — Check MDX formatting and Mintlify component usage | ||
|
|
||
| ## Before Committing | ||
| - Run `/lint` and fix any errors | ||
| - If removing docs, add redirects in `docs.json` | ||
| - Ensure all internal links are valid | ||
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
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
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
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
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
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
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
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
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
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
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
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Like the direction here, but we should consider what of this could be implemented with a deterministic linter that is run by a script.
We should be able to put instructions to run the linting script in this command or we could create a Skill to do this. This will help preserve context and improve linting outcomes (in the traditional sense of linting)
Then anything that can't be done by a traditional linter could be done by the LLM