fix: prevent mdx block collapsing under prettier

.github/workflows/prettier.yml

@@ -14,6 +14,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Use Node
         uses: actions/setup-node@v4
@@ -25,5 +27,10 @@ jobs:
       - name: Install deps
         run: npm ci
 
+      - name: MDX spacing check
+        run: |
+          git fetch origin "${{ github.base_ref }}" --depth=1
+          npm run lint:mdx-spacing -- --diff "origin/${{ github.base_ref }}...HEAD"
+
       - name: Prettier check
         run: npm run format:check

.husky/.gitignore

@@ -0,0 +1,3 @@
+*
+!pre-commit
+!.gitignore

.husky/pre-commit

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+
+npm run lint:mdx-spacing -- --staged

README.md

@@ -35,3 +35,8 @@ to the default branch. Find the link to install on your dashboard.
 - Mintlify dev isn't running - Run `mintlify install` it'll re-install
   dependencies.
 - Page loads as a 404 - Make sure you are running in a folder with `mint.json`
+
+### Writing Conventions
+
+- Follow `STYLE_GUIDE.md` for MDX formatting rules, especially markdown block
+  spacing inside JSX components.

STYLE_GUIDE.md

@@ -0,0 +1,54 @@
+# MDX Authoring Style Guide
+
+## Markdown Inside JSX Components
+
+When writing markdown inside `<Step>`, `<Tab>`, or `<Accordion>`, always place
+an empty line before and after block markdown content.
+
+This keeps nested content parsed as block markdown in MDX; without these blank
+lines, Prettier can flatten lists, tables, and code blocks into a single line.
+
+Block markdown content includes:
+
+- fenced code blocks
+- lists
+- tables
+- blockquotes
+- headings
+
+### Bad
+
+```mdx
+<Step title="Example">- item one - item two</Step>
+```
+
+````mdx
+<Tab title="Example">
+
+```bash
+echo hello
+```
+
+</Tab>
+````
+
+### Good
+
+```mdx
+<Step title="Example">
+
+- item one
+- item two
+
+</Step>
+```
+
+````mdx
+<Tab title="Example">
+
+```bash
+echo hello
+```
+
+</Tab>
+````

package.json

@@ -4,6 +4,7 @@
   },
   "scripts": {
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "lint:mdx-spacing": "node scripts/check-mdx-jsx-block-spacing.mjs"
   }
 }