This post is the orientation. It walks through the stack, the design language, and the things I deliberately left out.

What this is

Bblog is a statically generated personal blog. Pages are rendered at build time, shipped to the edge, and read like a printed essay — narrow column, generous line height, no sidebar shouting at you.

A few constraints shaped every decision:

• The reading column never exceeds 680px.
• The accent color appears only where it earns it.
• Every interaction is 300ms or faster.

The stack

npm install next react react-dom
npm install next-mdx-remote rehype-pretty-code shiki
npm install tailwindcss @tailwindcss/typography

The interesting part is not the list — it is how they fit together. The MDX pipeline is the subject of its own article, so I will keep this one short and point you there.

What I left out

Restraint is a feature.

• No comment system. Use the replies on the social link instead.
• No analytics by default. Add the one line you trust, when you trust it.
• No theme toggle button that flashes. The system preference is respected, instantly.

That is the whole pitch. The rest is reading.

Static by default

Every route in the app directory is statically rendered unless you opt out. That is the right default for a blog. The one thing you must remember is to enumerate your paths.

  return getPostSlugs().map((slug) => ({ slug }));
}


  // rendered at build time, one HTML file per slug
  return ;
}

The generateStaticParams call is what turns a dynamic route into a folder of static HTML. Forget it and you get on-demand rendering — fine for an app, wasteful for a blog.

When to reach for the edge

Static files already serve from the nearest CDN PoP. Edge rendering earns its keep when your page needs a little dynamism — a draft preview, a per-request theme, a footer with the current build hash.

Use it when the cost of going fully static is a stale page. Do not use it to feel modern.

The checklist I run before every deploy

• generateStaticParams returns every slug.
• No accidental fetch with dynamic cache on a static page.
• Images are .webp, sized, and lazy below the fold.
• Fonts use next/font or display: swap.

Run that list and your Lighthouse score stops being a surprise.

The palette

The site runs on one background, one text color, and one accent. Everything else is a tint of those.

:root {
  --background: 40 33% 98%;   /* #FAF9F6 warm cream */
  --foreground: 240 3% 11%;   /* #1C1C1E charcoal  */
  --accent: 0 75% 60%;        /* #E54B4B burgundy  */
  --code-bg: 20 12% 15%;      /* #2A2421 warm dark  */
}

The accent is the strictest rule on the whole site. It appears on heading links, on hover, and nowhere else. The moment you paint a border with it, it stops meaning anything.

Why warm, not neutral

Pure neutral gray reads as cold and corporate. Add four degrees of hue and the page reads as paper. That single change is the difference between a dashboard and an essay.

The type scale

I keep exactly four sizes in regular use, and a display size for the hero.

The 680px rule

maxWidth: {
  prose: '680px',
}

Beyond roughly 680px, the eye loses its place on the return sweep. A wider column does not hold more meaning — it only holds more fatigue.

The renderer

The App Router is built on React Server Components, so the renderer has to be RSC-aware. next-mdx-remote ships an /rsc entrypoint for exactly that.

  return (
    <div className="prose-blog">
      
    </div>
  );
}

Syntax highlighting without a runtime

rehype-pretty-code runs Shiki at build time. Zero JavaScript ships to the reader; the colors are baked in as inline styles. One setting does all the heavy lifting:

const options = {
  theme: 'one-dark-pro',
  keepBackground: false, // we set our own #2A2421 in CSS
};

Setting keepBackground to false is the trick that lets a warm #2A2421 background replace Shiki's default theme background, so code blocks belong to the page instead of fighting it.

Line highlighting

Lines are highlighted with the {1,3-5} meta syntax on the fence:

function add(a: number, b: number) {
  return a + b;            // highlighted
}
const result = add(2, 3); // highlighted
console.log(result);

A table of contents that matches

The last piece is a TOC whose anchors line up with the rendered headings. The fix is to produce heading ids with the same slugger the renderer uses.

const slugger = new GithubSlugger();
// slug(text) === the id rehype-slug will produce

That is the whole system: read a file, strip frontmatter, render with one component, and the headings, anchors, and sidebar all agree.

The pairing

Latin text is set in Geist, a grotesk with a wide enough aperture to stay legible at 15px. Chinese body text is set in Noto Serif SC, a serif that carries weight without shouting. Headings switch to Noto Sans SC at 800 weight, where the strokes are dense enough to anchor a section.

--font-geist-sans: /* Geist, via next/font */
--font-noto-serif-sc: /* Noto Serif SC, body */
--font-noto-sans-sc: /* Noto Sans SC, headings */

The three numbers

A bilingual column becomes readable the moment these three are right.

body { line-height: 1.8; }
article { max-width: 680px; }
p { margin-block: 1.6em; }

• 1.8 line height. CJK glyphs are taller and denser; 1.5 reads as cramped.
• 680px column. Beyond it the return sweep breaks on both scripts.
• 1.6em paragraph spacing. White space is how the eye knows a beat passed.

A paragraph in practice

中英文混排时，最容易出现的问题是基线不齐与字重失衡。解决方法其实并不复杂：英文使用无衬线、中文正文使用衬线，再把行高拉到 1.8，把段落间距留足。剩下的，交给留白。

Read that paragraph next to the one above it. The two scripts are finally on speaking terms — not because they match, but because each is set to its own comfortable measure and given room to breathe.

What to avoid

• Forcing one font for both scripts. They will both look slightly wrong.
• Sub-pixel line heights. Use unitless 1.8, never 1.8em on line-height.
• Justifying text on the web. It creates rivers of whitespace in both languages.

Get those right and the typography disappears, which is the whole point.

The three numbers

For a content site, almost everything that matters is captured by three metrics. Pick ceilings, write them down, and treat them as a contract.

Where the budget leaks

Almost every budget violation on a blog comes from the same three sources: fonts, images, and third-party scripts.

const nextConfig = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
};

Fonts

Reserve the heavy weights for headings only. Body text in four weights is four round trips the reader never asked for.

Images

A .webp at the displayed width is cheaper than any responsive framework. The responsive framework exists to serve large images; if you do not have large images, you do not have the problem.

Enforce it

A budget you enforce at build time is the only kind that survives a deadline.

const budget = { lcp: 1200, cls: 0.05, tbt: 150 };
const result = await measure(buildOutput);
for (const [k, ceiling] of Object.entries(budget)) {
  if (result[k] > ceiling) throw new Error(`budget breached: ${k}`);
}

Fail the build when a number crosses its ceiling. Everything else is optional. The reader never opted in to slow.