Building a Premium MDX Ecosystem in Next.js

A digital garden is only as powerful as its reading experience. As I began migrating my technical deep-dives and cloud architecture blueprints to aqmalkhatiman.dev, I quickly realized that a standard Markdown parser wasn't going to cut it.

Technical documentation requires visual hierarchy, pristine syntax highlighting, and structural clarity. Relying on basic <pre> and <code> tags breaks the "Senior System Architect" illusion. So, for Phase 1.3.0 of my site's architecture, I decided to upgrade the internal reading experience.

The Architectural Goal

The objective was to transform raw .mdx files (organized strictly using the P.A.R.A methodology) into a premium, VS Code-like reading environment without introducing the bloat of a Headless CMS or a heavy database like PostgreSQL.

The solution? A statically compiled pipeline using Next.js (App Router), injected with custom plugins.

The Tech Stack Upgrade

To achieve this "VS Code in the browser" feel, I integrated two critical tools into my MDX compilation engine:

1. rehype-pretty-code: Powered by Shiki, this plugin provides highly accurate syntax highlighting. I locked the theme to github-dark to match my site's strict minimalist, Apple-esque, high-contrast design language.
2. remark-gfm: Essential for GitHub Flavored Markdown support, allowing me to render tables, task lists, and autolinks natively.

Custom Components Injection

Markdown is great, but sometimes you need bespoke UI elements. I built a custom, Tailwind-styled <Callout /> component to highlight warnings or architectural tips.

By passing these custom React components directly into the MDX provider, I can seamlessly invoke them inside any local .mdx file.

// Example of injecting the custom component
import { Callout } from "@/components/mdx/Callout";
 
const components = {
  Callout,
  // Mapping standard HTML elements to Tailwind classes
  h1: (props) => <h1 className="text-3xl font-bold mt-8" {...props} />,
  pre: (props) => <pre className="p-4 rounded-lg bg-zinc-950 overflow-x-auto" {...props} />,
};

The Vibe Coding Workflow

This entire Phase 1.3.0 upgrade was mapped and executed using my Multi-AI Vibe Coding protocol. Gemini acted as the Principal System Architect handling the macro-level blueprints, while Claude (via Cursor IDE's Agent mode) handled the micro-level execution and dependency management.

Biology sets the constraints, but we write the code. The result is a fast, scalable, and beautifully rendered digital garden ready for more heavy-duty technical writing.