Skip to content

Commit 242a000

Browse files
ethanpalmethanpalm
committed
Merge branch 'main' into mintlify/fonts-documentation-page-1684
2 parents fd4453d + bb0204c commit 242a000

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1100
-27
lines changed

‎.claude/commands/review.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Please review the changes I'm about to commit and check:
99
3. Are any code examples accurate?
1010
4. Is the frontmatter complete and correct?
1111
5. Does the content match our existing style?
12-
6. Are there any links that need testing?
12+
6. Run vale on the files being updated and make a plan to resolve any errors, warnings, and suggestions.
13+
7. Are there any links that need testing?
1314

1415
$ARGUMENTS

‎.vale.ini‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Vale configuration for Mintlify documentation
2+
3+
StylesPath = .vale/styles
4+
MinAlertLevel = suggestion
5+
IgnoredScopes = code, tt, img, url, a
6+
SkippedScopes = script, style, pre, figure, code
7+
8+
Packages = Google
9+
10+
Vocab = Mintlify
11+
12+
# This is required since Vale doesn't officially support MDX
13+
[formats]
14+
mdx = md
15+
16+
# MDX support
17+
[*.mdx]
18+
BasedOnStyles = Vale, Google
19+
Vale.Terms = NO # Enforces really harsh capitalization rules, keep off
20+
Vale.Avoid = NO # Too aggressive about common technical terms
21+
22+
# Token and block ignores for MDX-specific syntax
23+
TokenIgnores = (?sm)((?:import|export) .+?$), \
24+
(?<!`)(<\w+ ?.+ ?\/>)(?!`), \
25+
(<[A-Z]\w+>.+?<\/[A-Z]\w+>), \
26+
(<[^>]*>)
27+
28+
BlockIgnores = (?sm)^(<\w+\n .*\s\/>)$, \
29+
(?sm)^({.+.*})
30+
31+
CommentDelimiters = {/*, */}

‎.vale/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Vale Configuration for Mintlify Docs
2+
3+
This directory contains the Vale linting configuration for Mintlify documentation.
4+
5+
## Philosophy
6+
7+
Start simple and grow incrementally as needs emerge. The current setup uses:
8+
9+
- Core Mintlify-specific vocabulary
10+
- Customized rules from the Google developer documentation style guide
11+
12+
## Vale files
13+
- `.vale.ini` - Main configuration file
14+
- `styles/config/vocabularies/Mintlify/` - Mintlify-specific terms
15+
- `styles/Google/` - Google developer documentation style rules customized for Mintlify docs
16+
17+
## When to add vocabulary
18+
- **Mintlify terms** - New components, features, platform-specific concepts
19+
- **Frequent false positives** - Any terms that repeatedly trigger spelling errors, but shouldn't
20+
21+
### Discover new vocabulary
22+
Use the included script to find vocabulary candidates:
23+
```bash
24+
# Discover terms from all files
25+
.vale/scripts/discover-vocabulary.sh
26+
27+
# Discover from specific files
28+
.vale/scripts/discover-vocabulary.sh "components/*.mdx"
29+
```
30+
31+
This script:
32+
1. Runs Vale on specified files
33+
2. Extracts spelling error suggestions
34+
3. Saves results to `.vale/vocabulary-candidates.txt`
35+
36+
## When to add new rules
37+
- **Consistent patterns** - The same style issue appears frequently
38+
- **High-value, low-noise** - Rules that catch problems with minimal false positives
39+
40+
### Testing new rules
41+
Before adding a new rule:
42+
1. Test locally: `vale path/to/file.mdx`
43+
2. Run on sample files: `vale components/*.mdx`
44+
3. Check false positive rate
45+
4. Start with `level: suggestion` then promote to `warning` or `error`

‎.vale/scripts/discover-vocabulary.sh‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#!/bin/bash
2+
# Script to discover potential vocabulary terms from Vale output
3+
# Usage: ./discover-vocabulary.sh [file-pattern]
4+
5+
set -e
6+
7+
PATTERN=${1:-"**/*.mdx"}
8+
OUTPUT_FILE=".vale/vocabulary-candidates.txt"
9+
10+
echo "🔍 Discovering vocabulary candidates from Vale spelling errors..."
11+
echo "Pattern: $PATTERN"
12+
echo ""
13+
14+
# Run Vale and extract spelling error words
15+
vale --no-exit $PATTERN 2>&1 | \
16+
grep "Vale.Spelling" | \
17+
sed -n "s/.*Did you really mean '\([^']*\)'.*/\1/p" | \
18+
sort | uniq -c | sort -nr > "$OUTPUT_FILE"
19+
20+
if [ -s "$OUTPUT_FILE" ]; then
21+
echo "Found vocabulary candidates in $OUTPUT_FILE:"
22+
echo ""
23+
head -20 "$OUTPUT_FILE"
24+
echo ""
25+
echo "Review these terms and add appropriate ones to:"
26+
echo " - .vale/styles/config/vocabularies/Mintlify/accept.txt (if valid)"
27+
echo " - .vale/styles/config/vocabularies/Mintlify/reject.txt (if misspellings)"
28+
echo ""
29+
echo "To clean up this file: rm $OUTPUT_FILE"
30+
else
31+
echo "✅ No vocabulary issues found!"
32+
rm -f "$OUTPUT_FILE"
33+
fi

‎.vale/styles/Google/AMPM.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
extends: existence
2+
message: "Use 'AM' or 'PM' (preceded by a space)."
3+
link: "https://developers.google.com/style/word-list"
4+
level: error
5+
nonword: true
6+
tokens:
7+
- '\d{1,2}[AP]M\b'
8+
- '\d{1,2} ?[ap]m\b'
9+
- '\d{1,2} ?[aApP]\.[mM]\.'

‎.vale/styles/Google/Acronyms.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
extends: conditional
2+
message: "Spell out '%s', if it's unfamiliar to the audience."
3+
link: 'https://developers.google.com/style/abbreviations'
4+
level: suggestion
5+
ignorecase: false
6+
# Ensures that the existence of 'first' implies the existence of 'second'.
7+
first: '\b([A-Z]{3,5})\b'
8+
second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
9+
# ... with the exception of these:
10+
exceptions:
11+
- API
12+
- ASP
13+
- CLI
14+
- CPU
15+
- CSS
16+
- CSV
17+
- DEBUG
18+
- DOM
19+
- DPI
20+
- FAQ
21+
- GCC
22+
- GDB
23+
- GET
24+
- GPU
25+
- GTK
26+
- GUI
27+
- HTML
28+
- HTTP
29+
- HTTPS
30+
- IDE
31+
- JAR
32+
- JSON
33+
- JSX
34+
- LESS
35+
- LLDB
36+
- NET
37+
- NOTE
38+
- NVDA
39+
- OSS
40+
- PATH
41+
- PDF
42+
- PHP
43+
- POST
44+
- RAM
45+
- REPL
46+
- RSA
47+
- SCM
48+
- SCSS
49+
- SDK
50+
- SQL
51+
- SSH
52+
- SSL
53+
- SVG
54+
- TBD
55+
- TCP
56+
- TODO
57+
- URI
58+
- URL
59+
- USB
60+
- UTF
61+
- XML
62+
- XSS
63+
- YAML
64+
- ZIP

‎.vale/styles/Google/DateFormat.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
extends: existence
2+
message: "Use 'July 31, 2016' format, not '%s'."
3+
link: 'https://developers.google.com/style/dates-times'
4+
ignorecase: true
5+
level: error
6+
nonword: true
7+
tokens:
8+
- '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
9+
- '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

‎.vale/styles/Google/Ellipses.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
extends: existence
2+
message: "In general, don't use an ellipsis."
3+
link: 'https://developers.google.com/style/ellipses'
4+
nonword: true
5+
level: warning
6+
action:
7+
name: remove
8+
tokens:
9+
- '\.\.\.'

‎.vale/styles/Google/EmDash.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
extends: existence
2+
message: "Don't put a space before or after an em dash."
3+
link: "https://developers.google.com/style/dashes"
4+
nonword: true
5+
level: error
6+
action:
7+
name: edit
8+
params:
9+
- trim
10+
- " "
11+
tokens:
12+
- '\s[—–]\s'
13+

‎.vale/styles/Google/Exclamation.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
extends: existence
2+
message: "Don't use exclamation points in text."
3+
link: "https://developers.google.com/style/exclamation-points"
4+
nonword: true
5+
level: warning
6+
action:
7+
name: edit
8+
params:
9+
- trim_right
10+
- "!"
11+
tokens:
12+
- '\w+!(?:\s|$)'

0 commit comments

Comments
 (0)