Refactor GitHub alert capitalization styling

[hichemfantar]

Why:

Titles should displayed as they are and modified via css to allow control and easier overrided by the users.

more reliable (text isn't modified) also better performance (no js) and more typesafe (non-null assertion)

contributes to: #4087

What's being changed (if available, include any code snippets, screenshots, or gifs):

Replace manual capitalization of GitHub alert names with CSS styling for improved consistency and maintainability.

Check off the following:

• I have reviewed my changes in staging, available via the View
  deployment link in this PR's timeline (this link will be available after
  opening the PR).

[changeset-bot]

⚠️ No Changeset found

Latest commit: 91bbfc3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nextra-v2	❌ Failed (Inspect)			Jan 28, 2025 3:02pm

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
nextra	⬜️ Ignored (Inspect)	Visit Preview		Jan 28, 2025 3:02pm

[vercel]

@hichemfantar is attempting to deploy a commit to the Vercel Team on Vercel.

A member of the Team first needs to authorize it.

[dimaMachina]

via css to allow control and easier overrided by the users.

this this another feature to implement, i don't see any benefit in your change, even github when you write [!NOTE] outputs in DOM Note and not NOTE

[hichemfantar]

via css to allow control and easier overrided by the users.

I'm talking css stylesheet override not passing props

also

better performance (no js) and more typesafe (non-null assertion)

and it's compatible with #4087

[hichemfantar]

even docusaurus uses css for text transform

[hichemfantar]

the current implementation has downsides but the new one doesn't have any

[dimaMachina]

via css to allow control and easier overrided by the users.

I'm talking css stylesheet override not passing props

also

better performance (no js) and more typesafe (non-null assertion)

and it's compatible with #4087

it's not compatible due to this check

nextra/packages/nextra/src/client/hocs/with-github-alert.tsx

Lines 29 to 33 in bcc34cc

	const alertName = str
	.match(GITHUB_ALERT_RE)
	?.groups?.name!.toLowerCase()
	if (alertName) {

[hichemfantar]

let me see

[hichemfantar]

the check doesn't affect current behavior, our change is purely presentation.

[hichemfantar]

ah you mean the assertion, i'll handle it

[hichemfantar]

fixed

[dimaMachina]

I don't see the pros of this PR, github renders all of these same

> [!note]
> [!note]

> [!nOte]
> [!nOte]

> [!NOTE]
> [!NOTE]

Note

[!note]

Note

[!nOte]

Note

[!NOTE]

[hichemfantar]

It’s future proofing for #4087

[dimaMachina]

the goal of this HOC to always have same callouts supported by GitHub

If you want to pass custom titles, IMO withGitHubAlert should accept 3rd argument alertMap which is by default

      {
        caution: 'Error',
        important: 'Important',
        note: 'Note',
        tip: 'Tip',
        warning: 'Warning'
      }

so you could override note callout with Good to Know for example

note: 'Good to Know',

so you'll write

> [!NOTE]
> Hello

which will be rendered with

> **Good to know**
> Hello

[hichemfantar]

What if I want to have a call out but use my own titles? I do btw

You shouldn’t assume what the user wants to render because that’s creating unnecessary limitations which is exactly why docusaurus provides a way to provide a custom title.

[dimaMachina]

What if I want to have a call out but use my own titles? I do btw

You can provide your own HOC component (for blockquote element in mdx-components file) which will do whatever you want with your callouts, the goal of this HOC to only support GitHub alert syntax and not your own alert syntax

[dimaMachina]

the goal of this HOC to only support GitHub alert syntax and not your own alert syntax

so callout will be rendered nicely in your website and in GitHub as well

[hichemfantar]

why not make it a general solution? github has a limitation that your solution can easily not have. it's also opt in.
as in it supports github callouts but also custom titles when you need them

it's also a highly requested feature https://github.com/orgs/community/discussions/103219

[dimaMachina]

I don't see the benefit of writing custom alert syntax aka

> [!Foo bar]
> ...

which will be not rendered by GitHub, this isn't goal of this HOC, the goal is to be compatible to GitHub Alert syntax

[dimaMachina]

t's also a highly requested feature github.com/orgs/community/discussions/103219

once it will be supported by github, we can add support in Nextra as well

[hichemfantar]

a documentation engine should as flexible as possible which is why i still use docusaurus for many projects even though i'd like to move them to nextra. it's small things like this that will help nextra get more adoption. take it from a power user.
my 2 cents

[hichemfantar]

do you think we should throw an error here https://github.com/shuding/nextra/pull/4088/files#diff-b10660e8325c20788b36ba3d2b8eb76e4bde020249fd3df234653df7a5d86223R32

[dimaMachina]

Closing since I do not plan to make GitHub Alert Syntax HOC configurable with custom titles (for me it should match GitHub behaviour).

If you need a custom title/icon feature just use Nexta's callout https://nextra.site/docs/built-ins/callout directly