ikoonman.io

A blog that is only a folder of Markdown files

·1 min read

  • Architecture
  • Systems

A blog that is only a folder of Markdown files

There is no database here, no CMS, and no admin interface. Publishing works like this:

  1. Add a Markdown file to blog/.
  2. Run npm run build.
  3. Serve dist/.

The filename becomes the URL. blog/hello-ikoonman.md is published at /blog/hello-ikoonman/, unless the frontmatter overrides the slug.

Why keep it this small

Every feature added to a publishing tool is a feature that has to keep working for as long as the writing does. Markdown files outlive engines, so the engine should be replaceable in an afternoon.

The blog exists to publish ideas, not to become another software platform.

What the build does

flowchart TD
    Scan[Scan blog/] --> Parse[Parse frontmatter]
    Parse --> Skip[Skip drafts]
    Skip --> Render[Markdown to HTML]
    Render --> Pages[Write post pages]
    Pages --> Index[Build index and feed]
    Index --> Assets[Copy public assets]

Images live in public/ and are referenced from a post with a normal absolute path, so nothing about them is special either.