Skip to content

Commit 98deb8a

Browse files
author
Lasim
committed
docs(README): improve formatting and clarity in documentation guidelines
1 parent 080b90a commit 98deb8a

File tree

1 file changed

+13
-1
lines changed

1 file changed

+13
-1
lines changed

README.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ mintlify dev
6161
```
6262

6363
The local server provides:
64+
6465
- Hot reloading for instant content updates
6566
- Navigation preview
6667
- Component rendering
@@ -96,6 +97,7 @@ More content here...
9697
Mintlify provides built-in components for enhanced documentation:
9798

9899
**Callouts:**
100+
99101
```mdx
100102
<Note>General information</Note>
101103
<Info>Important information</Info>
@@ -106,6 +108,7 @@ Mintlify provides built-in components for enhanced documentation:
106108
```
107109

108110
**Code Groups:**
111+
109112
```mdx
110113
<CodeGroup>
111114
`\`\`bash macOS/Linux
@@ -118,8 +121,8 @@ npm install
118121
</CodeGroup>
119122
```
120123

121-
122124
**Cards:**
125+
123126
```mdx
124127
<CardGroup cols={2}>
125128
<Card title="Getting Started" icon="rocket" href="/general/quick-start">
@@ -132,6 +135,7 @@ npm install
132135
```
133136

134137
**Steps:**
138+
135139
```mdx
136140
<Steps>
137141
<Step title="Install Dependencies">
@@ -155,26 +159,31 @@ Navigation is controlled via `docs.json`:
155159
- **Pages**: Individual documentation pages
156160

157161
To add a new page:
162+
158163
1. Create the `.mdx` file in the appropriate directory
159164
2. Add the page path to `docs.json` under the relevant group
160165
3. Test locally with `mintlify dev`
161166

162167
### Content Guidelines
163168

164169
**File Naming:**
170+
165171
- Use kebab-case: `my-new-page.mdx`
166172
- Index files represent the directory: `index.mdx`
167173

168174
**Links:**
175+
169176
- Use absolute paths from documentation root: `/development/backend/api/index`
170177
- Mintlify automatically handles `.mdx` extensions
171178

172179
**Images:**
180+
173181
- Store in `assets/images/` with logical subdirectories
174182
- Reference with absolute paths: `/assets/images/logo/dark.webp`
175183
- Optimize images before committing (compress file sizes)
176184

177185
**Frontmatter:**
186+
178187
```yaml
179188
---
180189
title: Page Title (required)
@@ -214,19 +223,22 @@ description: Page description for SEO (required)
214223
### Documentation Standards
215224

216225
**Writing Style:**
226+
217227
- Write in clear, concise language
218228
- Use active voice
219229
- Address the reader directly ("you")
220230
- Avoid jargon without explanation
221231
- Include code examples where helpful
222232

223233
**Code Examples:**
234+
224235
- Include complete, working examples
225236
- Add comments for clarity
226237
- Show expected output when relevant
227238
- Test all code before committing
228239

229240
**Structure:**
241+
230242
- Start with overview/introduction
231243
- Progress from basic to advanced
232244
- Use descriptive section headers

0 commit comments

Comments
 (0)