What I want from a website

Web development is a mess. In my previous attempts at a portfolio and/or blogging site, I’ve always spent more time fighting the “features” of some template rather than writing actual content. Here are some examples of such “features:”

• A comments section, e.g. Giscus or Disqus. For most blogs, this is a moderation liability.

• Content management systems (CMS). Good file management and naming conventions are enough for me. I don’t want to be forced into any CMS idiosyncracies either.

• Share buttons. I have never used these.

• Analytics like Umami. This is just overkill.

• Newsletter integrations. RSS is enough.

• Too many prebuilt components, e.g. twenty different carousels. It’s just overchoice. If I need a component someday, I can make or look for one then.

• Multi-author management systems. Git and pull requests suffice.

• Too many libraries. Why do you need shadcn, MUI, DaisyUI, and RadixUI?

On the other hand, there are some features I consider essential to any website:

• constants file(s). Both for styling, e.g. a single .css for all colors, and component data. More on this later.

• Open Graph metadata, and other basic SEO features. Its good for searchability.

• Affordable navigation stuff, e.g. a navbar, table of contents, etc.

For blogs in particular, I consider these features essential:

• Math equation support, e.g. via KaTeX.

• Code blocks with syntax highlighting, e.g. via Shiki.

• Mobile support. That is, everything resizes without losing functionality.

• A table of contents that’s always accessible. These should not just be at the start and end, even on mobile.

• Separation of content and style. I should not be styling components in the same file as my post text data.

  • On that note, .mdx or similar for content. Not .md. I should have easy access to JavaScript even in my content files, for components and the like.

What this website has

This site is built off Erudite. It satisfies every requirement above, with only minor modifications. Its design document significantly overlaps this one. I strongly recommend this template.

Let me show off this site’s features using a continuous article series. Each part is rendered on this page when you follow any of these links:

1. The technicals

2. Styling and typography

3. Components

Why Astro?

From the start I knew I wanted Astro as my web framework. There were three main reasons for this:

1. UI-agnostic. Astro allows you to use React, Svelte, Vue, Solid, etc all in one site. As someone new to web development, this means I can try all the UI frameworks without committing to one early on.

2. Server-first. In Astro, the server renders as much content into HTML as possible. This is ideal for static sites like blogs.

3. Islands architecture. Astro separates each page into different islands or components, each of which can be static or interactive and use almost any UI framework. This is performant while allowing me to choose the best framework for each component.

I didn’t want to start from nothing, so I went through every blog template on Astro themes. Erudite was the best fit at the time.

The tech stack

Astro is the web framework, with MDX as the main content format. Satteri is the Markdown/MDX pipeline. Temml renders math, and Expressive Code handles code. The site is written in TypeScript and hosted on GitHub through GitHub Pages.

The flowchart for a typical blog post is:

1. Brainstorming a topic. Surprisingly the easiest part.

2. Making the post’s banner art in Figma. This is second because I find illustrating forces me to concretely narrow down the topic in a way text cannot do.

3. Writing directly in .mdx using an IDE. This takes the most time.

4. Making custom components for the post. It’s my unspoken rule to always make a new component for every post, both to practice reviewing AI-generated code and to give each post some individuality.

5. All this is done in a Github branch. When the first draft is ready, I make a pull request. If a post needs edits after that, I do it in the same branch and PR it back into main.

The Git branches allow me trace what post inspired what change, and work on multiple posts simultaneously.

On media

I try to store all images in WebP if its not a vector and SVG if it is. I’m having doubts about SVG though. Inspect the blog post banner file size and you’ll see why. I hope to never upload a video or large media file directly here, providing links to an external service instead.

The color palette

I spent more time thinking about the site’s color palette than any other design decision. This was largely because I wanted a palette that:

1. Had a primary color that was visible in both light and dark mode.
2. Had a primary color with many subtle shades, making light and dark mode palettes easy.
3. Had a wide available color gamut on most displays.

I did this by experimenting with okclh(L C H / a), which controls

• L, perceived lightness, dark to bright $[\mathrm{0,1}]$;
• C, chroma, dull to vivid $[0,\infty )$;
• H, hue, or the color angle in polar coordinates $[0^{\circ },{360}^{\circ }]$;
• a, alpha, transparent to opaque $[\mathrm{0,1}]$.

To create a cohesive palette, I wanted all colors to have the same hue color. Furthermore, between dark and light mode, different colors should have the same relative chroma, but have “inverted” lightness.

I’m still working on this, but here’s what I got so far:

Styling images

Black and white images are automatically inverted on light/dark mode though CSS’ invert.

Post banners get special treatment. The art, text, and watermark are stored as an svg with transparent background. Between light and dark mode, I just swap out the background color. Here’s what the banner looks like on both themes:

Unfortunately, open graph previews don’t work well with this. So I supply the same banner with background for this.

Styling text

Almost all Markdown syntax is built-in. This includes bold, italics, $\text{equations}$, and code. Satteri feeds both inline and block code into a shared Expressive Code renderer. Spoiler tags like this are custom inline components.

Sections are done with #, ##, and so on. Tables are just like markdown:

Code blocks are styled by Expressive Code, which allow me to do things like:

1
function demo() {
2
  console.log('this line is marked as deleted')
3
  // This line and the next one are marked as inserted
4
  console.log('this is the second inserted line')
9 collapsed lines
5
  console.log('C')
6
  console.log('O')
7
  console.log('L')
8
  console.log('L')
9
  console.log('A')
10
  console.log('P')
11
  console.log('S')
12
  console.log('E')
13
  console.log('D')
14
  return 'this line is marked and all code in between is collapsed'
15
}

Typography

The current default fonts are the variable IBM Plex Sans and Mono. It used to be Inter, which I think looks slightly better than IBM Plex. However, Inter is unfortunately very generic and overused right now.

Serif vs sans-serif was an unexpected point of contention in this website’s design. Half of the people I asked feedback from preferred sans-serif, because it looks modern and clean. The other half argued serif was more academic and better suited my purposes.

Here’s a screenshot of an old version of the site with serif font:

Honestly, I thought it looked disgusting and too much like the default font.

Other typography things: Titles are in titlecase. Sections have the first word and proper nouns capitalized. All files and technical names should be slugified (lowercase with - as spaces).

How to use components

Within any .mdx, import a custom component and pass in the required parameters. Callouts are lighter-weight Satteri directives and need no import:

1
:::important[About callouts]{closed}
2
  Callouts signify different types of content to the reader
3
:::

Here’s how it looks rendered. Notice the closed attribute makes the callout closed by default, ideal for e.g. solutions to puzzles.

I can then call out the component as a hyperlink. Here’s how this line looks in code:

1
I can then call out the component as a [hyperlink](#about-callouts).

By default, the callout’s id is its slugified title, but an explicit directive ID can be supplied too.

Callouts

Callout color and icons are data driven, so it’s easy to add a bunch of varieties:

Post-specific components

Almost every post has a custom callout made just for it. For example, here’s a music sheet component using LilyPond with tablature support:

LilyPond engraves the score during the site build, so the page ships a compact SVG rather than a browser-side music renderer.

Here’s a logic grid component for my post Logic Grids as Data Structures:

It’s fully functional and inputs persist even over page reloads.

I want each post to have at least one unique component. I think it adds a lot of interaction and individuality.