Article

Building a Markdown-First Technical Blog with Modern Tools

3 min readVinay Punera
nextjsvelitetailwinduxdeployment
ListenAI narration
0:00
04:12
Click/Touch anywhere to close
Minimal neon blueprint featuring converging lines around a central signal dot.

Why This Matters

Most technical blogs drown in maintenance. A CMS here, a plugin there, database queries that crawl under load, hosting bills that creep upward-the machinery meant to support writing becomes a burden instead. We wanted to prove something simpler: a blog can be fast, maintainable, and genuinely user-friendly without sacrificing essentials or chasing the latest frameworks.

This is how we built ours.

The Architecture

There's no mystery here. The stack is straightforward and each piece solves a real problem:

Content Processing: Velite

Velite handles markdown at build time. Drop a .md file into content/posts with frontmatter (title, date, tags, optional cover image), and Velite validates the schema, calculates reading time, and passes typed content to the Next.js App Router. No manual entry. No API overhead. Files become data at build time-exactly when you need it.

Hosting: Static Export

Next.js with output: "export" pre-renders every page to pure HTML and CSS. No server, no database, no dynamic rendering. Everything is precomputed at build time and outputs as a static bundle ready for GitHub Pages, a CDN, or any static host. The result:

  • Pages load in milliseconds, even on slow networks.
  • Zero database attack surface.
  • Hosting costs pennies.
  • Uptime is boring-which is what you want.

UI Foundation: Tailwind + shadcn/ui

Clean, responsive layout without unnecessary weight. System fonts, a focused color palette, no custom imports or heavy libraries. Just accessible primitives and utility-first CSS that compounds into readable, maintainable pages.

Reader Experience: Mobile-First

We didn't optimize desktop first and shoehorn mobile in-we started with phones.

A floating navigation hub sits at the bottom-right, where thumbs naturally rest. It unfolds to reveal:

  • Search: a slide-down sheet that pulls from the top, ensuring the keyboard never covers the input. Filter by title, description, or tags. Active filters show inline; tap "Clear" and they reset.
  • Share buttons that adapt: native share sheet on phones, direct LinkedIn/copy-to-clipboard on desktop.
  • Theme toggle for dark/light mode, persisted via next-themes.
  • Navigation to home or the author page without hunting for a sidebar.

On desktop, hover over the button to unfurl the menu. Same interactions, adapted to input method. No mobile-only UI bloat.

Additional polish:

  • Reading progress bar fills as you scroll-visual feedback without getting in the way.
  • Code syntax highlighting (Shiki) compiles to static HTML at build time. Zero runtime JavaScript.
  • Post metadata (reading time, date, tags) auto-generates.
  • Theme and search state persist across page reloads.

The Win: Simplicity at Every Layer

For writers: Markdown files are the source of truth. Add a post, commit it, and the build handles the rest. No dashboard to learn. No CMS dialogs. No waiting for approval workflows. Write, save, done.

For readers: Pages load fast. Responsive layout adapts from phones to desktops without awkward breakpoints. Theme preference persists. Search is instant. Navigation is always at thumb's reach. No clutter.

For operators: Static files don't crash under traffic. No database to patch. Hosting is cheap. Uptime requires no monitoring. Deploy by pushing a folder to GitHub Pages or syncing to a CDN. That's it.

Performance Without Compromise

Static export + smart component choices = speed:

  • Sub-second page loads on any network.
  • No database queries hiding behind page renders.
  • CDN-friendly asset caching.
  • Framer Motion adds motion only where it clarifies interaction-never bloating the bundle.
  • Syntax highlighting compiles at build time, not runtime.

Next Steps

This setup scales. Add related posts, RSS feeds, or analytics without disturbing the core. The goal isn't to be first with features-it's to be right with the fundamentals.

A technical blog doesn't need to be complex. It needs to be fast, maintainable, and pleasant to read. With modern tooling (Velite, Next.js static export, Tailwind), all three are within reach. The only variable is discipline: choose simplicity at each decision point, and everything else follows.