Add support for GitHub style callouts

Author: jhildenbiddle

Diff for: docs/helpers.md

@@ -6,72 +6,106 @@ docsify extends Markdown syntax to make your documents more readable.
 
 ## Callouts
 
-### Important content
+Docsify supports [GitHub style](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) callouts (also known as "admonitions" or "alerts").
 
-Important content like:
+<!-- prettier-ignore -->
+> [!CAUTION]
+> **Caution** callouts communicate negative potential consequences of an action.
 
-```markdown
-!> **Time** is money, my friend!
-```
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> **Important** callouts communicate information necessary for users to succeed.
 
-is rendered as:
+<!-- prettier-ignore -->
+> [!NOTE]
+> **Note** callouts communicate information that users should take into account.
 
-!> **Time** is money, my friend!
+<!-- prettier-ignore -->
+> [!TIP]
+> **Tip** callouts communicate optional information to help a user be more successful.
 
-### Tips
+<!-- prettier-ignore -->
+> [!WARNING]
+> **Warning** callouts communicate potential risks user should be aware of.
 
-General tips like:
+**Markdown**
 
+<!-- prettier-ignore -->
 ```markdown
-?> _TODO_ unit test
+> [!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.
 ```
 
-are rendered as:
+### Legacy Style ⚠️
 
-?> _TODO_ unit test
+The following Docsify v4 callout syntax has been deprecated and will be removed in a future version.
+
+!> **Important** callouts communicate information necessary for users to succeed.
+
+?> **Tip** callouts communicate optional information to help a user be more successful.
+
+**Markdown**
+
+```markdown
+!> **Important** callouts communicate information necessary for users to succeed.
+
+?> **Tip** callouts communicate optional information to help a user be more successful.
+```
 
 ## Link attributes
 
 ### disabled
 
-```md
+```markdown
 [link](/demo ':disabled')
 ```
 
 ### href
 
 Sometimes we will use some other relative path for the link, and we have to tell docsify that we don't need to compile this link. For example:
 
-```md
+```markdown
 [link](/demo/)
 ```
 
 It will be compiled to `<a href="/#/demo/">link</a>` and will load `/demo/README.md`. Maybe you want to jump to `/demo/index.html`.
 
 Now you can do that
 
-```md
+```markdown
 [link](/demo/ ':ignore')
 ```
 
 You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set the title for the link.
 
-```md
+```markdown
 [link](/demo/ ':ignore title')
 
 <a href="/demo/" title="title">link</a>
 ```
 
 ### target
 
-```md
+```markdown
 [link](/demo ':target=_blank')
 [link](/demo2 ':target=_self')
 ```
 
 ## Task lists
 
-```md
+```markdown
 - [ ] foo
 - bar
 - [x] baz
@@ -91,19 +125,19 @@ You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set th
 
 ### Class names
 
-```md
+```markdown
 ![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass')
 ```
 
 ### IDs
 
-```md
+```markdown
 ![logo](https://docsify.js.org/_media/icon.svg ':id=someCssId')
 ```
 
 ### Sizes
 
-```md
+```markdown
 ![logo](https://docsify.js.org/_media/icon.svg ':size=WIDTHxHEIGHT')
 ![logo](https://docsify.js.org/_media/icon.svg ':size=50x100')
 ![logo](https://docsify.js.org/_media/icon.svg ':size=100')
@@ -119,7 +153,7 @@ You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set th
 
 ## Heading IDs
 
-```md
+```markdown
 ### Hello, world! :id=hello-world
 ```
 

Diff for: docs/ui-kit.md

@@ -53,6 +53,40 @@
 
 ## Callouts
 
+### Github Style
+
+<!-- prettier-ignore -->
+> [!CAUTION]
+> **Caution** callouts communicate negative potential consequences of an action.
+
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> **Important** callouts communicate information necessary for users to succeed.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> **Note** callouts communicate information that users should take into account.
+
+<!-- prettier-ignore -->
+> [!TIP]
+> **Tip** callouts communicate optional information to help a user be more successful.
+
+<!-- prettier-ignore -->
+> [!WARNING]
+> **Warning** callouts communicate potential risks user should be aware of.
+
+**Nested**
+
+<!-- prettier-ignore -->
+> [!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.
+
+#### Legacy Docsify Style
+
 !> **Important** callout with `inline code` and additional placeholder text used
 to force the content to wrap and span multiple lines.
 

Diff for: src/core/render/compiler.js

@@ -13,6 +13,7 @@ import {
 import { imageCompiler } from './compiler/image.js';
 import { highlightCodeCompiler } from './compiler/code.js';
 import { paragraphCompiler } from './compiler/paragraph.js';
+import { blockquoteCompiler } from './compiler/blockquote.js';
 import { taskListCompiler } from './compiler/taskList.js';
 import { taskListItemCompiler } from './compiler/taskListItem.js';
 import { linkCompiler } from './compiler/link.js';
@@ -232,6 +233,7 @@ export class Compiler {
       return `<h${depth} id="${slug}" tabindex="-1"><a href="${url}" data-id="${slug}" class="anchor"><span>${str}</span></a></h${depth}>`;
     };
 
+    origin.blockquoteCompiler = blockquoteCompiler({ renderer });
     origin.code = highlightCodeCompiler({ renderer });
     origin.link = linkCompiler({
       renderer,

Diff for: src/core/render/compiler/blockquote.js

@@ -0,0 +1,36 @@
+export const blockquoteCompiler = ({ renderer }) =>
+  (renderer.blockquote = function ({ tokens }) {
+    const calloutData =
+      tokens[0].type === 'paragraph' &&
+      // 0: Match "[!TIP] My Title"
+      // 1: Mark "[!TIP]"
+      // 2: Type "TIP"
+      tokens[0].raw.match(/^(\[!(\w+)\])/);
+
+    let openTag = '<blockquote>';
+    let closeTag = '</blockquote>';
+
+    if (calloutData) {
+      const calloutMark = calloutData[1]; // "[!TIP]"
+      const calloutType = calloutData[2].toLowerCase(); // "tip"
+      const token = tokens[0].tokens[0];
+
+      // Remove callout mark from tokens
+      ['raw', 'text'].forEach(key => {
+        token[key] = token[key].replace(calloutMark, '').trimStart();
+      });
+
+      // Remove empty paragraph
+      if (tokens.length > 1 && !token.raw.trim()) {
+        tokens = tokens.slice(1);
+      }
+
+      openTag = `<div class="callout ${calloutType}">`;
+      closeTag = `</div>`;
+    }
+
+    const body = this.parser.parse(tokens);
+    const html = `${openTag}${body}${closeTag}`;
+
+    return html;
+  });

Diff for: src/core/render/tpl.js

@@ -112,6 +112,9 @@ export function tree(
   return tpl.replace('{inner}', innerHTML);
 }
 
+/**
+ * @deprecated
+ */
 export function helper(className, content) {
   return /* html */ `<p class="${className}">${content.slice(5).trim()}</p>`;
 }

Diff for: src/themes/addons/core-dark.css

@@ -28,9 +28,46 @@
   color-scheme: dark;
 }
 
+/* Cover */
+/* ========================================================================== */
 .cover-main {
   a.button.secondary {
     color: var(--color-text);
     border-color: rgba(255, 255, 255, 0.5);
   }
 }
+
+/* Markdown */
+/* ========================================================================== */
+.markdown-section {
+  .callout {
+    &[class] {
+      --callout-bg: unset;
+    }
+
+    &.caution {
+      --callout-border-color: #991b1b; /* Tailwind: red 800 */
+    }
+
+    &.important {
+      --callout-border-color: #5b21b6; /* Tailwind: violet 800 */
+    }
+
+    &.note {
+      --callout-border-color: var(--theme-color-4);
+    }
+
+    &.tip {
+      --callout-border-color: #115e59; /* Tailwind: teal 800 */
+    }
+
+    &.warning {
+      --callout-border-color: #a16207; /* Tailwind: yellow 700 */
+    }
+
+    code,
+    pre:where([data-lang]) {
+      background: var(--color-mono-min);
+    }
+  }
+}

Diff for: src/themes/shared/_markdown.css

@@ -126,13 +126,29 @@
       text-align: center;
     }
 
+    > :first-child {
+      margin-top: 0;
+    }
+
+    > :last-child {
+      margin-bottom: 0;
+    }
+
     code,
     strong {
       color: inherit;
     }
 
     code {
-      background: rgba(0, 0, 0, 0.08);
+      background: rgba(0, 0, 0, 0.05);
+    }
+
+    pre:where([data-lang]) {
+      background: rgba(255, 255, 255, 0.4);
+    }
+
+    .callout {
+      margin-block: var(--margin-block);
     }
   }
 
@@ -226,7 +242,7 @@
       padding: 0 !important;
       padding-block: 1.5rem !important;
       padding-inline: 1.5rem !important;
-      background: inherit;
+      background: transparent;
       color: inherit;
       font-size: inherit;
       white-space: inherit;