diff --git a/text.mdx b/text.mdx
index 379b83abb..231cc96a5 100644
--- a/text.mdx
+++ b/text.mdx
@@ -1,104 +1,213 @@
---
title: "Headers and text"
-description: "Text, title, and styling in standard markdown"
-icon: 'heading'
+description: "Learn how to format text, create headers, and style content"
+icon: "heading"
---
-## Titles
+## Headers
-Best used for section headers.
+Headers organize your content and create navigation anchors. They appear in the table of contents and help users scan your documentation.
+
+### Creating headers
+
+Use `#` symbols to create headers of different levels:
```mdx
-## Titles
+## Main section header
+### Subsection header
+#### Sub-subsection header
```
-### Subtitles
+
+ Use descriptive, keyword-rich headers that clearly indicate the content that follows. This improves both user navigation and search engine optimization.
+
+
+## Text formatting
+
+We support most Markdown formatting for emphasizing and styling text.
+
+### Basic formatting
+
+Apply these formatting styles to your text:
+
+| Style | Syntax | Example | Result |
+|-------|--------|---------|--------|
+| **Bold** | `**text**` | `**important note**` | **important note** |
+| *Italic* | `_text_` | `_emphasis_` | *emphasis* |
+| ~~Strikethrough~~ | `~text~` | `~deprecated feature~` | ~~deprecated feature~~ |
-Best used for subsection headers.
+### Combining formats
+
+You can combine formatting styles:
```mdx
-### Subtitles
+**_bold and italic_**
+**~~bold and strikethrough~~**
+*~~italic and strikethrough~~**
```
-
- Titles and subtitles create anchors and also show up on the table of contents on the right.
-
+**_bold and italic_**
+**~~bold and strikethrough~~**
+*~~italic and strikethrough~~*
-## Text Formatting
+### Superscript and subscript
-We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
+For mathematical expressions or footnotes, use HTML tags:
-| Style | How to write it | Result |
-| ------------- | ----------------- | --------------- |
-| Bold | `**bold**` | **bold** |
-| Italic | `_italic_` | _italic_ |
-| Strikethrough | `~strikethrough~` | ~strikethrough~ |
+| Type | Syntax | Example | Result |
+|------|--------|---------|--------|
+| Superscript | `text` | `example2` | example2 |
+| Subscript | `text` | `examplen` | examplen |
-You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
+## Links
-You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
+Links help users navigate between pages and access external resources. Use descriptive link text to improve accessibility and user experience.
-| Text Size | How to write it | Result |
-| ----------- | ------------------------ | ---------------------- |
-| Superscript | `superscript` | superscript |
-| Subscript | `subscript` | subscript |
+### Internal links
-## Linking to Pages
+Link to other pages in your documentation using root-relative paths:
+
+```mdx
+[Quickstart](/quickstart)
+[Steps](/components/steps)
+```
-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).
+[Quickstart](/quickstart)
+[Steps](/components/steps)
-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.
+
+ Avoid relative links like `[page](../page)` as they load slower and cannot be optimized as effectively as root-relative links.
+
-Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
+### External links
-You can validate broken links in your docs with [our CLI](/installation).
+For external resources, include the full URL:
+
+```mdx
+[Markdown Guide](https://www.markdownguide.org/)
+```
+
+[Markdown Guide](https://www.markdownguide.org/)
+
+### Broken links
+
+You can check for broken links in your documentation using the [CLI](/installation):
+
+```bash
+mint broken-links
+```
## Blockquotes
-### Singleline
+Blockquotes highlight important information, quotes, or examples within your content.
-To create a blockquote, add a `>` in front of a paragraph.
+### Single line blockquotes
-> Dorothy followed her through many of the beautiful rooms in her castle.
+Add `>` before text to create a blockquote:
```mdx
-> Dorothy followed her through many of the beautiful rooms in her castle.
+> This is a quote that stands out from the main content.
```
-### Multiline
+> This is a quote that stands out from the main content.
-> Dorothy followed her through many of the beautiful rooms in her castle.
->
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
+### Multi-line blockquotes
+
+For longer quotes or multiple paragraphs:
```mdx
-> Dorothy followed her through many of the beautiful rooms in her castle.
+> This is the first paragraph of a multi-line blockquote.
>
-> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
+> This is the second paragraph, separated by an empty line with `>`.
```
-### LaTeX
+> This is the first paragraph of a multi-line blockquote.
+>
+> This is the second paragraph, separated by an empty line with `>`.
+
+
+ Use blockquotes sparingly to maintain their visual impact and meaning. Consider using [callouts](/components/callouts) for notes, warnings, and other information.
+
-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)$.
+## Mathematical expressions
-Equations on their own line can be created with double dollar signs (\$\$):
+We support LaTeX for rendering mathematical expressions and equations.
-$$\exists \, x \notin [0,1]$$
+### Inline math
+
+Use single dollar signs, `$`, for inline mathematical expressions:
```mdx
-$$\exists \, x \notin [0,1]$$
+The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
```
-### Line Breaks
+The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
+
+### Block equations
-Markdown syntax also recognizes a double enter in your MDX as a linebreak.
+Use double dollar signs, `$$`, for standalone equations:
-```html
-
+```mdx
+$$
+E = mc^2
+$$
```
+$$
+E = mc^2
+$$
+
+
+ LaTeX support requires proper mathematical syntax. Refer to the [LaTeX documentation](https://www.latex-project.org/help/documentation/) for comprehensive syntax guidelines.
+
+
+## Line breaks and spacing
+
+Control spacing and line breaks to improve content readability.
+
+### Paragraph breaks
+
+Separate paragraphs with blank lines:
+
```mdx
-Paragraph 1
+This is the first paragraph.
+
+This is the second paragraph, separated by a blank line.
+```
+
+This is the first paragraph.
+
+This is the second paragraph, separated by a blank line.
-Paragraph 2
+### Manual line breaks
+
+Use HTML `
` tags for forced line breaks within paragraphs:
+
+```mdx
+This line ends here.
+This line starts on a new line.
```
+
+This line ends here.
+This line starts on a new line.
+
+
+ In most cases, paragraph breaks with blank lines provide better readability than manual line breaks.
+
+
+## Best practices
+
+### Content organization
+- Use headers to create clear content hierarchy
+- Follow proper header hierarchy (don't skip from H2 to H4)
+- Write descriptive, keyword-rich header text
+
+### Text formatting
+- Use bold for emphasis, not for entire paragraphs
+- Reserve italics for terms, titles, or subtle emphasis
+- Avoid over-formatting that distracts from content
+
+### Links
+- Write descriptive link text instead of "click here" or "read more"
+- Use root-relative paths for internal links
+- Test links regularly to prevent broken references