Skip to content

Commit 388c93d

Browse files
tuureptuurep
committed
docs(#141): add a guide for alerts customization
1 parent 37f1814 commit 388c93d

3 files changed

Lines changed: 222 additions & 76 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,17 +42,18 @@ issue](https://github.com/jannis-baum/vivify/issues/new/choose) or
4242
- [KaTeX math](https://katex.org)
4343
- [graphviz/dot graphs](https://graphviz.org/doc/info/lang.html)
4444
- [Mermaid diagrams & charts](https://mermaid.js.org)
45+
- alert blocks
46+
- default styles like in [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
47+
- [syntax extensions](docs/alerts.md#custom-marker) similar to [Obsidian
48+
callouts](https://help.obsidian.md/callouts)
49+
- configurable [custom alerts](docs/alerts.md#configuring-alert-icons)
4550
- links to other files: [relative links like in
4651
GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#relative-links)
4752
as well as absolute file links
4853
- [add styles, classes, ids or other attributes directly from
4954
Markdown](https://github.com/arve0/markdown-it-attrs?tab=readme-ov-file#examples)
5055
- table of contents with `[[toc]]`
5156
- `<kbd>` tags, e.g. to style keyboard shortcuts
52-
- [GitHub alert
53-
blocks](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
54-
- with syntax extension similar to [Obsidian callouts](https://help.obsidian.md/callouts)
55-
- highly customizable custom alerts, with defaults like GitHub
5657

5758
You can find examples for all supported features in the files in the
5859
[`tests/rendering`](tests/rendering) directory. In case you are looking at these

‎docs/alerts.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# Alerts usage and customization
2+
3+
There are five default alerts, that are styled without configuration. These are the
4+
[GitHub
5+
alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts):
6+
7+
```md
8+
> [!NOTE]
9+
> Lorem ipsum
10+
```
11+
12+
```md
13+
> [!TIP]
14+
> Lorem ipsum
15+
```
16+
17+
```md
18+
> [!IMPORTANT]
19+
> Lorem ipsum
20+
```
21+
22+
```md
23+
> [!WARNING]
24+
> Lorem ipsum
25+
```
26+
27+
```md
28+
> [!CAUTION]
29+
> Lorem ipsum
30+
```
31+
32+
## Custom marker
33+
34+
We have extended support similar to [how alerts work in
35+
Obsidian](https://help.obsidian.md/callouts) (where they are called "callouts").
36+
The marker can be a custom multi-word string, like this:
37+
38+
```md
39+
> [!CUSTOM MARKER]
40+
> Lorem ipsum
41+
```
42+
43+
By default, the above alert (with an arbitrary marker) is styled like `[!NOTE]`.
44+
This matches Obsidian's default behavior. If you want to style this separately,
45+
see [customizing fallback alert](#customizing-fallback-alert).
46+
47+
## Custom title
48+
49+
Alert title can optionally be set with the following extended syntax:
50+
51+
```md
52+
> [!NOTE] A custom title
53+
> Lorem ipsum
54+
```
55+
56+
Additionally, custom titles for markers can be set in the configuration:
57+
58+
```json
59+
{
60+
"alertOptions": {
61+
"titles": {
62+
"note": "A custom title"
63+
}
64+
}
65+
}
66+
```
67+
68+
With the above example, `[!NOTE]` would *always* be rendered with the title *A
69+
custom title*.
70+
71+
## Case sensitivity
72+
73+
Marker names are matched case-insensitively, meaning `[!CUSTOM MARKER]`,
74+
`[!custom marker]` and `[!Custom Marker]` refer to the same type of alert.
75+
76+
In the same way, all keys in `alertOptions.icons` and `alertOptions.titles` are
77+
case-insensitive.
78+
79+
## Configuring alert icons
80+
81+
Set custom icons for alerts by marker type like this:
82+
83+
```json
84+
{
85+
"alertOptions": {
86+
"icons": {
87+
"custom": "bell"
88+
}
89+
}
90+
}
91+
```
92+
93+
When set as a string, the icon is interpreted to be a valid
94+
[octicon](https://primer.style/octicons/) name.
95+
96+
This would set the octicon [`bell`](https://primer.style/octicons/icon/bell-16/)
97+
for alert
98+
`[!CUSTOM]`.
99+
100+
### Advanced icon configuration
101+
102+
To use icons other than octicons, the value can be set as a path to an svg
103+
file, for example:
104+
105+
Absolute path:
106+
107+
- `"custom": "/home/user/.config/vivify/icons/flower.svg"`
108+
109+
Home as tilde:
110+
111+
- `"custom": "~/.config/vivify/icons/flower.svg"`
112+
113+
Path relative to Vivify config directory:
114+
115+
- `"custom": "./icons/flower.svg"`
116+
117+
Even a raw svg string can be set in the configuration:
118+
119+
- `"custom": "<svg> ... </svg>"`
120+
121+
## Customizing alert colors
122+
123+
Colors should be customized in your custom stylesheet (via the `"styles"` option
124+
in the [config](customization.md)).
125+
126+
To set any color to a custom alert type:
127+
128+
```css
129+
.alert-custom { --color: #00ff00; }
130+
```
131+
132+
The left-side border, title icon, and title text will be colored as `--color`.
133+
134+
The CSS class is fully lowercased and in `kebab-case`. So for a marker with a
135+
multi-word name, this is how you'd set the color:
136+
137+
```css
138+
.alert-my-multi-word-name { --color: #00ff00; }
139+
```
140+
141+
Instead of coming up with a new hex color, you may want to match to one of the
142+
default alerts' colors. Use one of these CSS variables:
143+
144+
- `--alert-note`
145+
- `--alert-tip`
146+
- `--alert-important`
147+
- `--alert-warning`
148+
- `--alert-caution`
149+
150+
For example:
151+
152+
```css
153+
.alert-custom { --color: var(--alert-important); }
154+
```
155+
156+
## Examples
157+
158+
Here are a few practical examples to achieve some types of alerts that have
159+
default styles in Obsidian, but not on GitHub:
160+
161+
- `[!TODO]`
162+
- `[!QUESTION]`
163+
- `[!EXAMPLE]`
164+
- `[!SUCCESS]`
165+
- `[!FAILURE]`
166+
167+
```json
168+
{
169+
"alertOptions": {
170+
"icons": {
171+
"todo": "check-circle",
172+
"question": "question",
173+
"example": "list-unordered",
174+
"success": "check",
175+
"failure": "x"
176+
}
177+
}
178+
}
179+
```
180+
181+
```css
182+
.alert-todo { --color: var(--alert-note); }
183+
.alert-question { --color: var(--alert-warning); }
184+
.alert-example { --color: var(--alert-important); }
185+
.alert-success { --color: var(--alert-tip); }
186+
.alert-failure { --color: var(--alert-caution); }
187+
```
188+
189+
## Customizing fallback alert
190+
191+
Any custom alert that hasn't been configured will have the same icon and color
192+
as `[!NOTE]`. If you want a whole separate color and icon for unconfigured
193+
alerts, use these options:
194+
195+
```json
196+
{
197+
"alertOptions": {
198+
"fallbackIcon": "alert"
199+
}
200+
}
201+
```
202+
203+
> [!NOTE]
204+
> `"fallbackIcon"` is a separate option outside of the `"icons"` table, but
205+
> accepts the same type of icon value as the [icon
206+
> customization](#configuring-alert-icons).
207+
208+
For the color, any alert that doesn't have a "known" marker gets a CSS class as
209+
`.fallback-alert`. So, to customize the color:
210+
211+
```css
212+
.fallback-alert { --color: #ff0000; }
213+
```

‎docs/customization.md‎

Lines changed: 4 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -76,9 +76,9 @@ keys:
7676

7777
- **`"alertOptions"`**\
7878
Options to customize
79-
[Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
79+
[alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
8080
beyond the 5 default ones used by GitHub. You may also know this feature by
81-
the name of [Obsidian Callouts](https://help.obsidian.md/callouts).
81+
the name of [Obsidian callouts](https://help.obsidian.md/callouts).
8282

8383
```json
8484
"alertOptions": {
@@ -92,77 +92,9 @@ keys:
9292
}
9393
```
9494

95-
In more detail:
95+
For alerts customization, see [full explanation with examples](alerts.md).
9696

97-
- **`"icons"`**
98-
99-
**Key:** Any custom marker name. Can also be a multi-word string. Matched
100-
case-insensitively.
101-
102-
**Value:** A custom svg to use in one of three formats:
103-
104-
1. Name of an [octicon](https://primer.style/octicons/) (in kebab-case)
105-
2. Path to an svg file, either relative to Vivify's config directory, or
106-
an absolute path. Tilde (`~`) can be used in an absolute path.
107-
3. A raw svg tag as a string. Note: must escape double quotes or use
108-
single quotes inside the string.
109-
110-
> [!WARNING]
111-
> We're considering switching from octicons to lucide as the main icon
112-
> provider, so option 1 is subject to change.
113-
114-
- **`"fallbackIcon"`**
115-
116-
Icon to fall back to for markers you have not explicitly set a custom icon
117-
for. Given in the same format as an entry in the `"icons"` table.
118-
119-
The fallback icon defaults to the icon used by `[!NOTE]`, to match the
120-
default behavior in Obsidian.
121-
122-
- **`"titles"`**
123-
124-
If you want an alert to have a different title than the marker string
125-
itself, it can be mapped in this table.
126-
127-
**Key:** Any custom marker name. Can also be a multi-word string. Matched
128-
case-insensitively.
129-
130-
**Value:** Any string.
131-
132-
Note that custom titles can also be given with this markdown syntax, with no
133-
config required:
134-
135-
```md
136-
> [!NOTE] Nota bene
137-
```
138-
139-
To customize alert colors, set in your custom stylesheet (see `"styles"`
140-
above):
141-
142-
```css
143-
.alert-foo { --color: #00ff00; }
144-
```
145-
146-
To set the same color as a default marker, use one of these variables
147-
variables:
148-
- `--alert-note`
149-
- `--alert-tip`
150-
- `--alert-important`
151-
- `--alert-warning`
152-
- `--alert-caution`
153-
154-
These would be used as follows:
155-
156-
```css
157-
.alert-bar { --color: var(--alert-tip); }
158-
```
159-
160-
For customization of all unconfigured custom markers at once, we have a color
161-
variable:
162-
- `--fallback-alert`
163-
164-
and a special class for the base alert div:
165-
- `.fallback-alert`
97+
### Reloading config
16698

16799
Vivify reads the config on startup, i.e. when you want it to reload the config,
168100
you have to restart Vivify. You can do this for example by running

0 commit comments

Comments
 (0)