Keep what you’ve truly understood
Information can always be searched for again, and AI is always there to answer questions. Still, what you’ve truly understood, verified, and put into practice is worth writing down. When you return to those notes, they become a personal index of knowledge and a way to recall what you’ve learned.
Built with Next.js and React, the site uses MDX to organize its content. Components and tooling help continually improve how that content is structured, presented, and used.
01
Technology Stack
The site is primarily composed of five layers.
Next.js 16 (App Router) + React 19
Handles routing, page rendering, and static export.
MDX (@next/mdx) + remark-gfm / rehype-slug / rehype-pretty-code (Shiki)
Long-form content and Cheatsheets are written in MDX, with Markdown extensions, syntax highlighting, and React compilation handled at build time.
Tailwind CSS v4 + Radix UI + shadcn + lucide-react
Tailwind supplies utility classes, Radix supplies unstyled interaction primitives, shadcn wraps them into site components, and lucide-react supplies icons.
TypeScript 5 + pnpm
Source code uses TypeScript, while dependencies and scripts are managed with pnpm.
Vercel
Static output is deployed to Vercel.
02
Dependencies
These are the npm packages the site actually uses. Select a category or package to see what it is responsible for, and how it is used here.
"dependencies"
: {// Runtime capability"devDependencies"
: {// Development toolchain03
How Content Is Published
The site has no database or CMS. Content lives in source files. Node.js scripts extract metadata into list indexes, then Next.js builds static pages for deployment.
- 01
Write Chinese
MDX / JSON
- 02
Translate English
LLM + review
- 03
Generate indexes
generate:all
- 04
Static build
Next.js → out/
- 05
Publish
GitHub → Vercel
- 01
Write the Chinese source first
Articles, cheatsheets, and interface copy usually start in Chinese. Article slugs come from directory names; cheatsheet slugs come from metadata.slug and may differ from filenames. Translations share the corresponding URL slug.
- Articles: src/content/zh-cn/articles/{slug}/index.mdx
- Cheatsheets: src/content/zh-cn/cheatsheets/{topic}/{article}.mdx
- Page copy: src/i18n/messages/zh-cn/{namespace}/index.json
- 02
Translate English with an LLM, then review by hand
After the Chinese draft is settled, copy it into the English directory and translate with a script, agent, or chatbot. The LLM only provides a first pass; code, commands, links, facts, and terminology still need human review.
- Keep IDs, slugs, code, and URLs unchanged; translate titles, summaries, body text, and visible labels.
- Use an _draft prefix or omit unfinished content; regenerate indexes when the translation is ready.
- 03
Extract metadata with Node.js to build list data
pnpm generate:all scans export const metadata in MDX, plus tool / Explore meta JSON, and writes per-locale list.json files for home and list pages. Lists are not generated by an MDX formatter or CMS, because JSON makes the data shape easier to control and keep aligned across languages.
- Article indexes are newest first; tool and Explore metadata preserve sort, while presentation order depends on the page implementation.
- list.json and src/generated/* are generated output — do not edit them by hand, or the next generate run will overwrite them
- 04
Build the static site and publish
pnpm build runs generate:all first, then Next.js prerenders every locale and path into out/. After a push to GitHub, Vercel builds and publishes the static output according to the project settings.
- Before committing, pnpm routes:list can confirm that both English and Chinese URLs were generated
- The site has no database or CMS. Sections come from the directory structure; titles, dates, summaries, and sorting come from metadata in the source files.
- metadata must be serializable literals. Functions or external variables cannot be used, or the generate scripts cannot extract it.
04
How Internationalization Works
This is a lightweight in-house setup, not next-intl. English and Simplified Chinese pages are both pre-generated at build time; they are not translated on the fly in the browser.
URL
/{locale}/...
The language is the first URL segment. /en/about is English; /zh-cn/about is Chinese. Visiting / shows the default English home page. There is no browser-language auto-redirect.
UI copy
JSON
Titles, buttons, and menus live in src/i18n/messages/{locale}/. Each language has its own file, and the field structure must match.
Long-form content
MDX
Articles and Cheatsheets live in src/content/{locale}/. Each language maintains its own body; list indexes are generated by scripts.
Build
Static HTML
generateStaticParams creates routes for each language. After deploy, both English and Chinese pages are prerendered HTML.
Why JSON and MDX are separate tracks
Short copy changes often and has a fixed shape, so JSON keeps fields aligned. Long-form content needs Markdown, code blocks, and components, so it uses MDX. Do not put article bodies into UI JSON, and do not put button labels into MDX.
How pages load copy
Regular pages load JSON by locale in a Server Component and pass it down as props. Only client components that already need clicks, filters, or other state wrap an I18nProvider and read copy with useLocalesT.
In-site links must keep the current language
Components write business paths such as /articles; LocaleLink adds /zh-cn or /en. Using next/link directly drops the locale prefix, and the next page can switch languages by accident.
Publish languages independently
Do not create untranslated placeholder files. The build derives language availability from published content. Missing long-form translations show notice pages and stay out of the sitemap. Interface messages still need matching field structures in both languages.
05
Hosting & External Services
These are the primary services currently used by the site.
Code & Deployment
GitHub
Hosts the repository and serves as the source for Vercel deployments.
Free tierVercel
Handles builds and static site hosting, and serves the public site.
Free tier (Hobby)Assets
Cloudinary
Hosts and distributes site images; pages generate Cloudinary URLs through a custom next/image loader.
Free tierCloudflare R2 (r2.oceanz.site)
Hosts larger static files, such as edge-tts audio samples, and distributes them through a custom domain.
Free tierjsDelivr (cdn.jsdelivr.net)
Provides backup URLs for edge-tts and similar assets. R2 is the primary path; jsDelivr can be unstable on some networks and is not the primary dependency source.
FreeDomain
Cloudflare DNS
Provides DNS after the domain's nameservers are moved to Cloudflare; domain registration costs are separate.
DNS free tierAnalytics
Vercel Analytics
Collects site traffic metrics through @vercel/analytics.
Free tier (included with the Vercel plan)Vercel Speed Insights
Collects Web Vitals and other performance metrics through @vercel/speed-insights.
Free tier (included with the Vercel plan)Microsoft Clarity (clarity.ms)
Injects the Clarity script in production for session replay and page behavior analytics.
FreeAdvertising
Google AdSense
Loads the AdSense script from pagead2.googlesyndication.com in production to display ads.
Free to integrate; revenue is settled through AdSense