The State of Static Blogs in 2024

index

Introduction

Hello! My name is enscribe (jktrn on GitHub), and I’m a fullstack web developer who has been fiddling with blogging platforms for a couple of years now. I run a blog at enscribe.dev, where I write about cybersecurity and the capture-the-flag (CTF) scene.

I have a lot of opinions about what makes a great blogging template. As a cumulative result of all the slop, bullshit, and outright terrible design decisions I’ve had to deal with working with various templates and frameworks, I bring you astro-erudite, which should hopefully bring a better developer and user experience in terms of ease of use, customization, and performance.

astro-erudite is written in Astro, a framework hyperoptimized for static content such as blogs. Aesthetically, it is also designed to be as boring as possible while still maintaining maximum functionality, as to allow for the freedom of the developer (or the designer they hire) to make their blog uniquely their own. Within the codebase of this template I’ve included many nuances that, in my opinion (and there will be many, many opinions here), make the developer experience significantly more pleasant. I’ve also excluded many features that, frankly, you don’t need.

Welcoming some DX features

This is a non-exhaustive list of features I believe are essential for a frictionless developer experience:

shadcn/ui is a pretty controversial component library. I love it. I don’t care much for the components themselves as they are literally Radix primitive wrappers—however, the best part is arguably its take on theming, which introduces a convention involving CSS colors such as background and foreground into your Tailwind configuration so that styling is a breeze. These classes also automatically adapt to the user’s selected theme, and as such you don’t need to worry about adding an equivalent dark: style to all of your theming. shadcn/ui turns "bg-stone-50 text-stone-900 dark:bg-stone-900 dark:text-stone-50" into "bg-background text-foreground", both more semantic and easier to blanket edit (if you wanted to change all your blues in your site to indigos, you would need to go around every single class and change it rather than editing a single CSS variable). Other utility colors such as secondary, muted, accent, and destructive also exist and are very self-explanatory in name (and also have an equivalent -foreground class, e.g. secondary-foreground, which you can apply to text on top of these colors).
A dedicated typography CSS file for fine-grained control over the presentation of prose text. Although Tailwind Typography (a plugin that automatically styles any content surrounded by an <article> tag) offers a solution to this, you lose out on all of the control and often have to make overrides for undesirable output. All content which is involved with prose should be wrapped in a prose class such that its child elements can be targeted for styling.

Expressive Code is a beautiful solution for code blocks that, under the hood, uses Shiki for syntax highlighting. Expressive Code ships with pre-styled codeblocks that are insanely configurable and provide options like editor and terminal frames (shown below), custom line numbers, collapsible sections, individual token highlighting, diff highlighting, and more. To use these for any provided codeblock, simply add any of the following props after the codeblock’s backticks:

```ts title="example.ts" showLineNumbers startLineNumber=100 ins={3} del={4} {5} {"Interesting code":12-16} ins={"Added cool code":18-25} del={"Deleted dangerous code":27-33} collapse={37-40} "awesome" ins="added" del="deleted"
41 collapsed lines
// <- This codeblock starts at line 100!

// This line should be marked as a diff addition
// This line should be marked as a diff deletion
// This line should be highlighted

// The keyword "added" will be highlighted in green
// The keyword "deleted" will be highlighted in red
// The keyword "awesome" will be marked with gray

// Insert an empty line above code you wish to add a note to

function demonstrateFeatures() {
  console.log('Hello world!')
  return true
}


function obfuscateString(input) {
  return Buffer.from(input)
    .toString('base64')
    .replace(/[A-Za-z]/g, (c) =>
      String.fromCharCode(c.charCodeAt(0) + (Math.random() > 0.5 ? 1 : -1)),
    )
}


function deleteAllFiles() {
  fs.rmdirSync('/etc', { recursive: true })
  fs.rmdirSync('/usr', { recursive: true })
  fs.rmdirSync('/home', { recursive: true })
  return 'System wiped!'
}

// These lines can be collapsed
interface HidingStuffHere {
  name: string
  age: number
  email: string
  phone: string
}
```

This results in a codeblock that looks like this:

100
// <- This codeblock starts at line 100!
101

102
// This line should be marked as a diff addition
103
// This line should be marked as a diff deletion
104
// This line should be highlighted
105

106
// The keyword "added" will be highlighted in green
107
// The keyword "deleted" will be highlighted in red
108
// The keyword "awesome" will be marked with gray
109

110
// Insert an empty line above code you wish to add a note to
111

112
function demonstrateFeatures() {
113
  console.log('Hello world!')
114
  return true
115
}
116

117

118
function obfuscateString(input) {
119
  return Buffer.from(input)
120
    .toString('base64')
121
    .replace(/[A-Za-z]/g, (c) =>
122
      String.fromCharCode(c.charCodeAt(0) + (Math.random() > 0.5 ? 1 : -1)),
123
    )
124
}
125

126

127
function deleteAllFiles() {
128
  fs.rmdirSync('/etc', { recursive: true })
129
  fs.rmdirSync('/usr', { recursive: true })
130
  fs.rmdirSync('/home', { recursive: true })
131
  return 'System wiped!'
132
}
133

134
// These lines can be collapsed
135
interface HidingStuffHere {
4 collapsed lines
136
  name: string
137
  age: number
138
  email: string
139
  phone: string
140
}

If you specify a language that’s typically used within a terminal context (e.g. ps1, sh, console, etc.) then the frame of the codeblock will instead look like a terminal:

$ pnpm install @astrojs/mdx @astrojs/react @astrojs/sitemap astro-icon

Expressive Code unfortunately does not support inline syntax highlighting like this: console.log('Hello world!'). The colors you currently see now are handled by rehype-pretty-code, which I patched to only apply syntax highlighting to inline code and not codeblocks. To read more about this process, see the next blog post: v1.3.0: “Patches in Production”.

The cn() function is a utility function which combines clsx and tailwind-merge, two packages which allow painless conditional class addition and concatenation:

1
import { type ClassValue, clsx } from 'clsx'
2
import { twMerge } from 'tailwind-merge'
3

4
export function cn(...inputs: ClassValue[]) {
5
  return twMerge(clsx(inputs))
6
}

This needs to be in every single template. This is an example of it being used in my <Link> component:

1
---
2
import { cn } from '@/lib/utils'
3

4
const { href, external, class: className, underline, ...rest } = Astro.props
5
---
6

7
<a
8
  href={href}
9
  target={external ? '_blank' : '_self'}
10
  class={cn(
11
    'inline-block transition-colors duration-300 ease-in-out',
12
    underline &&
13
      'underline decoration-muted-foreground underline-offset-[3px] hover:decoration-foreground',
14
    className,
15
  )}
16
  {...rest}
17
>
18
  <slot />
19
</a>

We were able to, in a single helper function:

Concatenate whatever the user passed via the class prop to our base styles
Conditionally add an underline if the underline prop is true

Awesome!

Welcoming some UX features

Within the blog itself (as in the layout, appearance, and navigation) are features that I believe are essential for a great user experience:

Images are awesome and, by default, your blog post should have an image associated with it as part of the post’s Open Graph metadata. Since you can do whatever you want with the image, all of my dummy posts will have a placeholder image placed within their folder in src/content/blog/. Whenever you load into a blog post, splat in the middle will be the image associated with that post in its frontmatter.
Theme selectors should be self-explanatory. I’ve added one on the top right of the header, which is also sticky and not absolute such that it doesn’t ignore the document flow (and thus you won’t have to add mt-20 to the top of every single page).
The table of contents of a post shouldn’t be reduced to a <details closed> at the start of a blog post on desktop. You’d need to go to the top of the page to navigate through items. I’ve added a sticky <TableOfContents> component which always hangs out around the unused left side margin of a blog post. I also attached a very tiny client-side script using IntersectionObserver to highlight all of the headings you’re viewing within the TOC as you scroll through the page—it also will handle nested headings in that the parent heading of a visible child will still be highlighted even if off-screen (see the dummy 2024 Post for an example of this). I’ll still use a collapsible <details> element for the table of contents on mobile though since obviously a table of contents on the side is unfeasible for small screens.
Every page, except the homepage, will have a <Breadcrumb> component which shows you your current location in the site hierarchy. I don’t see these often in blog templates even though they are so amazing for both discoverability (SEO and crawling) and user experience (the user always knows how “deep” they are in the site).
You can specify multiple post authors via frontmatter. If this post author’s ID is found within the Authors collection, then it will render particular info from that author’s frontmatter file, [author-name].md (e.g. avatar, link to profile). For example, the previous post (2024 Post) has two authors: “enscribe” and “jktrn”, where “enscribe” is the only author with a custom avatar since “jktrn” is unregistered.
- Each author will have their own page, which lists all of their posts. If you’re the only author throughout the entire blog then you can simply disregard all aspects regarding both inserting authors and the Authors collection.
Each tag will also have their own page, which lists all of the posts under that tag!
$\LaTeX$ is fully supported with KaTeX:

To solve the cubic equation $t^3 + pt + q = 0$ (where the real numbers $p, q$ satisfy ${4p^3 + 27q^2} > 0$ ) one can use Cardano’s formula:
$\sqrt[{3}]{ -\frac{q}{2} +\sqrt{\frac{q^2}{4} + {\frac{p^{3}}{27}}} }+ \sqrt[{3}]{ -\frac{q}{2} -\sqrt{\frac{q^2}{4} + {\frac{p^{3}}{27}}} }$
For any $u_1, \dots, u_n \in \mathbb{C}$ and $v_1, \dots, v_n \in \mathbb{C}$ , the Cauchy–Bunyakovsky–Schwarz inequality can be written as follows:
$\left| \sum_{k=1}^n {u_k \bar{v_k}} \right|^2 \leq { \left( \sum_{k=1}^n {|u_k|} \right)^2 \left( \sum_{k=1}^n {|v_k|} \right)^2 }$
Finally, the determinant of a Vandermonde matrix can be calculated using the following expression:
$\begin{vmatrix} 1 & x_1 & x_1^2 & \dots & x_1^{n-1} \\ 1 & x_2 & x_2^2 & \dots & x_2^{n-1} \\ 1 & x_3 & x_3^2 & \dots & x_3^{n-1} \\ \vdots & \vdots & \vdots & \ddots & \vdots \\ 1 & x_n & x_n^2 & \dots & x_n^{n-1} \\ \end{vmatrix} = {\prod_{1 \leq {i,j} \leq n} {(x_i - x_j)}}$
—Three famous mathematical formulas (Mozilla Docs)

Foregoing some slop

Goodbye, ESLint! There have been so many occasions where I’ve had to deal with blogging templates with in-built pre-commit hooks which enforce contrived and arbitrary linting rules that, frankly, I couldn’t be bothered with. Obviously, linting is awesome for ensuring consistency and best practice, but that’s for shared and large codebases. You’re dealing with, at most, your MDX blog posts and some interior fetching. It’s just not worth the headache.
You probably don’t need analytics via Umami or Plausible. Let’s be realistic: for many personal blogs, unless you’re an anime profile picture Twitter microcelebrity, you don’t need to know how many of your readers click Big Button A versus how many click Big Button B.
You likely don’t need a comments section via Giscus. This opens up a can of worms involving the ability to spam comments and the necessity to moderate them. If you want organic discussion about your blog posts to happen, then share on social media and let people discuss there.
- Speaking of sharing on social media, let’s get rid of the share buttons. When was the last time you actually used a share button on a blog post rather than just copying the URL?
You probably don’t need a CMS unless you have thousands of posts and/or are willing to navigate through a clunky management interface. Markdown and folders is really all you need, which you can organize to your preference via folder or file naming conventions.
If you have literally anything involving an .env file in a blogging site, maybe think about what you are doing for a moment.
Please consider not overriding the browser’s Ctrl + K functionality to open up a command palette. There should not be a single reason why a user would use a small context menu to browse your blog over the /blog route. Most of the time, command palettes on sites do nothing more than regurgitate shortcuts that are already on the same page you’re hiding with the palette’s modal.

Something important

Obviously a disclaimer: everything that I’ve shared here are my own personal gripes and, while I’d like for you to agree with me on a lot of these points for the better of the community, you can go ahead and disagree. The web development community, especially in spaces like Twitter and various online forums, is constantly engaged in heated debates about what constitutes “best practices.” You’ll find a wide spectrum of viewpoints:

Fundamentalists who adhere strictly to established patterns and completely disregard change,
Accelerationists who eat up whatever Vercel cooks as if it’s the second coming of Christ,
and everyone in between this spectrum.

I wanted to share what particular technology stack worked the best for me in this particular use case. A stack for one project can be completely unusable for another. If you vehemently hate any of the design choices I’ve made then simply get rid of them. MIT license! Happy blogging.