Skip to content

Commit 31b4e5c

Browse files
ethanpalmethanpalm
committed
testing cursor rule
1 parent 83e9664 commit 31b4e5c

File tree

1 file changed

+170
-50
lines changed

1 file changed

+170
-50
lines changed

‎text.mdx‎

Lines changed: 170 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,224 @@
11
---
2-
title: "Headers and text"
3-
description: "Text, title, and styling in standard markdown"
2+
title: "Headers and text formatting"
3+
description: "Learn how to format text, create headers, and style content using standard markdown and MDX syntax"
44
icon: 'heading'
55
---
66

7-
## Titles
7+
## Headers and titles
88

9-
Best used for section headers.
9+
Headers organize your content and create navigation anchors. They appear in the table of contents and help users scan your documentation.
10+
11+
### Creating headers
12+
13+
Use `#` symbols to create headers of different levels:
1014

1115
```mdx
12-
## Titles
16+
## Main section header
17+
### Subsection header
18+
#### Sub-subsection header
1319
```
1420

15-
### Subtitles
21+
<Info>
22+
Headers automatically create anchor links and appear in the table of contents on the right side of your documentation.
23+
</Info>
24+
25+
<Tip>
26+
Use descriptive, keyword-rich headers that clearly indicate the content that follows. This improves both user navigation and search engine optimization.
27+
</Tip>
28+
29+
## Text formatting
30+
31+
Mintlify supports standard markdown formatting for emphasizing and styling text. You can combine multiple formatting styles for enhanced readability.
1632

17-
Best used for subsection headers.
33+
### Basic formatting
34+
35+
Use these symbols to format your text:
36+
37+
| Style | Syntax | Example | Result |
38+
|-------|--------|---------|--------|
39+
| **Bold** | `**text**` | `**important note**` | **important note** |
40+
| *Italic* | `_text_` | `_emphasis_` | *emphasis* |
41+
| ~~Strikethrough~~ | `~text~` | `~deprecated feature~` | ~~deprecated feature~~ |
42+
43+
### Combining formats
44+
45+
You can combine formatting styles for enhanced emphasis:
1846

1947
```mdx
20-
### Subtitles
48+
**_bold and italic_**
49+
**~~bold and strikethrough~~**
50+
*~~italic and strikethrough~~**
2151
```
2252

23-
<Info>
24-
Titles and subtitles create anchors and also show up on the table of contents on the right.
25-
</Info>
53+
Results in:
54+
- **_bold and italic_**
55+
- **~~bold and strikethrough~~**
56+
- *~~italic and strikethrough~~*
2657

27-
## Text Formatting
58+
### Superscript and subscript
2859

29-
We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
60+
For mathematical expressions or footnotes, use HTML tags:
3061

31-
| Style | How to write it | Result |
32-
| ------------- | ----------------- | --------------- |
33-
| Bold | `**bold**` | **bold** |
34-
| Italic | `_italic_` | _italic_ |
35-
| Strikethrough | `~strikethrough~` | ~strikethrough~ |
62+
| Type | Syntax | Example | Result |
63+
|------|--------|---------|--------|
64+
| Superscript | `<sup>text</sup>` | `<sup>2</sup>` | <sup>2</sup> |
65+
| Subscript | `<sub>text</sub>` | `<sub>n</sub>` | <sub>n</sub> |
3666

37-
You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
67+
<Note>
68+
HTML tags are required for superscript and subscript because standard markdown doesn't support these formatting options.
69+
</Note>
3870

39-
You need to use HTML to write superscript and subscript text. That is, add `<sup>` or `<sub>` around your text.
71+
## Links and navigation
4072

41-
| Text Size | How to write it | Result |
42-
| ----------- | ------------------------ | ---------------------- |
43-
| Superscript | `<sup>superscript</sup>` | <sup>superscript</sup> |
44-
| Subscript | `<sub>subscript</sub>` | <sub>subscript</sub> |
73+
Links help users navigate between pages and access external resources. Use descriptive link text to improve accessibility and user experience.
4574

46-
## Linking to Pages
75+
### Internal links
4776

48-
You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
77+
Link to other pages in your documentation using root-relative paths:
4978

50-
Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/content/text)` links to the page "Text" in our components section.
79+
```mdx
80+
[Installation guide](/installation)
81+
[API reference](/api-reference)
82+
[Getting started](/quickstart)
83+
```
84+
85+
<Warning>
86+
Avoid relative links like `[text](../text)` as they load slower and cannot be optimized as effectively as root-relative links.
87+
</Warning>
88+
89+
### External links
5190

52-
Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
91+
For external resources, include the full URL:
92+
93+
```mdx
94+
[GitHub repository](https://github.com/mintlify/docs)
95+
[Markdown guide](https://www.markdownguide.org/)
96+
```
5397

54-
You can validate broken links in your docs with [our CLI](/installation).
98+
### Link validation
99+
100+
You can validate broken links in your documentation using the CLI:
101+
102+
```bash
103+
mintlify check-links
104+
```
105+
106+
<Check>
107+
The CLI will scan your entire documentation and report any broken or inaccessible links.
108+
</Check>
55109

56110
## Blockquotes
57111

58-
### Singleline
112+
Blockquotes highlight important information, quotes, or callouts within your content.
59113

60-
To create a blockquote, add a `>` in front of a paragraph.
114+
### Single line blockquotes
61115

62-
> Dorothy followed her through many of the beautiful rooms in her castle.
116+
Add `>` before text to create a blockquote:
63117

64118
```mdx
65-
> Dorothy followed her through many of the beautiful rooms in her castle.
119+
> This is an important note that stands out from the main content.
66120
```
67121

68-
### Multiline
122+
> This is an important note that stands out from the main content.
69123
70-
> Dorothy followed her through many of the beautiful rooms in her castle.
71-
>
72-
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
124+
### Multi-line blockquotes
125+
126+
For longer quotes or multiple paragraphs:
73127

74128
```mdx
75-
> Dorothy followed her through many of the beautiful rooms in her castle.
129+
> This is the first paragraph of a multi-line blockquote.
76130
>
77-
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
131+
> This is the second paragraph, separated by an empty line with `>`.
78132
```
79133

80-
### LaTeX
134+
> This is the first paragraph of a multi-line blockquote.
135+
>
136+
> This is the second paragraph, separated by an empty line with `>`.
137+
138+
<Tip>
139+
Use blockquotes sparingly to maintain their visual impact. Reserve them for truly important information, quotes, or warnings.
140+
</Tip>
81141

82-
Mintlify supports in-line [LaTeX](https://www.latex-project.org) by surrounding your LaTeX code with dollar signs (\$). For example, `$(a^2 + b^2 = c^2)$` will render as $(a^2 + b^2 = c^2)$.
142+
## Mathematical expressions
83143

84-
Equations on their own line can be created with double dollar signs (\$\$):
144+
Mintlify supports LaTeX for rendering mathematical expressions and equations.
85145

86-
$$\exists \, x \notin [0,1]$$
146+
### Inline math
147+
148+
Use single dollar signs for inline mathematical expressions:
87149

88150
```mdx
89-
$$\exists \, x \notin [0,1]$$
151+
The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
90152
```
91153

92-
### Line Breaks
154+
The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
155+
156+
### Block equations
93157

94-
Markdown syntax also recognizes a double enter in your MDX as a linebreak.
158+
Use double dollar signs for standalone equations:
95159

96-
```html
97-
<br />
160+
```mdx
161+
$$
162+
E = mc^2
163+
$$
98164
```
99165

166+
$$
167+
E = mc^2
168+
$$
169+
170+
<Info>
171+
LaTeX support requires proper mathematical syntax. Refer to [LaTeX documentation](https://www.latex-project.org) for comprehensive syntax guidelines.
172+
</Info>
173+
174+
## Line breaks and spacing
175+
176+
Control spacing and line breaks to improve content readability.
177+
178+
### Paragraph breaks
179+
180+
Separate paragraphs with blank lines:
181+
100182
```mdx
101-
Paragraph 1
183+
This is the first paragraph.
102184

103-
Paragraph 2
185+
This is the second paragraph, separated by a blank line.
104186
```
187+
188+
### Manual line breaks
189+
190+
Use HTML `<br />` tags for forced line breaks within paragraphs:
191+
192+
```mdx
193+
This line ends here.<br />
194+
This line starts on a new line.
195+
```
196+
197+
This line ends here.<br />
198+
This line starts on a new line.
199+
200+
<Note>
201+
In most cases, natural paragraph breaks with blank lines provide better readability than manual line breaks.
202+
</Note>
203+
204+
## Best practices
205+
206+
### Content organization
207+
- Use headers to create clear content hierarchy
208+
- Keep header levels logical (don't skip from H2 to H4)
209+
- Write descriptive, keyword-rich header text
210+
211+
### Text formatting
212+
- Use bold for emphasis, not for entire paragraphs
213+
- Reserve italics for terms, titles, or subtle emphasis
214+
- Avoid over-formatting that distracts from content
215+
216+
### Links and navigation
217+
- Write descriptive link text instead of "click here"
218+
- Validate links regularly to maintain documentation quality
219+
- Use root-relative paths for internal links
220+
221+
### Accessibility
222+
- Ensure sufficient color contrast for all text
223+
- Use semantic formatting (headers for structure, not styling)
224+
- Provide alternative text for any embedded content

0 commit comments

Comments
 (0)