di balik Hideout

Content pipeline

Gimana sebuah post jalan dari file MDX jadi static page dan gambar. Tiap snippet di sini di-copy dari repo; buka file yang namanya ada di atasnya buat ngecek.

Satu post, dua bahasa

Satu post punya satu file per bahasa, di src/contents/posts/en dan src/contents/posts/id. Dua file itu bawa slug map yang sama, jadi masing-masing tau alamat pasangannya. slugOriginal itu slug bahasa yang lagi dibaca, dan language switcher pake map itu buat lompat ke versi satunya.
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

List blog dipotong jadi page isi BLOG_PAGINATION_LIMIT (10) post. pageCount itu Math.ceil(post / 10), dan generateStaticParams ngelist semua nomor page dari 1 sampai pageCount, per bahasa. dynamicParams = false, jadi nomor page di luar list itu 404, bukan di-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;
};

id: 1 posts / 10 = 1 page

OG image per post

og.png itu route handler di sebelah post page. Static params-nya sama persis kayak post, jadi build nulis satu PNG 1200x630 per post per bahasa. Card-nya digambar pake ImageResponse dari next/og (satori di belakangnya) dengan font yang dibaca dari 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);
}

og.png asli dari salah satu post di site ini, di-load dari route-nya:

og.png: membangun-agent-memory-bebas-vendor/id/blog/membangun-agent-memory-bebas-vendor/og.png

Share image

Idenya sama, tiga ukuran buat story dan feed: 9x16 (1080x1920), 4x5 (1080x1350) dan 1x1 (1080x1080). satori gambar PNG, terus sharp ubah jadi JPEG quality 85 pake 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

Post masuk series cukup pake satu baris frontmatter. getSeriesParts ngumpulin semua post di bahasa yang sama dengan series id yang sama, diurutin by part, terus SeriesNav nampilin list-nya plus link previous dan next. Kalau part-nya kurang dari dua, nggak ada yang di-render.
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 dan reading progress

TOC dibaca dari source MDX, bukan dari DOM: baris h2 dan h3 di luar code fence, di-slug pake github-slugger sesuai urutan dokumen, sama kayak rehype-slug bikin id heading. Muncul mulai breakpoint xl. ReadingProgress itu bar tipis yang ngikutin seberapa jauh #post-body udah di-scroll.
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 itu static dan pake ulang path generator yang sama dengan page-nya: home, about, now, portfolio, page blog dan semua post, dengan dan tanpa prefix bahasa. Page docs sengaja nggak dimasukin.
src/app/sitemap.ts
import generateSitemap from '@/modules/Content/services/sitemap';

export const dynamic = 'force-static';

export default generateSitemap;

Workflow GitHub

Empat file di .github/workflows. Cuma satu yang jalan sendiri.
  • .github/workflows/integration.ymlon pull_request

    Jalan di tiap pull request: npm install, terus npm run lint.

  • .github/workflows/cloudinary.ymlworkflow_dispatch

    Dijalanin manual. Hapus semua di bawah gading.dev/media/ di Cloudinary, terus upload semua gambar di public/media, 7 sekaligus. Banner di production di-serve dari situ; di dev langsung dari public/media.

  • .github/workflows/lighthouse.ymlworkflow_dispatch

    Dijalanin manual. Ambil report PageSpeed buat gading.dev dalam bentuk SVG, desktop dan mobile, ke public/media/web-reports/pagespeed terus di-commit.

  • .github/workflows/revalidation.ymlworkflow_dispatch

    Dijalanin manual. Ngejalanin src/scripts/app:revalidate.ts, yang baca semua path dari sitemap.xml terus manggil /api/revalidate. Route itu sekarang nggak ada di src/app, jadi workflow ini sisa lama sampai route-nya balik.