Skip to content

Commit f9950e0

Browse files
jhildenbiddlesy-records
jhildenbiddle
authored and
sy-records
committed
Add support for GitHub style callouts
1 parent 2eec7c4 commit f9950e0

File tree

8 files changed

+230
-52
lines changed

8 files changed

+230
-52
lines changed

‎docs/helpers.md‎

Lines changed: 56 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,72 +6,106 @@ docsify extends Markdown syntax to make your documents more readable.
66
77
## Callouts
88

9-
### Important content
9+
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").
1010

11-
Important content like:
11+
<!-- prettier-ignore -->
12+
> [!CAUTION]
13+
> **Caution** callouts communicate negative potential consequences of an action.
1214
13-
```markdown
14-
!> **Time** is money, my friend!
15-
```
15+
<!-- prettier-ignore -->
16+
> [!IMPORTANT]
17+
> **Important** callouts communicate information necessary for users to succeed.
1618
17-
is rendered as:
19+
<!-- prettier-ignore -->
20+
> [!NOTE]
21+
> **Note** callouts communicate information that users should take into account.
1822
19-
!> **Time** is money, my friend!
23+
<!-- prettier-ignore -->
24+
> [!TIP]
25+
> **Tip** callouts communicate optional information to help a user be more successful.
2026
21-
### Tips
27+
<!-- prettier-ignore -->
28+
> [!WARNING]
29+
> **Warning** callouts communicate potential risks user should be aware of.
2230
23-
General tips like:
31+
**Markdown**
2432

33+
<!-- prettier-ignore -->
2534
```markdown
26-
?> _TODO_ unit test
35+
> [!CAUTION]
36+
> **Caution** callouts communicate negative potential consequences of an action.
37+
38+
> [!IMPORTANT]
39+
> **Important** callouts communicate information necessary for users to succeed.
40+
41+
> [!NOTE]
42+
> **Note** callouts communicate information that users should take into account.
43+
44+
> [!TIP]
45+
> **Tip** callouts communicate optional information to help a user be more successful.
46+
47+
> [!WARNING]
48+
> **Warning** callouts communicate potential risks user should be aware of.
2749
```
2850

29-
are rendered as:
51+
### Legacy Style ⚠️
3052

31-
?> _TODO_ unit test
53+
The following Docsify v4 callout syntax has been deprecated and will be removed in a future version.
54+
55+
!> **Important** callouts communicate information necessary for users to succeed.
56+
57+
?> **Tip** callouts communicate optional information to help a user be more successful.
58+
59+
**Markdown**
60+
61+
```markdown
62+
!> **Important** callouts communicate information necessary for users to succeed.
63+
64+
?> **Tip** callouts communicate optional information to help a user be more successful.
65+
```
3266

3367
## Link attributes
3468

3569
### disabled
3670

37-
```md
71+
```markdown
3872
[link](/demo ':disabled')
3973
```
4074

4175
### href
4276

4377
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:
4478

45-
```md
79+
```markdown
4680
[link](/demo/)
4781
```
4882

4983
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`.
5084

5185
Now you can do that
5286

53-
```md
87+
```markdown
5488
[link](/demo/ ':ignore')
5589
```
5690

5791
You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set the title for the link.
5892

59-
```md
93+
```markdown
6094
[link](/demo/ ':ignore title')
6195

6296
<a href="/demo/" title="title">link</a>
6397
```
6498

6599
### target
66100

67-
```md
101+
```markdown
68102
[link](/demo ':target=_blank')
69103
[link](/demo2 ':target=_self')
70104
```
71105

72106
## Task lists
73107

74-
```md
108+
```markdown
75109
- [ ] foo
76110
- bar
77111
- [x] baz
@@ -91,19 +125,19 @@ You will get `<a href="/demo/">link</a>`html. Do not worry, you can still set th
91125

92126
### Class names
93127

94-
```md
128+
```markdown
95129
![logo](https://docsify.js.org/_media/icon.svg ':class=someCssClass')
96130
```
97131

98132
### IDs
99133

100-
```md
134+
```markdown
101135
![logo](https://docsify.js.org/_media/icon.svg ':id=someCssId')
102136
```
103137

104138
### Sizes
105139

106-
```md
140+
```markdown
107141
![logo](https://docsify.js.org/_media/icon.svg ':size=WIDTHxHEIGHT')
108142
![logo](https://docsify.js.org/_media/icon.svg ':size=50x100')
109143
![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
119153

120154
## Heading IDs
121155

122-
```md
156+
```markdown
123157
### Hello, world! :id=hello-world
124158
```
125159

‎docs/ui-kit.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,40 @@
5353

5454
## Callouts
5555

56+
### Github Style
57+
58+
<!-- prettier-ignore -->
59+
> [!CAUTION]
60+
> **Caution** callouts communicate negative potential consequences of an action.
61+
62+
<!-- prettier-ignore -->
63+
> [!IMPORTANT]
64+
> **Important** callouts communicate information necessary for users to succeed.
65+
66+
<!-- prettier-ignore -->
67+
> [!NOTE]
68+
> **Note** callouts communicate information that users should take into account.
69+
70+
<!-- prettier-ignore -->
71+
> [!TIP]
72+
> **Tip** callouts communicate optional information to help a user be more successful.
73+
74+
<!-- prettier-ignore -->
75+
> [!WARNING]
76+
> **Warning** callouts communicate potential risks user should be aware of.
77+
78+
**Nested**
79+
80+
<!-- prettier-ignore -->
81+
> [!CAUTION]
82+
> **Caution** callouts communicate negative potential consequences of an action.
83+
> > [!IMPORTANT]
84+
> > **Important** callouts communicate information necessary for users to succeed.
85+
> > > [!NOTE]
86+
> > > **Note** callouts communicate information that users should take into account.
87+
88+
#### Legacy Docsify Style
89+
5690
!> **Important** callout with `inline code` and additional placeholder text used
5791
to force the content to wrap and span multiple lines.
5892

‎src/core/render/compiler.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
import { imageCompiler } from './compiler/image.js';
1414
import { highlightCodeCompiler } from './compiler/code.js';
1515
import { paragraphCompiler } from './compiler/paragraph.js';
16+
import { blockquoteCompiler } from './compiler/blockquote.js';
1617
import { taskListCompiler } from './compiler/taskList.js';
1718
import { taskListItemCompiler } from './compiler/taskListItem.js';
1819
import { linkCompiler } from './compiler/link.js';
@@ -232,6 +233,7 @@ export class Compiler {
232233
return `<h${depth} id="${slug}" tabindex="-1"><a href="${url}" data-id="${slug}" class="anchor"><span>${str}</span></a></h${depth}>`;
233234
};
234235

236+
origin.blockquoteCompiler = blockquoteCompiler({ renderer });
235237
origin.code = highlightCodeCompiler({ renderer });
236238
origin.link = linkCompiler({
237239
renderer,

‎src/core/render/compiler/blockquote.js‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
export const blockquoteCompiler = ({ renderer }) =>
2+
(renderer.blockquote = function ({ tokens }) {
3+
const calloutData =
4+
tokens[0].type === 'paragraph' &&
5+
// 0: Match "[!TIP] My Title"
6+
// 1: Mark "[!TIP]"
7+
// 2: Type "TIP"
8+
tokens[0].raw.match(/^(\[!(\w+)\])/);
9+
10+
let openTag = '<blockquote>';
11+
let closeTag = '</blockquote>';
12+
13+
if (calloutData) {
14+
const calloutMark = calloutData[1]; // "[!TIP]"
15+
const calloutType = calloutData[2].toLowerCase(); // "tip"
16+
const token = tokens[0].tokens[0];
17+
18+
// Remove callout mark from tokens
19+
['raw', 'text'].forEach(key => {
20+
token[key] = token[key].replace(calloutMark, '').trimStart();
21+
});
22+
23+
// Remove empty paragraph
24+
if (tokens.length > 1 && !token.raw.trim()) {
25+
tokens = tokens.slice(1);
26+
}
27+
28+
openTag = `<div class="callout ${calloutType}">`;
29+
closeTag = `</div>`;
30+
}
31+
32+
const body = this.parser.parse(tokens);
33+
const html = `${openTag}${body}${closeTag}`;
34+
35+
return html;
36+
});

‎src/core/render/tpl.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,9 @@ export function tree(
112112
return tpl.replace('{inner}', innerHTML);
113113
}
114114

115+
/**
116+
* @deprecated
117+
*/
115118
export function helper(className, content) {
116119
return /* html */ `<p class="${className}">${content.slice(5).trim()}</p>`;
117120
}

‎src/themes/addons/core-dark.css‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,46 @@
2828
color-scheme: dark;
2929
}
3030

31+
/* Cover */
32+
/* ========================================================================== */
3133
.cover-main {
3234
a.button.secondary {
3335
color: var(--color-text);
3436
border-color: rgba(255, 255, 255, 0.5);
3537
}
3638
}
39+
40+
/* Markdown */
41+
/* ========================================================================== */
42+
.markdown-section {
43+
.callout {
44+
&[class] {
45+
--callout-bg: unset;
46+
}
47+
48+
&.caution {
49+
--callout-border-color: #991b1b; /* Tailwind: red 800 */
50+
}
51+
52+
&.important {
53+
--callout-border-color: #5b21b6; /* Tailwind: violet 800 */
54+
}
55+
56+
&.note {
57+
--callout-border-color: var(--theme-color-4);
58+
}
59+
60+
&.tip {
61+
--callout-border-color: #115e59; /* Tailwind: teal 800 */
62+
}
63+
64+
&.warning {
65+
--callout-border-color: #a16207; /* Tailwind: yellow 700 */
66+
}
67+
68+
code,
69+
pre:where([data-lang]) {
70+
background: var(--color-mono-min);
71+
}
72+
}
73+
}

‎src/themes/shared/_markdown.css‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,13 +126,29 @@
126126
text-align: center;
127127
}
128128

129+
> :first-child {
130+
margin-top: 0;
131+
}
132+
133+
> :last-child {
134+
margin-bottom: 0;
135+
}
136+
129137
code,
130138
strong {
131139
color: inherit;
132140
}
133141

134142
code {
135-
background: rgba(0, 0, 0, 0.08);
143+
background: rgba(0, 0, 0, 0.05);
144+
}
145+
146+
pre:where([data-lang]) {
147+
background: rgba(255, 255, 255, 0.4);
148+
}
149+
150+
.callout {
151+
margin-block: var(--margin-block);
136152
}
137153
}
138154

@@ -226,7 +242,7 @@
226242
padding: 0 !important;
227243
padding-block: 1.5rem !important;
228244
padding-inline: 1.5rem !important;
229-
background: inherit;
245+
background: transparent;
230246
color: inherit;
231247
font-size: inherit;
232248
white-space: inherit;

0 commit comments

Comments
 (0)