Welcome to Notice

The first post: why Notice is a static blog, what it is built with, and how each piece gets written.

Cover image for Welcome to Notice with a deep blue gradient
Cover image for Welcome to Notice with a deep blue gradient

Welcome to Notice

Notice is where I write down what I learn while building things: a bit of Cloudflare, a bit of Astro, and some notes on writing documentation that my future self can actually read. There is no recommendation feed, no email popup, no "subscribe to continue reading" wall. Just text, plus the occasional file when a post needs one.

This first post is both a welcome and a short description of how the site works. If you are here for the engineering, it gives you enough to rebuild something similar over a weekend. If you are just passing through, there is a reading list at the end.

Why a static blog?

I have run three kinds of blog over roughly seven years. The first was WordPress. The second was a Next.js app with its own database. The third — the one you are reading — is pre-built HTML pushed to the edge.

The lessons were simple:

  • The content of a personal blog changes slowly. A few posts a month is a lot.
  • The thing that changes quickly is the layout, and the layout can be rebuilt at deploy time.
  • Every dynamic layer you add costs you maintenance time, security patches and server money.
  • If a page is text, a 12 KB HTML file is faster than anything you will write in JavaScript.

Put differently: a blog does not need a database to serve readers. It needs one to write posts. Separating those two jobs is the whole idea behind Notice.

What is inside

The writing side is a headless CMS on Cloudflare Workers, with an API for creating posts, uploading covers and attaching files. The reading side is Astro, built to static HTML, deployed on the same infrastructure. No server wakes up at 3 a.m. because a bot crawled a page.

Layer Technology Job
Writing SonicJS on Workers, D1 Store posts, track draft/published state
Assets R2 behind /files/:key PDFs, markdown notes, cover images
Rendering Astro, static output Turn markdown into HTML
Delivery Workers static assets Edge cache, no origin server
Search None yet, possibly never A grep over the repo is enough

What a post looks like

Every post is a document with a fixed set of fields: title, slug, excerpt, markdown body, cover, attachments, tags, author and locale. Vietnamese and English versions are separate documents linked by a translationOf field. It is slightly manual, and very easy to reason about when you open the API.

A minimal create call looks like this:

{
  "title": "Welcome to Notice",
  "slug": "welcome-to-notice",
  "status": "published",
  "data": {
    "excerpt": "A short post about why Notice exists.",
    "locale": "en",
    "tags": ["intro", "guide"],
    "author": "guest-editor"
  }
}

The content field is trimmed here. In practice it is plain markdown, exactly like the file you are reading.

Attachments

I prefer keeping long material as a separate PDF or markdown file instead of stuffing everything into the post. This post has two:

  1. huong-dan-tom-tat.pdf — a one-pager you can print and pin above a desk.
  2. nguon-tham-kieu.md — a list of sources and unfinished notes.

Both live in R2 and are served from /files/. No third-party embeds, no vendor PDF viewer.

How I write

The current workflow has four steps, and the third one matters most:

  1. Draft in a markdown file, without opening a web editor.
  2. Read it again at least a day later. A third usually disappears.
  3. Ask a real reader, or a language model playing a real reader.
  4. Publish, then fix typos through the API when you find them.

Writing is for understanding, not for being read. If a paragraph does not help you understand something, it will not help a reader either.

Step three is the one people skip. I once published a post about D1 migrations without a test reader, and it took two weeks to learn that a command in it had its arguments in the wrong order. Since then, every post gets at least one outside read.

If you are new, these three are a reasonable starting point:

And if you only want one post before leaving, this one is enough. Thanks for stopping by.