v1.5.0: “A Callout Component for Nerds”

index

Our (hesitantly) first content-based component

This new version of astro-erudite, v1.5.0, introduces our first content-based component: the callout! I was a bit hesitant about adding this component because, frankly, the entire philosophy behind this project was to be as minimalistic as possible—I wanted to simply provide boilerplate to remove the “busy work” factor that often takes away from the writing process.

However, just based on some blog posts I’ve seen that use this template, I felt like there would be a universal desire just to have this component around in the case where it’d be needed. The primary inspiration came when user @rezaarezvan sent in a PR to add their site, rezaarezvan.com, to the examples section in the README. They had years upon years of accumulated notes and resources on their site, most of which were in the form of LaTeX-style academic content that requires “blocks” for things like definitions, theorems, and proofs. I sent in an encouraging reply to the PR and then started building the component:

[@jktrn] your blog posts are literally insane btw @rezaarezvan how have you written multiple textbooks worth of educational resources???

i think i might add latex-style theorem/lemma/corollary/def/proof/eg/ex/remark blocks to astro-erudite so i can accommodate for these academia-style blogs, like e.g. for exercises it’d just be a component with an expandable section to hide the answer

How does it work?

I’ve added a simple Callout.astro to src/components that now comes shipped with the template. It’s a very easy-to-read component that has an insanely long configuration scheme for all of the different types of callouts that I’ve added. Fundamentally, it follows the same paradigm as shadcn/ui which uses class-variance-authority to create different “variants” on top of a base styling scheme:

1
---
2
import { cn } from '@/lib/utils'
3
import { Icon } from 'astro-icon/components'
4
import { cva, type VariantProps } from 'class-variance-authority'
5

6
const calloutConfig = {
7
  note: {
8
    style: 'border-blue-500 dark:bg-blue-950/5',
9
    textColor: 'text-blue-700 dark:text-blue-300',
10
    icon: 'lucide:info',
11
  },
115 collapsed lines
12
  tip: {
13
    style: 'border-green-500 dark:bg-green-950/5',
14
    textColor: 'text-green-700 dark:text-green-300',
15
    icon: 'lucide:lightbulb',
16
  },
17
  warning: {
18
    style: 'border-amber-500 dark:bg-amber-950/5',
19
    textColor: 'text-amber-700 dark:text-amber-300',
20
    icon: 'lucide:alert-triangle',
21
  },
22
  danger: {
23
    style: 'border-red-500 dark:bg-red-950/5',
24
    textColor: 'text-red-700 dark:text-red-300',
25
    icon: 'lucide:shield-alert',
26
  },
27
  important: {
28
    style: 'border-purple-500 dark:bg-purple-950/5',
29
    textColor: 'text-purple-700 dark:text-purple-300',
30
    icon: 'lucide:message-square-warning',
31
  },
32
  definition: {
33
    style: 'border-teal-600 dark:bg-teal-950/10',
34
    textColor: 'text-teal-700 dark:text-teal-400',
35
    icon: 'lucide:book-open',
36
  },
37
  axiom: {
38
    style: 'border-teal-500 dark:bg-teal-950/10',
39
    textColor: 'text-teal-600 dark:text-teal-300',
40
    icon: 'lucide:anchor',
41
  },
42
  notation: {
43
    style: 'border-teal-300 dark:bg-teal-950/10',
44
    textColor: 'text-teal-500 dark:text-teal-200',
45
    icon: 'lucide:pen-tool',
46
  },
47
  theorem: {
48
    style: 'border-indigo-500 dark:bg-indigo-950/10',
49
    textColor: 'text-indigo-700 dark:text-indigo-400',
50
    icon: 'lucide:check-circle',
51
  },
52
  lemma: {
53
    style: 'border-indigo-400 dark:bg-indigo-950/10',
54
    textColor: 'text-indigo-600 dark:text-indigo-300',
55
    icon: 'lucide:puzzle',
56
  },
57
  corollary: {
58
    style: 'border-indigo-300 dark:bg-indigo-950/10',
59
    textColor: 'text-indigo-500 dark:text-indigo-200',
60
    icon: 'lucide:git-branch',
61
  },
62
  proposition: {
63
    style: 'border-indigo-300 dark:bg-indigo-950/10',
64
    textColor: 'text-indigo-500 dark:text-indigo-200',
65
    icon: 'lucide:file-text',
66
  },
67
  conjecture: {
68
    style: 'border-fuchsia-500 dark:bg-fuchsia-950/10',
69
    textColor: 'text-fuchsia-700 dark:text-fuchsia-300',
70
    icon: 'lucide:help-circle',
71
  },
72
  proof: {
73
    style: 'border-amber-500 dark:bg-amber-950/10',
74
    textColor: 'text-amber-700 dark:text-amber-300',
75
    icon: 'lucide:check-square',
76
  },
77
  remark: {
78
    style: 'border-sky-300 dark:bg-sky-950/10',
79
    textColor: 'text-sky-500 dark:text-sky-200',
80
    icon: 'lucide:message-circle',
81
  },
82
  intuition: {
83
    style: 'border-sky-300 dark:bg-sky-950/10',
84
    textColor: 'text-sky-500 dark:text-sky-200',
85
    icon: 'lucide:lightbulb',
86
  },
87
  recall: {
88
    style: 'border-sky-300 dark:bg-sky-950/10',
89
    textColor: 'text-sky-500 dark:text-sky-200',
90
    icon: 'lucide:rotate-ccw',
91
  },
92
  example: {
93
    style: 'border-sky-500 dark:bg-sky-950/10',
94
    textColor: 'text-sky-600 dark:text-sky-300',
95
    icon: 'lucide:code',
96
  },
97
  explanation: {
98
    style: 'border-sky-500 dark:bg-sky-950/10',
99
    textColor: 'text-sky-600 dark:text-sky-300',
100
    icon: 'lucide:help-circle',
101
  },
102
  exercise: {
103
    style: 'border-pink-600 dark:bg-pink-950/5',
104
    textColor: 'text-pink-700 dark:text-pink-300',
105
    icon: 'lucide:dumbbell',
106
  },
107
  problem: {
108
    style: 'border-pink-600 dark:bg-pink-950/5',
109
    textColor: 'text-pink-700 dark:text-pink-300',
110
    icon: 'lucide:alert-circle',
111
  },
112
  answer: {
113
    style: 'border-pink-300 dark:bg-pink-950/5',
114
    textColor: 'text-pink-500 dark:text-pink-200',
115
    icon: 'lucide:check',
116
  },
117
  solution: {
118
    style: 'border-pink-300 dark:bg-pink-950/5',
119
    textColor: 'text-pink-500 dark:text-pink-200',
120
    icon: 'lucide:check-circle-2',
121
  },
122
  summary: {
123
    style: 'border-emerald-600 dark:bg-emerald-950/10',
124
    textColor: 'text-emerald-700 dark:text-emerald-300',
125
    icon: 'lucide:list',
126
  },
127
} as const
128

129
const capitalize = (str: string) => str.charAt(0).toUpperCase() + str.slice(1)
130

131
const calloutVariants = cva('relative px-4 py-3 my-6 border-l-4 text-sm', {
132
  variants: {
133
    variant: Object.fromEntries(
134
      Object.entries(calloutConfig).map(([key, config]) => [key, config.style]),
135
    ),
136
  },
137
  defaultVariants: {
138
    variant: 'note',
139
  },
140
})

As such, if you feel like there’s any variant that you’re missing, it’s insanely trivial to add it yourself. It’s less trivial, however, to figure out what colors to use since I’ve essentially taken up every good Tailwind color for these!

How do I use these?

Within any src/content/blog/**/*.mdx file, you can now use the Callout component by importing it like so underneath your frontmatter:

1
---
2
title: 'v1.5.0: “A Callout Component for Nerds”'
3
description: 'A quick update introduces our first content-based component: the callout!'
4
date: 2025-04-24
5
tags: ['v1.5.0']
6
image: './1200x630.png'
7
authors: ['enscribe']
8
---
9

10
import Callout from '@/components/Callout.astro'

Then, you can use the component like so. This is just an example but you should actually read the text since it’s relevant to the article:

<Callout title="About Github-flavored alerts" variant="important">
  I know that Github typically uses the following syntax for "alerts" (which is what they call these callouts, you can see their documentation [here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)):
9 collapsed lines
  ```md showLineNumbers=false
  > [!NOTE]
  > Useful information that users should know, even when skimming content.
  ```
  The above syntax is supposed to render like this:
  <Callout>
    Useful information that users should know, even when skimming content.
  </Callout>
  I believe they do this so they can keep you within the Markdown-like syntax system. However, since this is MDX, I thought we'd be better off just using the component paradigm since it's a bit impractical to make a rehype plugin that can parse this form of syntax (also, solutions for this already exist, such as [lin-stephanie/rehype-callouts](https://github.com/lin-stephanie/rehype-callouts)). Additionally, I find it a pain to work with the `>{:md}` (the `<blockquote>{:html}` indicators for Markdown) syntax, as it makes it difficult to nest things such as code blocks within them in pure Markdown. We'll use components for now!
</Callout>

Important (About Github-flavored alerts)

I know that Github typically uses the following syntax for “alerts” (which is what they call these callouts, you can see their documentation here):

> [!NOTE]
> Useful information that users should know, even when skimming content.

The above syntax is supposed to render like this:

Note

Useful information that users should know, even when skimming content.

I believe they do this so they can keep you within the Markdown-like syntax system. However, since this is MDX, I thought we’d be better off just using the component paradigm since it’s a bit impractical to make a rehype plugin that can parse this form of syntax (also, solutions for this already exist, such as lin-stephanie/rehype-callouts). Additionally, I find it a pain to work with the > (the <blockquote> indicators for Markdown) syntax, as it makes it difficult to nest things such as code blocks within them in pure Markdown. We’ll use components for now!

Callout only supports three props:

Prop	Description	Default
`title`	The title of the callout	`undefined`
`variant`	The variant of the callout	`"note"`
`defaultOpen`	Whether the callout `<details>` box is open by default	`true`

I’ve added an insane amount of variants to this component for potentially any use case you could think of. For the more general ones, you can use the following:

Variant	Usage
Note	For general information or comments that don’t fit other categories
Tip	For helpful advice or shortcuts related to the topic at hand
Warning	For potential pitfalls or common misconceptions
Danger	For things that could potentially be destructive or harmful
Important	For things that are important to the reader’s understanding

For the potentially more academic/mathy folk, you can use the following. I’ve created specific variants that are tailor-made to be used alongside and/or nested into each other:

Variant	Usage
Definition	For defining terms or concepts
Axiom	For fundamental assumptions that are accepted without proof
Notation	For explaining mathematical notation
Theorem	For important mathematical or logical statements that have been proven
Lemma	For helper theorems used in proving larger results
Corollary	For results that follow directly from theorems
Proposition	For important statements that are less significant than theorems
Conjecture	For unproven statements believed to be true
Proof	For logical arguments that establish the truth of a theorem or lemma
Remark	For additional comments or (potentially out-of-scope) observations
Intuition	For explaining the intuitive reasoning behind concepts
Recall	For reminding readers of previously covered material
Example	For illustrating concepts with concrete examples or analogies
Explanation	For providing deeper insights or clarifying complex topics
Exercise	For practice problems or take-home challenges for the reader
Problem	For presenting problems to be solved thoroughly
Answer	For providing simple, short answers to exercises or problems
Solution	For detailed solutions to exercises or problems
Summary	For summarizing key points or concepts

Generic callouts

These are what the generic callouts look like (of course, all the text is made up):

Note (Prerequisites for advanced React development)

This tutorial assumes you’re familiar with React hooks and the component lifecycle. If you need a refresher, check out the official React documentation before proceeding.

Tip (Productivity enhancement)

You can quickly format your code by pressing Ctrl + Alt + F (Windows/Linux) or Cmd + Option + F (Mac).

Additional shortcuts include:

Action	Windows/Linux	Mac
Search	`Ctrl` + `F`	`Cmd` + `F`
Replace	`Ctrl` + `H`	`Cmd` + `H`
Save all	`Ctrl` + `Alt` + `S`	`Cmd` + `Option` + `S`

Warning (Cross-browser compatibility issues)

This API is not supported in Internet Explorer and has limited support in older browsers. Make sure to include appropriate polyfills.

1
if (!Object.fromEntries) {
2
  Object.fromEntries = function(entries) {
3
    const obj = {};
4
    for (const [key, value] of entries) {
5
      obj[key] = value;
6
    }
7
    return obj;
8
  };
9
}

See the Browser Compatibility Table for detailed information.

Danger (Critical data loss risk)

Running this command will permanently delete all files in your current directory. Make sure to back up important data before proceeding.

# This will delete everything in the current directory
rm -rf ./*
# Safer alternative with confirmation
rm -ri ./*

This operation cannot be undone and recovery tools may not be able to restore your data.

Important (Major API changes in v2.0)

Version 2.0 introduces significant API changes. You’ll need to update your existing code to use the new parameter structure.

The configure() method now returns a Promise
Authentication requires an API key object instead of a string
Event handlers use a new callback pattern

A migration example looks like the following:

1
app.configure("api-key-string");
2
await app.configure({ key: "api-key-string", version: "2.0" });
3

4
app.on('event', callback);
5
app.on('event', { handler: callback, options: { once: true } });

Mathematical callouts

Like I mentioned before, some of these variants are meant to be nested within each other. Take, for example, the following:

Definition (Continuous function)

A function $f: X \rightarrow Y$ between topological spaces is continuous if for every open set $V \subseteq Y$ , the preimage $f^{-1}(V) \subseteq X$ is open in $X$ .

Explanation (Equivalent formulations)

For metric spaces, continuity can be characterized by: $\forall \varepsilon > 0, \exists \delta > 0$ such that $d_X(x,y) < \delta \implies d_Y(f(x),f(y)) < \varepsilon$ . This captures the intuition that points close to each other in $X$ map to points close to each other in $Y$ .

Theorem (Law of Large Numbers)

Let $X_1, X_2, \ldots$ be a sequence of independent and identically distributed random variables with expected value $\mathbb{E}[X_i] = \mu < \infty$ . Then for any $\varepsilon > 0$ :

\lim_{n \to \infty} P\left(\left|\frac{1}{n}\sum_{i=1}^{n}X_i - \mu\right| > \varepsilon\right) = 0

Proof (Proof)

We’ll prove this using Chebyshev’s inequality. Let $S_n = \sum_{i=1}^{n}X_i$ and $\sigma^2 = \text{Var}(X_i)$ . By Chebyshev’s inequality:

P\left(\left|\frac{S_n}{n} - \mu\right| \geq \varepsilon\right) \leq \frac{\text{Var}(S_n/n)}{\varepsilon^2}

Since the variables are independent, we have:

\text{Var}(S_n/n) = \frac{\text{Var}(S_n)}{n^2} = \frac{n\sigma^2}{n^2} = \frac{\sigma^2}{n}

Substituting this into our inequality:

P\left(\left|\frac{S_n}{n} - \mu\right| \geq \varepsilon\right) \leq \frac{\sigma^2}{n\varepsilon^2}

As $n \to \infty$ , the right side approaches 0, which proves the theorem.

Lemma (Monotone Convergence Theorem)

Let $(f_n)$ be a sequence of non-negative measurable functions such that $f_n(x) \leq f_{n+1}(x)$ for all $n \in \mathbb{N}$ and almost all $x$ . Define $f(x) = \lim_{n \to \infty} f_n(x)$ . Then:

\lim_{n \to \infty} \int f_n \, d\mu = \int f \, d\mu

Proof (Proof)

Let $g_n = f_n \cdot \chi_E$ where $E = \{x : f(x) < \infty\}$ . By Fatou’s lemma:

\int f \, d\mu = \int \lim_{n \to \infty} g_n \, d\mu \leq \liminf_{n \to \infty} \int g_n \, d\mu = \liminf_{n \to \infty} \int f_n \, d\mu

For the reverse inequality, note that $f_n \leq f$ for all $n$ , so $\int f_n \, d\mu \leq \int f \, d\mu$ . Taking the limit:

\limsup_{n \to \infty} \int f_n \, d\mu \leq \int f \, d\mu

Combining these inequalities:

\int f \, d\mu \leq \liminf_{n \to \infty} \int f_n \, d\mu \leq \limsup_{n \to \infty} \int f_n \, d\mu \leq \int f \, d\mu

Therefore, $\lim_{n \to \infty} \int f_n \, d\mu = \int f \, d\mu$ .

I’ll add this little subgenre of variant called “example-based” callouts that have more generally a question-answer format. For the “exercise-answer” pairing, the difference is that I’d recommend you default the answer to a closed state to hide the answer from any peeping readers until they’ve actually done the work themselves. Typically, the difference between an “Answer” and a “Solution” is that the answer basically just gives you the final answer, while the solution will show you the steps it takes to get to the answer:

Exercise (Finding the derivative of a product function)

Calculate the derivative of $f(x) = x^3 \sin(x)$ using the product rule.

Answer

\frac{d}{dx}[x^3 \sin(x)] = 3x^2 \sin(x) + x^3 \cos(x)

Problem (Convergence of arithmetic means)

Prove that if a sequence $(a_n)$ converges to $L$ , then the sequence of arithmetic means $(\frac{a_1 + a_2 + \ldots + a_n}{n})$ also converges to $L$ .

Solution (Detailed proof)

Let $\varepsilon > 0$ be given. Since $(a_n)$ converges to $L$ , there exists $N \in \mathbb{N}$ such that $|a_n - L| < \frac{\varepsilon}{2}$ for all $n \geq N$ . Let $S_n = \frac{a_1 + a_2 + \ldots + a_n}{n}$ be the sequence of arithmetic means.

We can split $S_n$ as follows:

S_n = \frac{a_1 + a_2 + \ldots + a_N + a_{N+1} + \ldots + a_n}{n}

For $n > N$ , we have:

\begin{align*} |S_n - L| &= \left|\frac{a_1 + a_2 + \ldots + a_n}{n} - L\right| \\ &= \left|\frac{a_1 + a_2 + \ldots + a_n - nL}{n}\right| \\ &= \left|\frac{(a_1 - L) + (a_2 - L) + \ldots + (a_n - L)}{n}\right| \\ &\leq \frac{|a_1 - L| + |a_2 - L| + \ldots + |a_N - L| + |a_{N+1} - L| + \ldots + |a_n - L|}{n} \end{align*}

Let $M = \max\{|a_1 - L|, |a_2 - L|, \ldots, |a_N - L|\}$ . Then:

|S_n - L| \leq \frac{NM + (n-N)\frac{\varepsilon}{2}}{n} = \frac{NM}{n} + \frac{n-N}{n} \cdot \frac{\varepsilon}{2}

As $n \to \infty$ , $\frac{NM}{n} \to 0$ and $\frac{n-N}{n} \to 1$ . So for sufficiently large $n$ , we have:

|S_n - L| < \varepsilon

Therefore, the sequence of arithmetic means converges to $L$ .