docs: clarify blank-line rule in admonition multi-line examples

[cotti]

Why

Closes #3131. The admonitions page claims callouts "can span multiple lines and support inline formatting," but the Plain example reproduced the exact misleading pattern that confused authors: its content reads "It can span multiple lines…" yet sits on a single line with no blank line, so it renders as one paragraph. The page also never stated the standard Markdown rule that adjacent lines collapse into one paragraph.

#3129 already corrected the Note example; this finishes the remaining gap.

What

• Added a blank line inside the Plain example (both the Output and Markdown tabs) so it actually renders as two paragraphs, mirroring the Note fix.
• Added one sentence near the top of "Basic admonitions" explaining that paragraphs inside an admonition must be separated by a blank line.

Made with Cursor

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d3717a99-d0e1-4b8b-aa26-1938ff00ebcd

📥 Commits

Reviewing files that changed from the base of the PR and between 3c11ef3 and 4e82374.

📒 Files selected for processing (1)

• docs/syntax/admonitions.md

---

📝 Walkthrough

Walkthrough

This PR updates the admonitions documentation to clarify multi-line formatting support. A new tabbed "Multiple paragraphs" example is added under Basic admonitions to demonstrate handling of multi-paragraph content. The Plain admonition example is expanded by adding a sample content line ("This is a plain callout.") to both the rendered output and the corresponding Markdown code block, providing concrete demonstration of multi-line text in plain admonitions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately describes the main change: clarifying the blank-line rule in admonition examples through documentation updates.
Description check	✅ Passed	The PR description clearly explains the issue, the fix, and references the related issue #3131, providing sufficient context about the documentation changes.
Linked Issues check	✅ Passed	The changes directly address #3131 by adding a blank line to the Plain example and clarifying the blank-line rule for multi-line admonitions, matching the prior Note fix from #3129.
Out of Scope Changes check	✅ Passed	All changes are documentation-only and directly related to the linked issue; no out-of-scope code modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/admonition-multiline-blank-line-3131

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/syntax/admonitions.md`:
- Around line 7-8: The intro to the Admonitions doc is missing the explicit rule
that paragraphs inside an admonition must be separated by a blank line; update
the sentence immediately after "Admonitions can span multiple lines and support
inline formatting." to add a clear rule like "Separate paragraphs inside an
admonition with a blank line." so readers know to insert an empty line between
paragraphs; keep the wording concise and mirror the tone of the existing intro
so it reads as a single, authoritative rule.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3cf6a341-f7d5-431c-9a88-fa014f479f94

📥 Commits

Reviewing files that changed from the base of the PR and between 667e2ec and 3c11ef3.

📒 Files selected for processing (1)

• docs/syntax/admonitions.md