MD Grid Engine
A content engine for building fast, file-first websites
MD Grid Engine is a custom system that transforms Markdown and MDX files into the structured, responsive pages of this website. It removes the need for a heavy, database-driven CMS while keeping the flexibility to build complex layouts through simple text editing. It also serves a second role: it is designed to become the interface layer for Architect, where the same content system can be used to present AI plans, execution traces, and decision outcomes.
The Problem: The friction between content and layout
Most sites force a choice between a heavy CMS and manually coding each page. For this portfolio, I needed a simpler workflow: content should be as easy to manage as a README file, but the frontend should still be able to render structured layouts and support more complex interfaces. That included not only normal portfolio pages, but also a future UI for Architect, where the system needs to display plans, execution traces, and decision outcomes in a clear way.
The Outcome: Structured content without CMS overhead
The engine provides a file-first workflow that treats content as code while keeping the presentation layer consistent and reusable.
- Fast updates: Content lives in the filesystem, so changes can be made directly without database overhead.
- Design consistency: A centralized component registry keeps layouts and UI patterns consistent across the site.
- Dual-purpose UI foundation: The same grid-based system that powers this portfolio is designed to support future interfaces for Architect.
Core Architecture
File-First Processing
The engine is built on the Next.js App Router and uses a custom MDX processing pipeline:
- On-demand compilation: A runtime MDX compiler transforms files into React components at request time, with plugins for formatting and syntax highlighting.
- Filesystem provider: A custom provider (
FsContentProvider) resolves URL slugs to file paths, supports nested directories, and expands reusable content partials ({{ partial:id }}). - Dynamic routing: Leverages the Next.js App Router (
[...slug]/page.tsx) to dynamically render any MDX document from thecontent/directory, with static params generated recursively.
Key Features
Structured UI Control
These design choices keep the system stable and easy to maintain:
- Typed metadata: A validation layer ensures frontmatter fields such as
title,description, anddatesare consistently typed and usable across the site. - Component registry: Standard text tags can be mapped to reusable React components such as
<Grid>,<Card>, and<Figure>, keeping the layout consistent. - Reliability testing: The engine is supported by unit and end-to-end tests to keep the content pipeline stable as the site grows.
- Styling Presets: The system uses Tailwind CSS combined with custom utility classes (
.prose-root,.preset-panel-wide) to keep layouts consistent and on-brand across all content types.
Impact & Status
The MD Grid Engine is 100% complete and in production. It currently powers this entire portfolio and has proven that a file-first approach can support a fast, structured website without the maintenance burden of a traditional CMS.
Its broader value is that it already solves two related problems with one system: it gives this portfolio a clean, maintainable content workflow today, and it provides a ready UI foundation for exposing Architect’s backend logic in a more readable and structured way.