shuding/nextra

Feature request: Vitepress-style callout markdown support

Open

#2,606 opened on Dec 29, 2023

View on GitHub
 (4 comments) (2 reactions) (0 assignees)TypeScript (13,807 stars) (1,413 forks)user submission
feature requesthelp wanted

Description

Hello! I’m a new user to Nextra but it is hands-down the best React-powered docs solution I’ve run across. I love how quickly it is to get up-and-running with almost no config, and I love how great everything looks, feels, and works ❤️.

Feature Request

Nextra has Callouts, but requires importing the component manually. Vitepress, instead, has a more automatic built-in syntax:

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

This is not only easier to compose; it also works in regular ol’ .md files for more flexibility / portability. And not that the Nextra project needs to be compatible with Vitepress or anything, but in general the more parity this project has with others, the easier it is for people to migrate to it.

If this syntax seems inline with the project, I’d love to add a PR hooking up this syntax with the Callout component.

Contributor guide

Tech stack
typescriptreactnextjs
Domain
documentation
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.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
NextraReactMDX
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75
Research direction
Examine the current Callout component implementation in the Nextra codebase to understand how it's rendered. Then, look into how MDX content is processed, possibly within the 'remark' or 'rehype' plugin chain, and create a plugin to convert the Vitepress style syntax into Callout component calls. The issue author has offered to contribute a PR, so coordination with maintainers might be needed.