From 797c322ddb2fe1eff1e3e7b392126d63a938aa58 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 24 Jul 2026 22:57:56 +0000 Subject: [PATCH 1/3] Updated mintlify pages - Updated create/text.mdx Mintlify-Source: dashboard-editor --- create/text.mdx | 85 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 66 insertions(+), 19 deletions(-) diff --git a/create/text.mdx b/create/text.mdx index ac657ceb8..df1409e47 100644 --- a/create/text.mdx +++ b/create/text.mdx @@ -39,7 +39,7 @@ When a page has multiple headings that generate the same ID, Mintlify adds `-2`, 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` | @@ -98,9 +98,9 @@ Mintlify supports most Markdown formatting for emphasizing and styling text. 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 @@ You can combine formatting styles: *~~italic and strikethrough~~* ``` -**_bold and italic_**
-**~~bold and strikethrough~~**
-*~~italic and strikethrough~~* +**_bold and italic_**
**~~bold and strikethrough~~**
_~~italic and strikethrough~~_ ### Superscript and subscript For mathematical expressions or footnotes, use HTML tags: | Type | Syntax | Example | Result | -|------|--------|---------|--------| +| --- | --- | --- | --- | | Superscript | `text` | `example2` | example2 | | Subscript | `text` | `examplen` | examplen | @@ -139,9 +137,7 @@ Link to other pages in your documentation using root-relative paths. Omit the fi [Steps](/components/steps) ``` -[Quickstart](/quickstart)
-[Steps](/components/steps) - +[Quickstart](/quickstart)
[Steps](/components/steps) ### External links @@ -205,7 +201,7 @@ Use single dollar signs, `$`, for inline mathematical expressions: 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 ends here.
This line starts on a new line. ``` -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. @@ -295,7 +290,7 @@ Use MDX-style comments to add notes, reminders, or to-dos in your source files. ``` - HTML-style `` comments are not supported in MDX. Always use `{/* ... */}`. + HTML-style `{/* ... */}` comments are not supported in MDX. Always use `{/* ... */}`. ## Escape special characters @@ -303,10 +298,10 @@ Use MDX-style comments to add notes, reminders, or to-dos in your source files. 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 (`{` for `{`, `}` for `}`), or write it inside a JSX expression as a string (`{'{'}`). | -| `<` | Wrap in backticks (`` `<` ``), use the HTML entity `<`, or write `{'<'}`. | -| `` ` `` | Use a backslash (`` \` ``). | +| :-- | :-- | +| `{` and `}` | Wrap the character in backticks (`{`), use the HTML entity (`{` for `{`, `}` for `}`), or write it inside a JSX expression as a string (`{'{'}`). | +| `<` | Wrap in backticks (`<`), use the HTML entity `<`, or write `{'<'}`. | +| \`\`\` | Use a backslash (\`\`\`). | | `\` | Use a double backslash (`\\`). | ```mdx Escape examples @@ -317,21 +312,73 @@ The placeholder {name} renders as literal curly braces. 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`` | +| 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 `` | `Cmd + K` | + +### 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, [``](/components/callouts) for supplementary info, `` 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. \ No newline at end of file From 2c9cda07b61a8095db962f26e8b7d68022fcca63 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 24 Jul 2026 22:59:54 +0000 Subject: [PATCH 2/3] Updated mintlify pages - Updated create/text.mdx Mintlify-Source: dashboard-editor --- create/text.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/create/text.mdx b/create/text.mdx index df1409e47..f72e4e1a8 100644 --- a/create/text.mdx +++ b/create/text.mdx @@ -198,10 +198,10 @@ Mintlify supports LaTeX for rendering mathematical expressions and equations. Yo 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 @@ -354,7 +354,7 @@ Map each style guide decision to a specific Markdown or MDX pattern so writers a | :-- | :-- | | 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`` | +| 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 `` | `Cmd + K` | From 73bc05650ee7709f34525cee37c9badf0c065e88 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 25 Jul 2026 05:02:02 +0000 Subject: [PATCH 3/3] Updated mintlify pages - Updated create/text.mdx Mintlify-Source: dashboard-editor --- create/text.mdx | 87 ++++++++++++------------------------------------- 1 file changed, 20 insertions(+), 67 deletions(-) diff --git a/create/text.mdx b/create/text.mdx index f72e4e1a8..ac657ceb8 100644 --- a/create/text.mdx +++ b/create/text.mdx @@ -39,7 +39,7 @@ When a page has multiple headings that generate the same ID, Mintlify adds `-2`, 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` | @@ -98,9 +98,9 @@ Mintlify supports most Markdown formatting for emphasizing and styling text. 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,14 +113,16 @@ You can combine formatting styles: *~~italic and strikethrough~~* ``` -**_bold and italic_**
**~~bold and strikethrough~~**
_~~italic and strikethrough~~_ +**_bold and italic_**
+**~~bold and strikethrough~~**
+*~~italic and strikethrough~~* ### Superscript and subscript For mathematical expressions or footnotes, use HTML tags: | Type | Syntax | Example | Result | -| --- | --- | --- | --- | +|------|--------|---------|--------| | Superscript | `text` | `example2` | example2 | | Subscript | `text` | `examplen` | examplen | @@ -137,7 +139,9 @@ Link to other pages in your documentation using root-relative paths. Omit the fi [Steps](/components/steps) ``` -[Quickstart](/quickstart)
[Steps](/components/steps) +[Quickstart](/quickstart)
+[Steps](/components/steps) + ### External links @@ -198,10 +202,10 @@ Mintlify supports LaTeX for rendering mathematical expressions and equations. Yo 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 @@ -248,7 +252,8 @@ This line ends here.
This line starts on a new line. ``` -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. @@ -290,7 +295,7 @@ Use MDX-style comments to add notes, reminders, or to-dos in your source files. ``` - HTML-style `{/* ... */}` comments are not supported in MDX. Always use `{/* ... */}`. + HTML-style `` comments are not supported in MDX. Always use `{/* ... */}`. ## Escape special characters @@ -298,10 +303,10 @@ Use MDX-style comments to add notes, reminders, or to-dos in your source files. 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 (`{` for `{`, `}` for `}`), or write it inside a JSX expression as a string (`{'{'}`). | -| `<` | Wrap in backticks (`<`), use the HTML entity `<`, or write `{'<'}`. | -| \`\`\` | Use a backslash (\`\`\`). | +| :--- | :--- | +| `{` and `}` | Wrap the character in backticks (`` `{` ``), use the HTML entity (`{` for `{`, `}` for `}`), or write it inside a JSX expression as a string (`{'{'}`). | +| `<` | Wrap in backticks (`` `<` ``), use the HTML entity `<`, or write `{'<'}`. | +| `` ` `` | Use a backslash (`` \` ``). | | `\` | Use a double backslash (`\\`). | ```mdx Escape examples @@ -312,73 +317,21 @@ The placeholder {name} renders as literal curly braces. 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 `` | `Cmd + K` | - -### 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, [``](/components/callouts) for supplementary info, `` 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. \ No newline at end of file