Summary

Add support for new GitHub style callouts
Update documentation with new syntax details and examples
Migrate legacy callouts to new syntax in documentation
Mark legacy syntax as deprecated

Markdown

> [!CAUTION]
> **Caution** callouts communicate negative potential consequences of an action.

> [!IMPORTANT]
> **Important** callouts communicate information necessary for users to succeed.

> [!NOTE]
> **Note** callouts communicate information that users should take into account.

> [!TIP]
> **Tip** callouts communicate optional information to help a user be more successful.

> [!WARNING]
> **Warning** callouts communicate potential risks user should be aware of.

Screenshots

CleanShot 2024-08-08 at 00 07 10@2x

CleanShot 2024-08-08 at 00 06 50@2x

Related issue, if any:

2486

1588

483

What kind of change does this PR introduce?

Feature Docs

For any code change,

[x] Related documentation has been updated, if needed
[x] Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

Tested in the following browsers:

[x] Chrome
[x] Firefox
[x] Safari
[x] Edge

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

Name	Status	Preview	Comments	Updated (UTC)
docsify-preview	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 21, 2024 11:56am

Hiiii @trusktr Joe.

which as we can see results in "caution" being there twice, which means rendering will differ between Docsify and GitHub.

I think the behavior is totally acceptable.

We host docsify in server/githubpage with our own md parser instead github's. (Although it may looks odd when read raw markdown in github)
You put all the things under EN and github does not support i18n tho.

i.e.

All is EN, and github's callout icon supports only EN. it seems duplicated.

[!CAUTION] Caution callouts communicate negative potential consequences of an action.

How about this? The content is ZH, but github still gives me EN callout icon with EN content tho.

[!CAUTION] 非常重要 这里是一条你不能错过的信息。

IMHO, It is worse than only simply support a icon.

@trusktr @Koooooo-7 --

You both have valid points. I believe the current design and proposed custom label feature (described here) addresses both of them.

For context, understand that a large number of people are unhappy with GitHub's English-centric callout design (see https://github.com/orgs/community/discussions/16925#discussioncomment-9861713). GitHub callouts always display a label and that label is always in English. There is no way to override this, which can be problematic when authoring markdown non-English languages.

The Docsify callout design addresses GitHub's English-centric design by rendering only an icon without a label by default. This allows users to easy customize callout labels as they prefer directly in their markdown:

Markdown:

<!-- No label, single line -->
> [!caution]
> This is the callout text.

<!-- EN label, single line -->
> [!caution] **Caution:** This is the callout text.

<!-- EN label, new line -->
> [!caution]
>
> **Caution**
>
> This is the callout text.

<!-- ZH label, new line -->
> [!caution]
>
> **非常重要 这里是**
>
> This is the callout text.

However, I believe @trusktr is correct that there will be users who expect Docsify to render callout labels as GitHub does. Users who manually add callout labels in their markdown to "fix" the problem in Docsify may also be unhappy when duplicate titles are rendered on GitHub. This is why I would like to optionally render titles and provide the ability to define localized labels as part of the Docsify config here.

Per @Koooooo-7's preference, the default configuration will render icons only:

window.$docsify = {
  // Default: do not render callout titles
  callouts: {},
};

Per @trusktr's preference, specifying callout labels in English will render callout labels as seen on GitHub and avoid duplicate titles when markdown is rendered on GitHub:

window.$docsify = {
  // Render EN callout titles for all route paths
  callouts: {
    caution: 'Caution',
    important: 'Important',
    note: 'Note',
    tip: 'Tip',
    warning: 'Warning',
  },
};

For sites offering localized documentation, callout labels can be defined based on the route path:

window.$docsify = {
  // Render localized labels based on route paths
  callouts: {
    caution: {
      '/es/': 'Precaución',
      '/de-de/': 'Vorsicht',
      '/ru-ru/': 'Осторожность',
      '/zh-cn/': '警告',
      '/': 'Caution',
    },
    important: {
      // ...
    },
    note: {
      // ...
    },
    tip: {
      // ...
    },
    warning: {
      // ...
    },
  },
};

NOTE: After this PR is merged, it is my intention to recommend GitHub consider a similar "icons only be default" design to address the concerns with their current EN-centric design. I would like to link to our own documentation (once completed) as a reference.

However, I believe @trusktr is correct that there will be users who expect Docsify to render callout labels as GitHub does. Users who manually add callout labels in their markdown to "fix" the problem in Docsify may also be unhappy when duplicate titles are rendered on GitHub.

@jhildenbiddle --- I keep my point that we could just provide a callout icon and keep the consistency in docsify.
The user unhappy things don't make sense to me:

Normally, user don't need add a label to "explain" what the icon means, icon already explains itself by default. and if they do want do so, they can.
docsify is not a github based project, we don't need strict follow the github UX stuff for now and in future, it is unpredictable how would github to be in further. All the things are just an refer. If we cares about docsify render the callout not same to github. When users view and manage their repo in gitlab,bitbucket...etc, which may have different UX stylings. y and would you refuse to follow them? What docsify should do is maintain its own callout styling in consistency. No matter it would be deployed in github pages or other places/services. It is the docsify's renderer job, none of anything code/markdown management services' business.
User wants the docs render good in their site, not means it should be same result to view github raw markdown or in other git service providers. otherwise, such as the :id=Heading config should be removed from docsify, github can not parser it, either the js scripts within a markdown. docsify isn't a markdown viewer plugin for github using the github markdown parser. Even the callout syntax is not supported in github enterprise also. docsify aims to build a docs site with its own unique styling.

I understand the $.callouts config can both compatible with this, I just think it is unnecessary to strict follow github's to do those changes tho.

@jhildenbiddle --- I keep my point that we could just provide a callout icon and keep the consistency in docsify.

Agreed. This is why I opted for the "icon-only" presentation initially and propose it remain the default presentation for Docsify. I believe it is better than GitHub's implementation because it addresses internationalization issues inherent in GitHub's implementation and gives users control over if/how callout titles are rendered.

However, it is also true the icon-only presentation is unique to Docsify and not how other popular markdown environments render the same callout syntax. One way to "fix" the inconsistency in Docsify is to add text labels in markdown, however this will produce duplicate labels when rendered on GitHub and other environments that support the [!LABEL] syntax:

[!CAUTION] CAUTION

This is some text

Missing or duplicate labels may not matter to some but they definitely will matter to others. Hence the label option.

Normally, user don't need add a label to "explain" what the icon means, icon already explains itself by default. and if they do want do so, they can.

Agreed on the "if they want to do so, they can" part. The label configuration option provides a way of rendering callout labels that also prevents duplicate labels from being rendered outside of Docsify (see example above). This issue is created by our decision to have a different default presentation (icon-only) than other markdown environments that support the same syntax. If we instead chose to render callous labels by default as other markdown environments do, we wouldn't have to worry about duplicate callout labels when rendering callout markdown outside of Docsify.

When users view and manage their repo in gitlab,bitbucket...etc, which may have different UX stylings. y and would you refuse to follow them? What docsify should do is maintain its own callout styling in consistency. No matter it would be deployed in github pages or other places/services. It is the docsify's renderer job, none of anything code/markdown management services' business.

This is about content consistency, not style consistency.

The issue people have with GitHub's callout implementation is that it introduces potentially unwanted content in the form of English-only labels without the ability to modify them. I think this is a mistake, as do many others who have shared their opinions in the GitHub callout discussion. Regardless and for better or worse, other markdown environments that offer native support for the same syntax (e.g., Obsidian, Typora, VitePress) also render callout labels by default. In order for Docsify to render callouts consistently across environments, we need to provide an option to render callout labels as other environments do. This matters because markdown is a portable documentation format and it is therefore not uncommon for people/teams to edit markdown content in different environments. For example, I frequently edit Docsify markdown in Typora and I know first-hand of teams that have non-technical team members edit Docsify markdown content directly on GitHub.

As far as styles go, Docsify has its own callout style (icons, colors, border, backgrounds, etc.) just as other markdown environments do. This is not unexpected as it is very much a benefit/feature of markdown's portability.

...otherwise, such as the :id=Heading config should be removed from docsify, github can not parser it, either the js scripts within a markdown.

I would love to remove non-standard, Docsify-only syntax from Docsify because the more of it we offer the less portable Docsify markdown becomes. Unfortunately, there are some features that markdown does not offer and extended syntaxes to support them have not been standardized so we're left to invent our own sometimes. IMHO, these non-standard, Docsify-only markdown extensions are a necessary evil, not a pattern to continue if we can help it.

In the case of callouts, a standardized syntax did not exist back in 2017 when Docsify v4 was released so the custom "important" (!>) and "tip" (?>) syntax were fine (although they had issues like not supporting multi-line and nested content). Now that GitHub has released support for the [!LABEL] syntax, markdown environments are adopting it because of GitHub's reach and influence. The syntax is far from perfect, but it's far closer to a standard than Docsify's previous helper syntax is likely to ever be.

@Koooooo-7 I agree that we may be able to do it better, but I think having GitHub behavior at least be optional (and possibly default) would be great so that people can have consistency. Even if it isn't GitHub, many Docsify sites are hosted on GitHub.

unpredictable how would github to be in further

I bet they aren't willing to make many breaking changes, if any. The way GitHub flavored markdown has worked has remained constant as far as I have ever noticed, apart from new features coming in (f.e. callouts).

Another thing is that "Markdown" was meant to be a standard, and the more variations we have of it, the more fragmented the community. GitHub's is one of the most popular variants of Markdown (if not the most popular), so I think it is worth having consistency in the language, similar to how browsers standardize for HTML, CSS, and JavaScript.

Because of this, I believe we should have a way to follow GitHub's format, but we can allow it to be more flexible customizeable too, best of both worlds. Basically it would be a complete superset of the "standard" markdown, rather than a fork with new parts and parts of standard missing.

@jhildenbiddle good point about the language! I would be happy to be able to configure it to work like GitHub's defaults, but otherwise having it be easy for other people to configure the callout names for their language. It also works that way in docsify-plugin-flexible-alerts, which is nice.

Perhaps GitHub behavior should be the default unless a config is provided to override it. The reason is because the "standard" is in english GFM, with default the default behavior on GitHub, so maybe good if it just works the same out of the box with no config. Then someone who needs it in another language can add the config, which is better than both types of users having to add the config. Wdyt?

docsify-plugin-flexible-alerts also allows customizing the icon, but it requires the font awesome class (f.e. fa-caution) to be specified. I think it would be nice to be able to provide the URL for each icon image instead of a class (or alternative to a class). Useful for "troubleshooting", "bug", and other types of callouts. Or f.e. a warcraft site has warcraft-style shield-like icons, or a stock trading website has bull and bear icons, etc. 😄

--- @jhildenbiddle @trusktr , thx for the sharing of more thoughts on it. The pros seems benefit more to users and more close to "modern markdown renderer result standard". Although I see some comments in that community/discussions/16925 still argue with github's standard. And it hasn't been added into the GFM/sepc beyond the CommonMark Spec yet.

Generally, introducing this config won't disable any config styles we talk about, it could make everyone happy, so I'm okay with it.

As far as styles go, Docsify has its own callout style (icons, colors, border, backgrounds, etc.) just as other markdown environments do. This is not unexpected as it is very much a benefit/feature of markdown's portability.

...otherwise, such as the :id=Heading config should be removed from docsify, github can not parser it, either the js scripts within a markdown.

I would love to remove non-standard, Docsify-only syntax from Docsify because the more of it we offer the less portable Docsify markdown becomes. Unfortunately, there are some features that markdown does not offer and extended syntaxes to support them have not been standardized so we're left to invent our own sometimes. IMHO, these non-standard, Docsify-only markdown extensions are a necessary evil, not a pattern to continue if we can help it.

I see, we could keep them to achieve the consistency in docsify for now, and remove it to achieve the consistency in generic markdown standard in future.

Off topic: A little thoughts about the i18n by path solution in docsify itself. Currently, it only exists in search placeholder and the callout. (Others like alias, nameLink more like the path mapping, not i18n content) If the i18n part text grows more, we may need consider categorize them in future, TBD.

--- @trusktr

Another thing is that "Markdown" was meant to be a standard, and the more variations we have of it, the more fragmented the community. GitHub's is one of the most popular variants of Markdown (if not the most popular), so I think it is worth having consistency in the language, similar to how browsers standardize for HTML, CSS, and JavaScript.

Because of this, I believe we should have a way to follow GitHub's format, but we can allow it to be more flexible customizeable too, best of both worlds. Basically it would be a complete superset of the "standard" markdown, rather than a fork with new parts and parts of standard missing.

Agreed. and I have more deep realization of the github influence now.