Blogcraft
Tutorial

Hello, Blogcraft

A comprehensive guide to Blogcraft's content pipeline featuring Expressive Code, Mermaid diagrams, and rich static MDX components.

Tin Dang avatar
Tin Dang 2 min read
Open notebook with teal fountain pen and flowing ink strokes on paper

The Blogcraft Content Pipeline

Blogcraft transforms your MDX content into beautifully typeset, zero-JavaScript pages. Every component on this page renders at build time — no client-side framework needed.

Architecture Overview

Here is how content flows through the Blogcraft build pipeline:

Blogcraft content pipeline illustration
The Blogcraft paper-aesthetic design system in action.

Code Highlighting

Blogcraft uses Expressive Code for syntax highlighting with dual light/dark themes.

TypeScript with Line Highlighting

src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';


const blog = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/blog' }),
  schema: ({ image }) => z.object({
    title: z.string().max(100),
    description: z.string().max(300),
    pubDate: z.coerce.date(),
  }),
});


export const collections = { blog };

Terminal Commands

Terminal window
pnpm add astro-expressive-code@^0.41.7
pnpm build

Insert and Delete Markers

const old = 'removed line';
const replacement = 'added line';
console.log(replacement);

Getting Started

Terminal window
pnpm create astro@latest
pnpm add astro-expressive-code
Terminal window
npm create astro@latest
npm install astro-expressive-code
Terminal window
yarn create astro
yarn add astro-expressive-code

Behind the Scenes

How does the reading progress bar work?

The reading progress bar uses CSS animation-timeline: scroll() — a pure CSS solution that requires zero JavaScript. It animates a thin teal bar from width: 0 to width: 100% as the user scrolls down the page. Browsers that don’t support scroll-timeline gracefully degrade to an invisible bar.

How are Mermaid diagrams rendered?

Mermaid code fences are converted to inline SVG at build time using rehype-mermaid and Playwright’s headless Chromium. This means zero client-side JavaScript for diagrams — the SVG is embedded directly in the HTML output.

Framework Comparison

FeatureBlogcraft (Astro)Next.js BlogHugo
Zero JS by default ✓ ✗ ✓
MDX Components ✓ ✓ ✗
Build-time Mermaid ✓ ✗ ✗
React Islands ✓ ✓ ✗
Edge Functions ✓ ✓ ✗
AI Writing Assistant ✓ ✗ ✗

Project Timeline

Foundation & Design System

Astro 5 + React 19 + Tailwind 4 scaffold, paper aesthetic, fonts, dark mode, Cloudflare Pages deployment.

Content Spine & Static MDX

Content collections, blog post layout, Expressive Code, build-time Mermaid, 8 static MDX components.

Routing & SEO

Homepage, blog listing, tag archives, RSS, sitemap, OG images, client-side search.

Interactive MDX

Charts, code playgrounds, animations — all lazy-loaded within Lighthouse budget.

Keystatic CMS

Git-based authoring UI with schema parity checking.

AI & CI/CD

Plate editor with AI actions, GitHub Actions pipeline, Lighthouse CI gates.

Interactive Components

Blogcraft’s interactive components are React islands that hydrate lazily — charts wait until you scroll to them (client:visible), and code playgrounds load after the page is idle (client:idle). Posts that don’t use these components ship zero additional JavaScript.

Interactive

Live Chart

Recharts bar chart — hydrates when you scroll here.

Framework Performance Scores
Interactive

Code Playground

Edit and run code live in the browser.

</> Run Code 
document.getElementById('app').textContent = 'Hello from Blogcraft!';
Open on CodeSandboxOpen Sandbox

Wrapping Up

Blogcraft proves that rich, author-friendly content and zero-JavaScript performance are not mutually exclusive. Every component you have seen on this page renders at build time, ships as static HTML, and works perfectly in both light and dark modes.

0

Related Posts