Building Verto: A Modern Blog Engine

Every tool begins as frustration. We had been maintaining a developer blog for two years — first on Gatsby, then Hugo, then a brief, regrettable stint with a custom CMS — and each time, something was missing. The beautiful reading experience of OpenAI's blog💬, Mintlify's intelligent structured navigation, and Notion's expressive block system had never existed in a single coherent tool.

So we built Verto — named from the Latin vertō, meaning "to transform." The name felt right: you write plain Markdown, and Verto transforms it into something that looks and feels like a premium publication.

The core philosophy is zero compromise: authors should write in plain Markdown with optional syntax extensions. Readers should get a publication-quality experience. Developers should have zero-config deployment.

Architecture Decisions

Choosing the right framework was the hardest part💬. After a two-week evaluation spike, the architecture settled into three clear layers:

1. Parser Layer — An extended unified/remark pipeline that handles custom syntax like callouts, toggles, and inline comments
2. Renderer Layer — Astro components that convert AST nodes into semantic HTML with zero client-side JavaScript
3. Delivery Layer — Static site output with optional edge runtime for dynamic features

The Parser Pipeline

The remark ecosystem gave us 80% of what we needed for free. The remaining 20% — callouts, inline comments, toggle blocks — required custom AST transformers. Here's the core transformer for callout syntax:

import { visit } from "unist-util-visit";
import type { Plugin, Root } from "unified";

// Matches: > [!INFO] Optional title
const CALLOUT_RE = /^\[!(INFO|WARN|OK)\]\s*(.*)/i;

export const remarkCallouts: Plugin<[], Root> = () => (tree) => {
  visit(tree, "blockquote", (node, index, parent) => {
    const firstPara = node.children[0];
    if (firstPara?.type !== "paragraph") return;
    const text = toString(firstPara);
    const match = CALLOUT_RE.exec(text);
    if (!match) return;

    // Mutate node into callout type
    node.type = "callout" as any;
    (node as any).calloutType = match[1].toLowerCase();
    (node as any).calloutTitle = match[2];
  });
};

The key insight: rather than building a new parser from scratch, we extended the existing remark ecosystem. This gave us CommonMark compatibility for free while enabling Verto-specific syntax with minimal code.

The Renderer

Astro was a clear winner for this use case💬. Its island architecture meant we could ship zero JavaScript by default — critical for a reading-focused content site — while still enabling interactive islands for things like code copy buttons and inline comment popups.

// Post layout — Astro component
import CodeBlock from "../components/CodeBlock.astro";
import Callout from "../components/Callout.astro";

const { post } = Astro.props;

// Component mapping lets MDX use custom renderers
const components = {
  pre: CodeBlock,
  blockquote: Callout,
};

"The best blog engine is one your readers never notice — they only notice the content." This principle guided every design decision we made, from typography choices to animation timing.

The Block System

Notion proved that a block-based editor doesn't have to feel like a database. Verto takes that philosophy to Markdown: every block type has a clean, unambiguous syntax and a beautiful default rendering.

Callout Blocks

Three callout types cover 95% of author needs:

Toggle Sections

Collapsible blocks let authors include supporting detail without cluttering the main reading flow:

<Toggle title="Your section title">
  Content goes here. Supports full Markdown including
  code blocks, lists, and nested components.
</Toggle>

Task Lists

The Verto v0.1 roadmap, tracked as a task list right in this blog post:

• Core Markdown parser with remark
• Callout block syntax and renderer
• Inline comment system (c- footnote syntax)
• Dark mode with system preference detection
• Excalidraw embed integration
• Full-text search
• RSS feed generation
• Comment threads (not inline — threaded discussions)

The Inline Comment System

This is Verto's most distinctive feature. Every blogger has thoughts they want to share that don't fit the narrative flow — a parenthetical, a confession, a "here's what really happened" aside. Designing the interaction for this took longer than any other part of Verto💬.

The syntax reuses Markdown's footnote notation with a c- prefix:

Some highlighted text[^c-1] continues normally.

[^c-1]: This is my author's note about this text.
[^1]: This is a regular footnote, rendered at the bottom.

The parser distinguishes between [^c-N] (inline comment — shown as popup) and [^N] (footnote — rendered at page bottom). This means author commentary and formal citations coexist without conflict.

Rich Media Embeds

Static blogs have historically been terrible at embedding rich content. Verto treats embeds as first-class citizens with a consistent visual language.

Images and Captions

Every image in Verto can carry a caption, rendered in a consistent <Figure> component:

Diagrams

For architectural diagrams and flowcharts, Verto supports placeholder blocks that can be replaced with Excalidraw or Mermaid embeds in production:

Link Preview Cards

External references render as rich preview cards instead of plain hyperlinks:

The Design System

Verto's visual language is intentionally restrained. The goal: the design should disappear, leaving only the content. Here's the complete typography and spacing spec:

Both light and dark modes are defined as CSS custom properties on :root and html.dark respectively, enabling instant, flicker-free theme switching. The color palette uses a minimal set of semantic variables — --bg, --text, --accent-blue, --border — that adapt automatically.

What's Next

Verto v0.1 ships with the core feature set. The roadmap for v0.2 focuses on collaboration💬. That means:

• Real-time collaborative editing via Y.js CRDTs
• Version history with visual diffs
• Threaded comment discussions (separate from inline comments)
• AI writing assistant (optional, privacy-respecting)

React Server Components¹ make this possible — the server can handle collaborative state while the client remains lightweight, only hydrating the interactive editing islands.