prettier/prettier

Support markdown callouts/admonitions

Open

#8,640 opened on Jun 25, 2020

View on GitHub
 (3 comments) (12 reactions) (0 assignees)JavaScript (51,868 stars) (4,716 forks)batch import
help wantedlang:markdown

Description

Docusaurus has one non-standard markdown syntax extension - Callouts/admonitions. Currently this syntax doesn't play nice with Prettier, especially with proseWrap set to always.

Since it's not a part of CommonMark spec I'd understand if Prettier team wouldn't want to take an extra maintenance cost. But given that Docusaurus is quite popular (it's used by Prettier itself), this syntax doesn't seem to be conflicting with anything else, and it has a remark plugin, I thought opening this issue might worth a shot.

Prettier 2.0.5 Playground link

--parser markdown
--prose-wrap always

Input:

:::note
Some note
:::

:::note

Some note
:::

:::note
Some note

:::

::: note

Some note

:::

Output:

:::note Some note :::

:::note

Some note :::

:::note Some note

:::

::: note

Some note

:::

Expected behavior:

:::note
Some note
:::

:::note
Some note
:::

:::note
Some note
:::

:::note
Some note
:::

Contributor guide

Tech stack
javascriptnodejs
Domain
toolingdeveloper experiencedocumentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
Familiarity with Prettier's markdown parserUnderstanding of AST transformations
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
30
Research direction
The issue requests support for Docusaurus style callouts/admonitions in markdown (e.g., :::note). The expected behavior is to preserve the block structure without collapsing content into a single line. To implement, study Prettier's markdown parser in src/language markdown/ and how it handles non standard syntax. The remark admonitions plugin (https://github.com/elviswolcott/remark admonitions) can serve as a reference. The challenge is to modify the parser or printer to treat ::: as a container block, similar to how code fences are handled. The issue has been open since June 2020 with 12 reactions, indicating user interest. No existing PR or assignee, so it's open for contribution.