AT-draft

create/text.mdx

@@ -39,9 +39,9 @@
 The following examples show how heading text maps to a generated anchor ID:
 
 | Heading text | Generated ID |
-| :--- | :--- |
+| :-- | :-- |
 | `Getting started` | `getting-started` |
 | `Config.json options` | `config-json-options` |
 | `What's new` | `what’s-new` |
 | `Rate limits (per minute)` | `rate-limits-per-minute` |
 | `Read/write access` | `read/write-access` |
@@ -98,9 +98,9 @@
 Apply these formatting styles to your text:
 
 | Style | Syntax | Example | Result |
-|-------|--------|---------|--------|
+| --- | --- | --- | --- |
 | **Bold** | `**text**` | `**important note**` | **important note** |
-| *Italic* | `_text_` | `_emphasis_` | *emphasis* |
+| _Italic_ | `_text_` | `_emphasis_` | _emphasis_ |
 | ~~Strikethrough~~ | `~text~` | `~deprecated feature~` | ~~deprecated feature~~ |
 
 ### Combine formats
@@ -113,16 +113,14 @@
 *~~italic and strikethrough~~*
 ```
 
-**_bold and italic_**<br />
-**~~bold and strikethrough~~**<br />
-*~~italic and strikethrough~~*
+**_bold and italic_**<br /> **~~bold and strikethrough~~**<br /> _~~italic and strikethrough~~_
 
 ### Superscript and subscript
 
 For mathematical expressions or footnotes, use HTML tags:
 
 | Type | Syntax | Example | Result |
-|------|--------|---------|--------|
+| --- | --- | --- | --- |
 | Superscript | `<sup>text</sup>` | `example<sup>2</sup>` | example<sup>2</sup> |
 | Subscript | `<sub>text</sub>` | `example<sub>n</sub>` | example<sub>n</sub> |
 
@@ -139,9 +137,7 @@
 [Steps](/components/steps)
 ```
 
-[Quickstart](/quickstart)<br />
-[Steps](/components/steps)
-
+[Quickstart](/quickstart)<br /> [Steps](/components/steps)
 
 ### External links
 
@@ -202,10 +198,10 @@
 Use single dollar signs, `$`, for inline mathematical expressions:
 
 ```mdx
-The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
+The Pythagorean theorem states that $a^2 + b^2 = c^2$ in a right triangle.
 ```
 
-The Pythagorean theorem states that $(a^2 + b^2 = c^2)$ in a right triangle.
+The Pythagorean theorem states that $$a^2 + b^2 = c^2$$ in a right triangle.
 
 ### Block equations
 
@@ -252,8 +248,7 @@
 This line starts on a new line.
 ```
 
-This line ends here.<br />
-This line starts on a new line.
+This line ends here.<br /> This line starts on a new line.
 
 <Tip>
   In most cases, paragraph breaks with blank lines provide better readability than manual line breaks.
@@ -295,18 +290,18 @@
 ```
 
 <Warning>
-  HTML-style `<!-- ... -->` comments are not supported in MDX. Always use `{/* ... */}`.
+  HTML-style `{/*  ...  */}` comments are not supported in MDX. Always use `{/* ... */}`.
 </Warning>
 
 ## Escape special characters
 
 MDX treats `{` and `}` as the start and end of JSX expressions, and `<` as the start of a JSX tag. When you want these characters to render as literal text, escape them so MDX does not try to parse them.
 
 | Character | How to escape |
-| :--- | :--- |
-| `{` and `}` | Wrap the character in backticks (`` `{` ``), use the HTML entity (`&#123;` for `{`, `&#125;` for `}`), or write it inside a JSX expression as a string (`{'{'}`). |
-| `<` | Wrap in backticks (`` `<` ``), use the HTML entity `&lt;`, or write `{'<'}`. |
-| `` ` `` | Use a backslash (`` \` ``). |
+| :-- | :-- |
+| `{` and `}` | Wrap the character in backticks (`{`), use the HTML entity (`&#123;` for `{`, `&#125;` for `}`), or write it inside a JSX expression as a string (`{'{'}`). |
+| `<` | Wrap in backticks (`<`), use the HTML entity `&lt;`, or write `{'<'}`. |
+| \`\`\` | Use a backslash (\`\`\`). |
 | `\` | Use a double backslash (`\\`). |
 
 ```mdx Escape examples
@@ -317,21 +312,73 @@
 In JSX, write {'{ key: value }'} to display a literal object.
 ```
 
-Inside fenced code blocks (```` ``` ````), MDX does not parse curly braces, so you can write `{variable}` directly without escaping. Escaping is only required in regular prose and inside JSX attributes.
+Inside fenced code blocks (\`\`\`\`\`), MDX does not parse curly braces, so you can write `{variable}` directly without escaping. Escaping is only required in regular prose and inside JSX attributes.
 
 ## Best practices
 
 ### Content organization
+
 - Use headings to create clear content hierarchy
 - Follow proper heading hierarchy (don't skip from H2 to H4)
 - Write descriptive, keyword-rich heading 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
+
+## Implement your brand's style guide
+
+Consistent text formatting is one of the fastest ways to make documentation feel like an extension of your product. Use the guidance below to translate an existing brand or editorial style guide into concrete MDX conventions.
+
+### Define voice and tone
+
+Before touching formatting, agree on the voice your docs use and where tone should shift.
+
+- **Voice**: The stable personality of your writing (for example, direct, friendly, precise).
+- **Tone**: How voice adapts to context (for example, reassuring in troubleshooting, matter-of-fact in reference).
+- Document a short list of do's and don'ts with example sentences so contributors have concrete patterns to copy.
+
+### Codify formatting rules
+
+Map each style guide decision to a specific Markdown or MDX pattern so writers apply them the same way every time.
+
+| Style guide rule | MDX convention |
+| :-- | :-- |
+| Product names are never bolded | Write product names as plain text, reserve `**bold**` for UI labels |
+| UI elements use bold | `Click **Save**` |
+| File paths and code identifiers use inline code | \`\`Update \`docs.json\`\`docs.json\`\` |
+| Emphasis uses italics, not bold | `_emphasis_` for tone, `**bold**` for UI |
+| Deprecated terms are struck through | `~old term~` with a link to the replacement |
+| Keyboard shortcuts use `<kbd>` | `<kbd>Cmd</kbd> + <kbd>K</kbd>` |
+
+### Standardize headings and structure
+
+Headings carry your information architecture, so align them with your style guide's rules for capitalization, length, and hierarchy.
+
+- Pick one heading case (sentence case or title case) and use it everywhere.
+- Start with `##` (H2) on every page — the page title from [frontmatter](/organize/pages) is the H1.
+- Keep hierarchy strict: never skip from `##` to `####`.
+- Use [custom heading IDs](#custom-heading-ids) for anchors you want to keep stable across rewrites.
+
+### Standardize links, callouts, and terminology
+
+- Use descriptive link text that matches the destination page title where possible.
+- Choose one callout per intent — for example, [`<Note>`](/components/callouts) for supplementary info, `<Warning>` for destructive actions — and use them consistently.
+- Maintain a short terminology list (preferred term, alternatives to avoid, capitalization) and link to it from your contributor guide.
+
+### Enforce the guide
+
+A style guide only works if it is easy to apply and easy to check.
+
+- Add a `STYLEGUIDE.md` or contributor guide page and link to it from your repository's `README`.
+- Create reusable [snippets](/create/reusable-snippets) for recurring phrasing like product descriptions, legal disclaimers, and support links so wording stays identical across pages.
+- Configure Mintlify's [AI writing assistant](/ai/writer) with your style guide so suggestions match your voice.
+- Review pull requests against the guide, and treat style fixes as first-class documentation work.