Rohan Roy
← All writings

How blog works in this site

Blog posts are plain markdown files in the repo. This post explains the mechanism and serves as a guide on how to write posts, what frontmatter to use, and how the list page, routes, and table of contents are generated.

Every post is a single markdown file in the directory content/blog/, and the site turns those files into pages at build time.

Creating a post

Add a file like content/blog/post.md. The filename becomes the URL: that file would be served at /blog/post. Keep filenames lowercase with hyphens.

Each file starts with frontmatter, then markdown content:

---
title: "My post"
date: "2026-09-06"
description: "One or two sentences shown on the list page and under the title."
updated: "2026-09-10"
tags:
  - notes
---

Your content here...

Frontmatter fields

  • title — the post title, shown on the list page and as the page heading.
  • date — the publish date in YYYY-MM-DD format. Posts are sorted newest first, and the date is shown above the title on the list page.
  • description — a one- or two-sentence summary. It appears on the list page, under the title on the post page, and in the page metadata for link previews.
  • updated — optional. Same format as date. When present, the post page shows "Updated …" next to the publish date.
  • tags — optional list. Shown at the bottom of the post and under the description on the list page.

Only title and date are truly required. Everything else degrades gracefully when omitted.

Writing content

The body is all markdown: headings, lists, quotes, tables, task lists, and fenced code blocks all work.

Headings and the table of contents

## and ### headings do two things automatically:

  1. They get anchor ids, so ## How it works is linkable as #how-it-works.
  2. They appear in the "On this page" table of contents — in the left sidebar on wide screens, in a box above the article on narrow ones.

Because of that, a good structure is one #-free body that starts at ## for sections and uses ### for subsections. The sample headings in this post are doing exactly that.

Blockquotes, inline code, and emphasis render as you'd expect from the prose styling shared across the site.

How the pipeline fits together

Three pieces do all the work:

  • The post loader reads every markdown file, parses its frontmatter, extracts the table of contents from ## / ### headings, and sorts posts newest first.
  • The writings index lists every post with its date above the title.
  • The article template renders each post as styled HTML, generates heading anchors so the table of contents can link to sections, and pre-renders every route at build time.

That means adding a post requires no code changes: drop in the file, and the list page, route, metadata, and table of contents update themselves.

Tagged: documentation

Thoughts on this?

Reply by email