Obsidian style callouts

README.md

@@ -42,8 +42,11 @@ issue](https://github.com/jannis-baum/vivify/issues/new/choose) or
 - [KaTeX math](https://katex.org)
 - [graphviz/dot graphs](https://graphviz.org/doc/info/lang.html)
 - [Mermaid diagrams & charts](https://mermaid.js.org)
-- [GitHub alert
-  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)
+- alert blocks
+  - 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)
+  - [syntax extensions](docs/alerts.md#custom-marker) similar to [Obsidian
+    callouts](https://help.obsidian.md/callouts)
+  - configurable [custom alerts](docs/alerts.md#configuring-alert-icons)
 - links to other files: [relative links 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#relative-links)
   as well as absolute file links

docs/alerts.md

@@ -0,0 +1,213 @@
+# Alerts usage and customization
+
+There are five default alerts, that are styled without configuration. These are the
+[GitHub
+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):
+
+```md
+> [!NOTE]
+> Lorem ipsum
+```
+
+```md
+> [!TIP]
+> Lorem ipsum
+```
+
+```md
+> [!IMPORTANT]
+> Lorem ipsum
+```
+
+```md
+> [!WARNING]
+> Lorem ipsum
+```
+
+```md
+> [!CAUTION]
+> Lorem ipsum
+```
+
+## Custom marker
+
+We have extended support similar to [how alerts work in
+Obsidian](https://help.obsidian.md/callouts) (where they are called "callouts").
+The marker can be a custom multi-word string, like this:
+
+```md
+> [!CUSTOM MARKER]
+> Lorem ipsum
+```
+
+By default, the above alert (with an arbitrary marker) is styled like `[!NOTE]`.
+This matches Obsidian's default behavior. If you want to style this separately,
+see [customizing fallback alert](#customizing-fallback-alert).
+
+## Custom title
+
+Alert title can optionally be set with the following extended syntax:
+
+```md
+> [!NOTE] A custom title
+> Lorem ipsum
+```
+
+Additionally, custom titles for markers can be set in the configuration:
+
+```json
+{
+  "alertOptions": {
+    "titles": {
+      "note": "A custom title"
+    }
+  }
+}
+```
+
+With the above example, `[!NOTE]` would *always* be rendered with the title *A
+custom title*.
+
+## Case sensitivity
+
+Marker names are matched case-insensitively, meaning `[!CUSTOM MARKER]`,
+`[!custom marker]` and `[!Custom Marker]` refer to the same type of alert.
+
+In the same way, all keys in `alertOptions.icons` and `alertOptions.titles` are
+case-insensitive.
+
+## Configuring alert icons
+
+Set custom icons for alerts by marker type like this:
+
+```json
+{
+  "alertOptions": {
+    "icons": {
+      "custom": "bell"
+    }
+  }
+}
+```
+
+When set as a string, the icon is interpreted to be a valid
+[octicon](https://primer.style/octicons/) name.
+
+This would set the octicon [`bell`](https://primer.style/octicons/icon/bell-16/)
+for alert
+`[!CUSTOM]`.
+
+### Advanced icon configuration
+
+To use icons other than octicons, the value can be set as a path to an svg
+file, for example:
+
+Absolute path:
+
+- `"custom": "/home/user/.config/vivify/icons/flower.svg"`
+
+Home as tilde:
+
+- `"custom": "~/.config/vivify/icons/flower.svg"`
+
+Path relative to Vivify config directory:
+
+- `"custom": "./icons/flower.svg"`
+
+Even a raw svg string can be set in the configuration:
+
+- `"custom": "<svg> ... </svg>"`
+
+## Customizing alert colors
+
+Colors should be customized in your custom stylesheet (via the `"styles"` option
+in the [config](customization.md)).
+
+To set any color to a custom alert type:
+
+```css
+.alert-custom { --color: #00ff00; }
+```
+
+The left-side border, title icon, and title text will be colored as `--color`.
+
+The CSS class is fully lowercased and in `kebab-case`. So for a marker with a
+multi-word name, this is how you'd set the color:
+
+```css
+.alert-my-multi-word-name { --color: #00ff00; }
+```
+
+Instead of coming up with a new hex color, you may want to match to one of the
+default alerts' colors. Use one of these CSS variables:
+
+- `--alert-note`
+- `--alert-tip`
+- `--alert-important`
+- `--alert-warning`
+- `--alert-caution`
+
+For example:
+
+```css
+.alert-custom { --color: var(--alert-important); }
+```
+
+## Examples
+
+Here are a few practical examples to achieve some types of alerts that have
+default styles in Obsidian, but not on GitHub:
+
+- `[!TODO]`
+- `[!QUESTION]`
+- `[!EXAMPLE]`
+- `[!SUCCESS]`
+- `[!FAILURE]`
+
+```json
+{
+  "alertOptions": {
+    "icons": {
+      "todo": "check-circle",
+      "question": "question",
+      "example": "list-unordered",
+      "success": "check",
+      "failure": "x"
+    }
+  }
+}
+```
+
+```css
+.alert-todo     { --color: var(--alert-note); }
+.alert-question { --color: var(--alert-warning); }
+.alert-example  { --color: var(--alert-important); }
+.alert-success  { --color: var(--alert-tip); }
+.alert-failure  { --color: var(--alert-caution); }
+```
+
+## Customizing fallback alert
+
+Any custom alert that hasn't been configured will have the same icon and color
+as `[!NOTE]`. If you want a whole separate color and icon for unconfigured
+alerts, use these options:
+
+```json
+{
+  "alertOptions": {
+    "fallbackIcon": "alert"
+  }
+}
+```
+
+> [!NOTE]
+> `"fallbackIcon"` is a separate option outside of the `"icons"` table, but
+> accepts the same type of icon value as the [icon
+> customization](#configuring-alert-icons).
+
+For the color, any alert that doesn't have a "known" marker gets a CSS class as
+`.fallback-alert`. So, to customize the color:
+
+```css
+.fallback-alert { --color: #ff0000; }
+```

docs/customization.md

@@ -74,6 +74,28 @@ keys:
   }
   ```
 
+- **`"alertOptions"`**\
+  Options to customize
+  [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)
+  beyond the 5 default ones used by GitHub. You may also know this feature by
+  the name of [Obsidian callouts](https://help.obsidian.md/callouts).
+
+  ```json
+  "alertOptions": {
+    "icons": {
+      "foo": "zap",
+      "bar": "./icons/flower.svg"
+    "titles": {
+      "bar": "Tip of the day"
+    },
+    "fallbackIcon": "alert"
+  }
+  ```
+
+  For alerts customization, see [full explanation with examples](alerts.md).
+
+### Reloading config
+
 Vivify reads the config on startup, i.e. when you want it to reload the config,
 you have to restart Vivify. You can do this for example by running
 

package.json

@@ -7,7 +7,7 @@
     "viv": "VIV_PORT=3000 node --loader ts-node/esm src/app.ts",
     "lint": "eslint src static",
     "lint-markdown": "markdownlint-cli2 --config .github/.markdownlint-cli2.yaml",
-    "test": "node --loader ts-node/esm tests/unit/cli.ts",
+    "test": "node --loader ts-node/esm --test tests/unit/cli.ts tests/unit/alerts.ts",
     "deduplicate": "yarn-deduplicate"
   },
   "type": "module",
@@ -28,7 +28,6 @@
     "markdown-it-emoji": "^3.0.0",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-front-matter": "^0.2.4",
-    "markdown-it-github-alerts": "^1.0.0",
     "markdown-it-inject-linenumbers": "^0.3.0",
     "markdown-it-mark": "^4.0.0",
     "markdown-it-sub": "^2.0.0",

src/config.ts

@@ -19,6 +19,11 @@ type Config = {
     katexOptions?: any;
     tocOptions?: any;
     /* eslint-enable @typescript-eslint/no-explicit-any */
+    alertOptions?: {
+        icons?: Record<string, string>;
+        titles?: Record<string, string>;
+        fallbackIcon?: string;
+    };
 };
 
 // fills in values from config file config that are not present
@@ -71,9 +76,10 @@ const getFileContents = (
     return getFileContent(paths);
 };
 
+let configBaseDir: string | undefined = undefined;
+
 const config = ((): Config => {
     let config = undefined;
-    let configBaseDir = undefined;
     // greedily find config
     for (const cp of configPaths) {
         if (!fs.existsSync(cp)) continue;
@@ -109,6 +115,7 @@ const config = ((): Config => {
     return config;
 })();
 
+export { config, configBaseDir };
 export default config;
 
 export const address = `http://localhost:${config.port}`;