behind the Hideout

Content pipeline

How a post goes from an MDX file to static pages and images. Every snippet here is copied from the repo; open the file named above it to check.

One post, two languages

A post has one file per language, in src/contents/posts/en and src/contents/posts/id. Both files carry the same slug map, so each knows the address of the other. slugOriginal is the slug of the language being read, and the language switcher uses the map to jump to the other version.
src/contents/posts/en/building-agent-memory-free-vendor.mdx
---
title: "Building Agent Memory with Vendor Lock-in Resistance (Part 2)"
slug: {
  en: "building-agent-memory-free-vendor",
  id: "membangun-agent-memory-bebas-vendor"
}
series: { id: "agent-memory", title: "Building Agent Memory", part: 2 }
---
src/modules/Content/services/content-parser.ts (getBlogMeta)
const slugOriginal = data.slug[language];

Static pagination

The blog list is cut into pages of BLOG_PAGINATION_LIMIT (10) posts. pageCount is Math.ceil(posts / 10), and generateStaticParams lists every page number from 1 to pageCount, per language. dynamicParams = false, so a page number outside that list is a 404, not a render on demand.
src/modules/Blog/BlogListPagination.page.tsx
export async function generateBlogPaginationPathsWithLang() {
  const _pathsRaw = await Promise.all(Object.keys(I18n)
    .map(async(lang) => {
      const { pagination } = await getBlogList(lang);
      return range(1, pagination.pageCount)
        .map(page => ({ page: `${page}`, lang }));
    }));
  const paths = _pathsRaw.flat(1);
  return paths;
};

en: 1 posts / 10 = 1 page

OG image per post

og.png is a route handler next to the post page. It takes the same static params as the post, so the build writes one 1200x630 PNG per post per language. The card is drawn with ImageResponse from next/og (satori under the hood) with fonts read from src/assets/og.
src/app/(base)/[lang]/blog/[slug]/og.png/route.tsx
/** `/{lang}/blog/{slug}/og.png`: written as a real .png file by the static export */
export const dynamic = 'force-static';

export const dynamicParams = false;

export const generateStaticParams = generateBlogPathsWithLang;

export async function GET(_request: Request, { params }: { params: Promise<{ slug: string; lang: I18nLocales }> }) {
  const { slug, lang } = await params;
  return renderPostOgImage(slug, lang);
}

The real og.png of a post on this site, loaded from its route:

og.png: building-agent-memory-free-vendor/en/blog/building-agent-memory-free-vendor/og.png

Share images

Same idea, three sizes for stories and feeds: 9x16 (1080x1920), 4x5 (1080x1350) and 1x1 (1080x1080). satori draws a PNG, then sharp turns it into a JPEG at quality 85 with mozjpeg.
src/modules/Blog/og/PostOgImage.tsx (renderPostShareImage)
const png = await new ImageResponse(<Layout card={card} />, { ...SHARE_SIZES[format], fonts }).arrayBuffer();
const jpeg = await sharp(Buffer.from(png)).jpeg({ quality: 85, mozjpeg: true }).toBuffer();

Series

A post joins a series with one frontmatter line. getSeriesParts collects every post of the same language with the same series id, sorted by part, and SeriesNav lists them with previous and next links. It renders nothing when a series has fewer than two parts.
src/modules/Content/services/content-parser.ts
export async function getSeriesParts(meta: ContentMeta, language = DEFAULT_LOCALE): Promise<ContentMeta[]> {
  if (!meta.series?.id) return [];
  ...
    .filter((m) => m.series?.id === meta.series?.id)
    .sort((a, b) => (a.series?.part ?? 0) - (b.series?.part ?? 0));

Table of contents and reading progress

The TOC is read from the MDX source, not the DOM: h2 and h3 lines outside code fences, slugged with github-slugger in document order, the same way rehype-slug makes the heading ids. It shows from the xl breakpoint up. ReadingProgress is a thin bar that follows how far #post-body has scrolled.
src/modules/Blog/services/toc.ts
const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
if (!match) continue;
const depth = match[1].length;
const text = toPlainText(match[2]);
const id = slugger.slug(text);
if (depth === 2 || depth === 3) {
  items.push({ id, text, depth });
}

Sitemap

src/app/sitemap.ts is static and reuses the same path generators the pages use: home, about, now, portfolio, the blog pages and every post, with and without the language prefix. The docs pages are not in it on purpose.
src/app/sitemap.ts
import generateSitemap from '@/modules/Content/services/sitemap';

export const dynamic = 'force-static';

export default generateSitemap;

GitHub workflows

Four files in .github/workflows. Only one runs on its own.
  • .github/workflows/integration.ymlon pull_request

    Runs on every pull request: npm install, then npm run lint.

  • .github/workflows/cloudinary.ymlworkflow_dispatch

    Run by hand. Deletes everything under gading.dev/media/ on Cloudinary, then uploads every image in public/media, 7 at a time. Banners are served from there in production; in dev they load from public/media directly.

  • .github/workflows/lighthouse.ymlworkflow_dispatch

    Run by hand. Fetches PageSpeed reports for gading.dev as SVG, desktop and mobile, into public/media/web-reports/pagespeed and commits them.

  • .github/workflows/revalidation.ymlworkflow_dispatch

    Run by hand. Runs src/scripts/app:revalidate.ts, which reads every path from sitemap.xml and calls /api/revalidate with them. That route does not exist in src/app today, so this one is a leftover until it comes back.