Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cotti wants to merge 2 commits into
base: main
Choose a base branch
from
+6 −1
Open

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a2c42a
docs: show blank-line rule in admonition multi-line examples
cotti Jun 4, 2026
3c11ef3
Update docs/syntax/admonitions.md
cotti Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/syntax/admonitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ Admonitions allow you to highlight important information with varying levels of

## Basic admonitions

Admonitions can span multiple lines and support inline formatting.
Admonitions can span multiple lines and support inline formatting.

Comment on lines +7 to +8

@coderabbitai coderabbitai Bot Jun 5, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add the explicit blank-line rule to match the intended behavior

The new example is fixed, but the intro still doesn’t state the key rule: separate paragraphs inside an admonition with a blank line. Without that sentence, the original confusion from #3131 can still recur.

Suggested doc patch 
-Admonitions can span multiple lines and support inline formatting. 
+Admonitions can span multiple lines and support inline formatting.
+To create multiple paragraphs inside an admonition, separate them with a blank line.

Based on learnings: "Update /docs/ whenever Markdown syntax or rendering behaviour changes."

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Admonitions can span multiple lines and support inline formatting.
Admonitions can span multiple lines and support inline formatting.
To create multiple paragraphs inside an admonition, separate them with a blank line.
🤖 Prompt for 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.

In `@docs/syntax/admonitions.md` around lines 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.

Available admonition types include:

- [Note](#note)
Expand Down Expand Up @@ -135,6 +136,8 @@ A plain admonition is a callout with no further styling. Useful to create a call
::::{tab-item} Output

:::{admonition} This is my callout
This is a plain callout.

It can *span* multiple lines and supports inline formatting.
:::

Expand All @@ -144,6 +147,8 @@ It can *span* multiple lines and supports inline formatting.

```markdown
:::{admonition} This is my callout
This is a plain callout.

It can *span* multiple lines and supports inline formatting.
:::
```
Expand Down
Loading