Inside RuneAI.tech: The MDX UI System That Powers Every Page

Every page on RuneAI.tech starts as an MDX file and ends as a fully rendered, SEO-optimized HTML document with structured data, internal links, and layout-stable ad placements. The system that makes this happen is not a single library or plugin. It is a set of interlocking components built on Next.js 16 App Router, MDX Remote, Supabase, and a custom rendering pipeline that handles articles, tool reviews, comparison pages, and alternative roundups through a unified architecture.

This article walks through how that system works, from raw MDX content to the final page a search engine crawler sees.

The Content Layer: MDX Files and Supabase

Content on RuneAI.tech lives in two places. Editorial content like articles, guides, and comparison write-ups is stored as MDX files in the repository under the content/ directory. Structured data like tool metadata, author profiles, category taxonomies, and user-facing ratings lives in Supabase Postgres tables.

This split is intentional. MDX files are version-controlled, diffable, and reviewable in pull requests. Database records are queryable, joinable, and updatable without deployments. When a page renders, the server component reads from both sources and merges them into a single props object that feeds the page template.

The MDX files follow strict frontmatter schemas. An article file includes title, slug, description, excerpt, publish and update dates, category, tags, cover image path, author name, and a FAQ array. The parser at lib/content/mdx-parser.ts validates every field, computes derived values like estimated read time and word count, and strips duplicate H1 headings if an author accidentally includes one.

Tool content files follow a different schema with fields for pricing tiers, feature lists, platform availability, and rating breakdowns. Comparison files define the two tools being compared and include structured pros and cons. Each content type has its own parser, its own validation rules, and its own set of computed fields.

MDX Remote and the Compilation Pipeline

RuneAI.tech uses next-mdx-remote to compile MDX content on the server rather than at build time. This is a deliberate architectural choice. Build-time MDX compilation requires every content file to be processed during next build, which means adding a single article triggers a full rebuild of the content bundle. With MDX Remote, compilation happens during server-side rendering or ISR revalidation, and the output is cached as static HTML.

The compilation pipeline works in three stages. First, the raw MDX string is read from the filesystem. Second, next-mdx-remote/rsc compiles it into a React Server Component tree, injecting custom components from a shared component map. Third, the rendered output is wrapped in the page layout with metadata, structured data, and navigation elements.

The custom component map is where the UI system comes together. Standard Markdown elements like headings, paragraphs, lists, and code blocks are mapped to custom React components that add anchor links, syntax highlighting, and consistent typography. Beyond standard elements, the map includes custom components for callout boxes, comparison tables, tool rating cards, and internal link sidebars.

Page Templates: Articles, Tools, and Comparisons

Each content type on RuneAI.tech renders through a dedicated page template inside the App Router. The article template at app/blog/[slug]/page.tsx is the most straightforward. It fetches the MDX file by slug, compiles it through the pipeline, and renders the result inside an article layout with a table of contents sidebar, author byline, and related articles section.

The tool pages follow a more complex pattern. A tool page like the one for ChatGPT combines MDX editorial content with live data from Supabase. The page component fetches the tool record from the database, reads the corresponding MDX file from content/tools/, and merges both into a template that shows pricing tables, feature breakdowns, rating visualizations, and the editorial review.

Comparison pages take this further by loading two tool records and a dedicated comparison MDX file. The template renders a side-by-side feature matrix generated from database fields, followed by the editorial comparison content from the MDX file. The structured data for comparison pages includes a Product schema for each tool and an ItemList schema for the comparison itself.

Alternative roundup pages aggregate multiple tool records into a ranked list with editorial commentary. The template iterates over a set of tool slugs defined in the MDX frontmatter, fetches each tool record from Supabase, and renders a card for each with pricing, key features, and a short editorial take from the MDX body.

Structured Data: Automatic JSON-LD Generation

Every content page on RuneAI.tech includes JSON-LD structured data generated automatically from the page content and metadata. This is not a manual process. The structured data layer reads from the same data sources as the page template and constructs the appropriate schema objects.

Article pages generate Article schema with headline, author, date published, date modified, image, and publisher fields. The FAQ frontmatter array generates a FAQPage schema that Google can surface directly in search results. Tool pages generate SoftwareApplication schema with name, description, operating system, pricing, and aggregate rating fields. Comparison pages generate ItemList schema wrapping individual Product entries.

The generation happens inside the generateMetadata function exported from each page component. Next.js 16 App Router calls this function during rendering and injects the returned metadata into the page head. The JSON-LD is included as a script tag with type="application/ld+json" inside the metadata object. Because this runs on the server, the structured data is present in the initial HTML response and visible to crawlers without JavaScript execution.

Schema validation runs as part of the content pipeline. When a new MDX file is added, the parser checks that all required fields for the corresponding schema type are present and correctly formatted. Missing fields trigger build warnings rather than silent omissions.

SEO Metadata Pipeline

SEO metadata on RuneAI.tech flows through a layered system. The base layer is the frontmatter: title, description, and cover image provide the raw inputs. The parser layer computes derived fields like meta title (capped at 60 characters with a site suffix), meta description (trimmed to 155 characters), and canonical URL (constructed from the slug and content type).

The generateMetadata export in each page component assembles the final metadata object. This includes Open Graph tags for social sharing, Twitter card metadata, canonical URL, robots directives, and the JSON-LD structured data. The alternates field specifies canonical URLs to prevent duplicate content issues across different URL patterns that might resolve to the same content.

Internal linking is partially automated. The auto-linker module in lib/auto-linker.ts scans rendered MDX output for mentions of known tool names and wraps them in links to the corresponding tool pages. This runs after MDX compilation but before final rendering, so the links are present in the static HTML. The system maintains a registry of tool names and their canonical URLs, updated whenever a new tool is added to the database.

The sitemap at app/sitemap.ts generates a dynamic XML sitemap by querying all published content across articles, tools, comparisons, and alternatives. Each entry includes the last modified date pulled from the updatedDate frontmatter field or the database record timestamp, whichever is more recent.

ISR Caching and Revalidation Strategy

RuneAI.tech uses Incremental Static Regeneration to serve content pages as static HTML while keeping them fresh. Each content route exports a revalidate value that tells Next.js how long to cache the rendered page before triggering a background regeneration.

Article pages revalidate every 3600 seconds (one hour). This is aggressive enough to pick up content corrections quickly but conservative enough to avoid unnecessary Supabase queries and MDX recompilation. Tool pages revalidate every 1800 seconds because tool data like pricing and feature availability changes more frequently. Comparison pages follow the same 1800-second window.

The revalidation process is transparent to users. When a request arrives after the stale window, Next.js serves the cached version immediately. In the background, it re-runs the page component: fetching fresh data from Supabase, re-compiling the MDX content, regenerating structured data, and rendering the complete page. The new version replaces the cache entry once rendering completes. If the regeneration fails, the stale version continues serving until a successful regeneration occurs.

For urgent updates like correcting a factual error or updating a tool's pricing, the admin panel triggers on-demand revalidation through a Next.js API route. This bypasses the time-based window and forces immediate regeneration of the specified path.

Turbopack and the Development Experience

Local development on RuneAI.tech uses Turbopack, the Rust-based bundler integrated into Next.js 16. Turbopack replaces Webpack for the dev server and provides significantly faster hot module replacement. For a content-heavy site with hundreds of MDX files, this matters.

The difference is most visible when editing MDX content. With Webpack, saving an MDX file triggered a recompilation that could take several seconds as the bundler re-processed the content pipeline. With Turbopack, the same edit reflects in the browser in under 500 milliseconds. This tight feedback loop makes content iteration practical: authors can preview formatting, component rendering, and layout changes almost instantly.

Turbopack also improves cold start times. The dev server boots in under three seconds on a standard development machine, compared to 10 or more seconds with the Webpack-based dev server. For a project with the number of routes and content files RuneAI.tech has, this saves meaningful time across a full development day.

Component Architecture Patterns

The MDX component system follows a few consistent patterns that keep the codebase manageable as content types multiply.

Server Components by Default

Every page component and layout component is a React Server Component. Client interactivity is pushed to the smallest possible leaf components: theme toggles, mobile navigation drawers, and interactive rating widgets. The MDX content itself renders entirely on the server, which means zero JavaScript ships to the client for the core reading experience.

Shared Component Map

All content types share a single MDX component map defined in one place. This map overrides default HTML elements with styled components and adds custom elements like Callout, ToolCard, and ComparisonTable. When a new component is added to the map, it becomes available in every MDX file across all content types without any per-file configuration.

Layout Composition

Page layouts compose through the App Router's nested layout system. The root layout provides the global navigation, footer, and theme context. Content-type layouts add type-specific sidebars, breadcrumbs, and related content sections. Individual pages fill in the main content area. This composition means changes to the global navigation propagate to every page without touching individual templates.

Key Takeaways

• MDX files handle editorial content while Supabase stores structured and dynamic data, keeping each system focused on what it does best.
• MDX Remote compiles content on the server during ISR revalidation rather than at build time, decoupling content updates from full rebuilds.
• JSON-LD structured data generates automatically from page content and metadata, with schema validation built into the content pipeline.
• ISR caching serves static HTML with configurable revalidation windows, balancing freshness against unnecessary recompilation.
• Turbopack cuts dev server cold starts and hot reload times substantially, making content iteration practical during local development.
• React Server Components handle all MDX rendering, shipping zero content-related JavaScript to the client.

Conclusion

The MDX UI system behind RuneAI.tech is not a single clever abstraction. It is a set of focused components that each handle one concern: content parsing, server-side compilation, metadata generation, structured data injection, caching, and layout composition. The stack choices of Next.js 16 App Router, MDX Remote, Supabase, and Turbopack support this separation by providing clear boundaries between build-time and runtime processing, between server and client rendering, and between editorial content and structured data. The result is a site that renders fast, indexes well, and stays maintainable as the content library grows.