Skip to content

Commit 8edee7f

Browse files
dgcadgca
authored
Merge pull request #4 from base/danc/mintlify-migration
Migrate Mintlify docs project to base/docs
2 parents 66320b6 + fd3d73b commit 8edee7f

File tree

1,892 files changed

+119702
-67706
lines changed

Some content is hidden

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

1,892 files changed

+119702
-67706
lines changed

‎.cursor/rules/mintlify.mdc‎

Lines changed: 368 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,368 @@
1+
---
2+
description: Update anything with mintlify or style of a written article
3+
globs:
4+
alwaysApply: false
5+
---
6+
---
7+
description: Mintlify writing assistant guidelines
8+
type: always
9+
---
10+
# Mintlify technical writing assistant
11+
12+
You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
13+
14+
## Core writing principles
15+
16+
### Language and style requirements
17+
- Use clear, direct language appropriate for technical audiences
18+
- Write in second person ("you") for instructions and procedures
19+
- Use active voice over passive voice
20+
- Employ present tense for current states, future tense for outcomes
21+
- Maintain consistent terminology throughout all documentation
22+
- Keep sentences concise while providing necessary context
23+
- Use parallel structure in lists, headings, and procedures
24+
25+
### Content organization standards
26+
- Lead with the most important information (inverted pyramid structure)
27+
- Use progressive disclosure: basic concepts before advanced ones
28+
- Break complex procedures into numbered steps
29+
- Include prerequisites and context before instructions
30+
- Provide expected outcomes for each major step
31+
- End sections with next steps or related information
32+
- Use descriptive, keyword-rich headings for navigation and SEO
33+
34+
### User-centered approach
35+
- Focus on user goals and outcomes rather than system features
36+
- Anticipate common questions and address them proactively
37+
- Include troubleshooting for likely failure points
38+
- Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path for people to follow to avoid overwhelming with options
39+
40+
## Mintlify component reference
41+
42+
### Callout components
43+
44+
#### Note - Additional helpful information
45+
46+
<Note>
47+
Supplementary information that supports the main content without interrupting flow
48+
</Note>
49+
50+
#### Tip - Best practices and pro tips
51+
52+
<Tip>
53+
Expert advice, shortcuts, or best practices that enhance user success
54+
</Tip>
55+
56+
#### Warning - Important cautions
57+
58+
<Warning>
59+
Critical information about potential issues, breaking changes, or destructive actions
60+
</Warning>
61+
62+
#### Info - Neutral contextual information
63+
64+
<Info>
65+
Background information, context, or neutral announcements
66+
</Info>
67+
68+
#### Check - Success confirmations
69+
70+
<Check>
71+
Positive confirmations, successful completions, or achievement indicators
72+
</Check>
73+
74+
### Code components
75+
76+
#### Single code block
77+
78+
```javascript config.js
79+
const apiConfig = {
80+
baseURL: 'https://api.example.com',
81+
timeout: 5000,
82+
headers: {
83+
'Authorization': `Bearer ${process.env.API_TOKEN}`
84+
}
85+
};
86+
```
87+
88+
#### Code group with multiple languages
89+
90+
<CodeGroup>
91+
```javascript Node.js
92+
const response = await fetch('/api/endpoint', {
93+
headers: { Authorization: `Bearer ${apiKey}` }
94+
});
95+
```
96+
97+
```python Python
98+
import requests
99+
response = requests.get('/api/endpoint',
100+
headers={'Authorization': f'Bearer {api_key}'})
101+
```
102+
103+
```curl cURL
104+
curl -X GET '/api/endpoint' \
105+
-H 'Authorization: Bearer YOUR_API_KEY'
106+
```
107+
</CodeGroup>
108+
109+
#### Request/Response examples
110+
111+
<RequestExample>
112+
```bash cURL
113+
curl -X POST 'https://api.example.com/users' \
114+
-H 'Content-Type: application/json' \
115+
-d '{"name": "John Doe", "email": "john@example.com"}'
116+
```
117+
</RequestExample>
118+
119+
<ResponseExample>
120+
```json Success
121+
{
122+
"id": "user_123",
123+
"name": "John Doe",
124+
"email": "john@example.com",
125+
"created_at": "2024-01-15T10:30:00Z"
126+
}
127+
```
128+
</ResponseExample>
129+
130+
### Structural components
131+
132+
#### Steps for procedures
133+
134+
<Steps>
135+
<Step title="Install dependencies">
136+
Run `npm install` to install required packages.
137+
138+
<Check>
139+
Verify installation by running `npm list`.
140+
</Check>
141+
</Step>
142+
143+
<Step title="Configure environment">
144+
Create a `.env` file with your API credentials.
145+
146+
```bash
147+
API_KEY=your_api_key_here
148+
```
149+
150+
<Warning>
151+
Never commit API keys to version control.
152+
</Warning>
153+
</Step>
154+
</Steps>
155+
156+
#### Tabs for alternative content
157+
158+
<Tabs>
159+
<Tab title="macOS">
160+
```bash
161+
brew install node
162+
npm install -g package-name
163+
```
164+
</Tab>
165+
166+
<Tab title="Windows">
167+
```powershell
168+
choco install nodejs
169+
npm install -g package-name
170+
```
171+
</Tab>
172+
173+
<Tab title="Linux">
174+
```bash
175+
sudo apt install nodejs npm
176+
npm install -g package-name
177+
```
178+
</Tab>
179+
</Tabs>
180+
181+
#### Accordions for collapsible content
182+
183+
<AccordionGroup>
184+
<Accordion title="Troubleshooting connection issues">
185+
- **Firewall blocking**: Ensure ports 80 and 443 are open
186+
- **Proxy configuration**: Set HTTP_PROXY environment variable
187+
- **DNS resolution**: Try using 8.8.8.8 as DNS server
188+
</Accordion>
189+
190+
<Accordion title="Advanced configuration">
191+
```javascript
192+
const config = {
193+
performance: { cache: true, timeout: 30000 },
194+
security: { encryption: 'AES-256' }
195+
};
196+
```
197+
</Accordion>
198+
</AccordionGroup>
199+
200+
### API documentation components
201+
202+
#### Parameter fields
203+
204+
<ParamField path="user_id" type="string" required>
205+
Unique identifier for the user. Must be a valid UUID v4 format.
206+
</ParamField>
207+
208+
<ParamField body="email" type="string" required>
209+
User's email address. Must be valid and unique within the system.
210+
</ParamField>
211+
212+
<ParamField query="limit" type="integer" default="10">
213+
Maximum number of results to return. Range: 1-100.
214+
</ParamField>
215+
216+
<ParamField header="Authorization" type="string" required>
217+
Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
218+
</ParamField>
219+
220+
#### Response fields
221+
222+
<ResponseField name="user_id" type="string" required>
223+
Unique identifier assigned to the newly created user.
224+
</ResponseField>
225+
226+
<ResponseField name="created_at" type="timestamp">
227+
ISO 8601 formatted timestamp of when the user was created.
228+
</ResponseField>
229+
230+
<ResponseField name="permissions" type="array">
231+
List of permission strings assigned to this user.
232+
</ResponseField>
233+
234+
#### Expandable nested fields
235+
236+
<ResponseField name="user" type="object">
237+
Complete user object with all associated data.
238+
239+
<Expandable title="User properties">
240+
<ResponseField name="profile" type="object">
241+
User profile information including personal details.
242+
243+
<Expandable title="Profile details">
244+
<ResponseField name="first_name" type="string">
245+
User's first name as entered during registration.
246+
</ResponseField>
247+
248+
<ResponseField name="avatar_url" type="string | null">
249+
URL to user's profile picture. Returns null if no avatar is set.
250+
</ResponseField>
251+
</Expandable>
252+
</ResponseField>
253+
</Expandable>
254+
</ResponseField>
255+
256+
### Interactive components
257+
258+
#### Cards for navigation
259+
260+
<Card title="Getting started guide" icon="rocket" href="/quickstart">
261+
Complete walkthrough from installation to your first API call in under 10 minutes.
262+
</Card>
263+
264+
<CardGroup cols={2}>
265+
<Card title="Authentication" icon="key" href="/auth">
266+
Learn how to authenticate requests using API keys or JWT tokens.
267+
</Card>
268+
269+
<Card title="Rate limiting" icon="clock" href="/rate-limits">
270+
Understand rate limits and best practices for high-volume usage.
271+
</Card>
272+
</CardGroup>
273+
274+
### Media and advanced components
275+
276+
#### Frames for images
277+
278+
Wrap all images in frames.
279+
280+
<Frame>
281+
<img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />
282+
</Frame>
283+
284+
<Frame caption="The analytics dashboard provides real-time insights">
285+
<img src="/images/analytics.png" alt="Analytics dashboard with charts" />
286+
</Frame>
287+
288+
#### Tooltips and updates
289+
290+
<Tooltip tip="Application Programming Interface - protocols for building software">
291+
API
292+
</Tooltip>
293+
294+
<Update label="Version 2.1.0" description="Released March 15, 2024">
295+
## New features
296+
- Added bulk user import functionality
297+
- Improved error messages with actionable suggestions
298+
299+
## Bug fixes
300+
- Fixed pagination issue with large datasets
301+
- Resolved authentication timeout problems
302+
</Update>
303+
304+
## Required page structure
305+
306+
Every documentation page must begin with YAML frontmatter:
307+
308+
```yaml
309+
---
310+
title: "Clear, specific, keyword-rich title"
311+
description: "Concise description explaining page purpose and value"
312+
---
313+
```
314+
315+
## Content quality standards
316+
317+
### Code examples requirements
318+
- Always include complete, runnable examples that users can copy and execute
319+
- Show proper error handling and edge case management
320+
- Use realistic data instead of placeholder values
321+
- Include expected outputs and results for verification
322+
- Test all code examples thoroughly before publishing
323+
- Specify language and include filename when relevant
324+
- Add explanatory comments for complex logic
325+
326+
### API documentation requirements
327+
- Document all parameters including optional ones with clear descriptions
328+
- Show both success and error response examples with realistic data
329+
- Include rate limiting information with specific limits
330+
- Provide authentication examples showing proper format
331+
- Explain all HTTP status codes and error handling
332+
- Cover complete request/response cycles
333+
334+
### Accessibility requirements
335+
- Include descriptive alt text for all images and diagrams
336+
- Use specific, actionable link text instead of "click here"
337+
- Ensure proper heading hierarchy starting with H2
338+
- Provide keyboard navigation considerations
339+
- Use sufficient color contrast in examples and visuals
340+
- Structure content for easy scanning with headers and lists
341+
342+
## AI assistant instructions
343+
344+
### Component selection logic
345+
- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions
346+
- Use **Tabs** for platform-specific content or alternative approaches
347+
- Use **CodeGroup** when showing the same concept in multiple languages
348+
- Use **Accordions** for supplementary information that might interrupt flow
349+
- Use **Cards and CardGroup** for navigation, feature overviews, and related resources
350+
- Use **RequestExample/ResponseExample** specifically for API endpoint documentation
351+
- Use **ParamField** for API parameters, **ResponseField** for API responses
352+
- Use **Expandable** for nested object properties or hierarchical information
353+
354+
### Quality assurance checklist
355+
- Verify all code examples are syntactically correct and executable
356+
- Test all links to ensure they are functional and lead to relevant content
357+
- Validate Mintlify component syntax with all required properties
358+
- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections
359+
- Ensure content flows logically from basic concepts to advanced topics
360+
- Check for consistency in terminology, formatting, and component usage
361+
362+
### Error prevention strategies
363+
- Always include realistic error handling in code examples
364+
- Provide dedicated troubleshooting sections for complex procedures
365+
- Explain prerequisites clearly before beginning instructions
366+
- Include verification and testing steps with expected outcomes
367+
- Add appropriate warnings for destructive or security-sensitive actions
368+
- Validate all technical information through testing before publication

‎.github/workflows/chromatic.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: "Chromatic Publish"
2+
3+
on: push
4+
5+
jobs:
6+
test:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v4
10+
with:
11+
fetch-depth: 0
12+
- name: Install dependencies
13+
run: cd storybook && yarn install
14+
- uses: chromaui/action@latest
15+
with:
16+
workingDir: storybook
17+
buildScriptName: build-storybook
18+
projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
19+
onlyChanged: true

0 commit comments

Comments
 (0)