Content maintenance guide

Find file paths, copy minimal templates, and inspect generated output by task.

Editable source · Copyable template

Add an article

src/content/{locale}/articles/{slug}/index.mdx

import Heading from '@/components/common/Heading'

export const metadata = {
    "title": "Article title",
    "description": "A short summary.",
    "date": "2026-09-23",
    "keywords": [
        "Next.js",
        "MDX"
    ],
    "outline": [
        {
            "id": "overview",
            "text": "Overview"
        }
    ]
};

<Heading id="overview">Overview</Heading>

Write the article here.

Fields and constraints

title / date: Required. Use YYYY-MM-DD; articles are listed newest first.
description / keywords: Recommended. Summary and keywords support listings and SEO.
outline: Table of contents; IDs must match the Heading IDs.
slug: Derived from the directory name; do not put it in metadata.

Output: src/content/{locale}/articles/list.json

Generation commands

pnpm generate:articles
pnpm generate:routes

Editable source · Copyable template

Maintain cheatsheet categories

src/content/{locale}/cheatsheets/categories.json

[
    {
        "slug": "ai-fundamentals",
        "title": "AI Fundamentals",
        "remark": "Optional category description"
    }
]

Fields and constraints

slug / title: Required. Unique slug; append to the existing array rather than replacing the file.
remark: Optional description.
Array order: Controls display order; no order field.

Output: src/content/{locale}/cheatsheets/list.json

Generation commands

pnpm generate:cheatsheets
pnpm generate:routes

Editable source · Copyable template

Add a cheatsheet topic

src/content/{locale}/cheatsheets/{topicDir}/meta.json

{
    "id": "example-topic",
    "slug": "example-topic",
    "title": "Example topic",
    "description": "Topic summary.",
    "icon": "/assets/cheatsheet/model.svg",
    "category": "ai-fundamentals",
    "keywords": [],
    "links": [],
    "sections": [],
    "order": 10,
    "createdAt": "2026-09-23",
    "updatedAt": "2026-09-23"
}

Fields and constraints

id / slug: Required. ID is stable identity; slug defines the URL. Use lowercase letters, digits, and hyphens. recent is reserved.
title / description / icon / category: Required. Category must match a categories.json slug; icon must point to an existing asset.
order / createdAt / updatedAt: Required. Lower order comes first; use YYYY-MM-DD dates.
sections / links: Required arrays, possibly empty. Sections use {slug,title} in array order; links use {title,url}.
keywords: Optional string array.

Output: src/content/{locale}/cheatsheets/list.json

Generation commands

pnpm generate:cheatsheets
pnpm generate:routes

Editable source · Copyable template

Add a cheatsheet entry

src/content/{locale}/cheatsheets/{topicDir}/{file}.mdx

export const metadata = {
    "id": "example-topic-basics",
    "slug": "basics",
    "title": "Basics",
    "description": "Content summary.",
    "keywords": [],
    "preview": [
        "One key point."
    ],
    "order": 0,
    "publishedAt": "2026-09-23",
    "updatedAt": "2026-09-23"
};

## Overview

Write the content here.

Fields and constraints

id / slug / title / description: Required. ID is unique across cheatsheets in a language; slug is unique within the topic. URLs use metadata.slug, not the filename.
order / publishedAt: Required. Order controls placement within the topic; publishedAt is the publication date.
updatedAt / keywords / preview: updatedAt may be omitted and falls back to publishedAt; the other fields are optional string arrays. Keep preview to four items or fewer.
section: Required and must match a section slug when the topic has sections; omit it when sections is empty.

Output: src/content/{locale}/cheatsheets/{topicDir}/list.json

Generation commands

pnpm generate:cheatsheets
pnpm generate:routes

Editable source · Copyable template

Add a tool

src/app/[locale]/tools/{id}/meta_{locale}.json

{
    "name": "Example tool",
    "description": "A short feature summary.",
    "icon": "/assets/tool/srt.svg",
    "tags": [],
    "sort": 10
}

Fields and constraints

name / description: Required. This file provides listing metadata only; create page.tsx and implement the page separately.
icon / tags / sort: Icon is an asset path; tags is a string array. sort can express ordering, but the generator itself does not reorder by sort.
author / version: Optional extension fields; the generator preserves additional metadata.

Output: src/content/{locale}/tools/list.json

Generation commands

pnpm generate:tools
pnpm generate:routes

Editable source · Copyable template

Add an Explore page

src/app/[locale]/explore/{id}/meta_{locale}.json

{
    "name": "Example tool",
    "description": "A short feature summary.",
    "icon": "/assets/tool/srt.svg",
    "tags": [],
    "sort": 10
}

Fields and constraints

name / description: Required. This file provides listing metadata only; create page.tsx and implement the page separately.
icon / tags / sort: Icon is an asset path; tags is a string array. sort can express ordering, but the generator itself does not reorder by sort.
author / version: Optional extension fields; the generator preserves additional metadata.

Output: src/content/{locale}/explore/list.json

Generation commands

pnpm generate:explore
pnpm generate:routes

Generated structures

These samples read current indexes at build time and show only a few entries. Do not edit these files. The recent sample shows one item, not a full page.

Generated · Read-only sample
src/content/en/articles/list.json

Article list: selected metadata fields plus directory slug and lang.

[
    {
        "slug": "nextjs-canonical-hreflang-google-indexing",
        "lang": "en",
        "title": "Debugging Next.js Multilingual Indexing Failures: Incorrect Canonical and Hreflang Configurations Prevent Google Indexing",
        "date": "2026-05-31",
        "description": "After deploying a multilingual site with Next.js and submitting it to Google Search Console, I kept seeing 'Duplicate, Google chose different canonical than user.' The root cause turned out to be incorrect Canonical and Hreflang settings, which prevented proper indexing.",
        "keywords": [
            "Canonical URL",
            "Canonical Tag",
            "hreflang",
            "Google Search Console",
            "Google chose different canonical than user",
            "Duplicate Google chose different canonical than user",
            "Google indexing issue",
            "Google not indexing pages",
            "Next.js App Router SEO",
            "International SEO",
            "Multilingual SEO",
            "i18n SEO",
            "Static Export SEO",
            "Next.js Static Export",
            "Next.js multilingual site",
            "Canonical configuration",
            "Hreflang configuration",
            "Google indexing",
            "Website indexing",
            "Multilingual website",
            "Internationalized SEO",
            "Website optimization"
        ]
    }
]

Generated · Read-only sample
src/content/en/cheatsheets/list.json

Global cheatsheet index: categories → topics, with articleCount and no body content.

[
    {
        "slug": "ai-fundamentals",
        "title": "AI Fundamentals",
        "topics": [
            {
                "id": "model-fundamentals",
                "slug": "model-fundamentals",
                "title": "Model",
                "keywords": [
                    "AI",
                    "Fundamentals"
                ],
                "description": "A model is a mathematical system that is trained to obtain parameters and can calculate outputs based on inputs.",
                "icon": "/assets/cheatsheet/model.svg",
                "links": [],
                "category": "ai-fundamentals",
                "order": 0,
                "createdAt": "2026-08-17",
                "updatedAt": "2026-08-17",
                "articleCount": 5
            }
        ]
    }
]

Generated · Read-only sample
src/content/en/cheatsheets/model-fundamentals/list.json

Topic article list: entry metadata ordered by section, order, and slug.

[
    {
        "id": "model-fundamentals-what-is-a-model",
        "slug": "what-is-a-model",
        "title": "Layer 1: What Is a Model?",
        "keywords": [
            "AI Model",
            "Model",
            "Model Architecture",
            "Parameters",
            "Model Parameters",
            "Weights",
            "Model Weights",
            "Model Configuration",
            "Model Config",
            "Tokenizer",
            "Model Fundamentals"
        ],
        "description": "Understand the basic building blocks of an AI model from an engineering perspective, and how core concepts such as model, architecture, parameters, weights, configuration, and Tokenizer relate to each other.",
        "preview": [
            "A model is a mathematical system that can compute outputs from inputs. Its architecture defines how the computation works, while the specific parameter values are obtained through training.",
            "Architecture is like a pre-designed computation framework; weights are the large set of numeric values filled in during training. Together they form a model with concrete capabilities."
        ],
        "order": 0,
        "publishedAt": "2026-08-21",
        "updatedAt": "2026-08-21"
    }
]

Generated · Read-only sample
src/content/en/cheatsheets/home.json

Home cheatsheets: the newest entry per nonempty topic with topic, category, and icon details, sorted by recency.

[
    {
        "slug": "office",
        "title": "Install Office (Word/Excel/PowerPoint) on macOS",
        "preview": [
            "Download the official PKG and activate with Microsoft-Office-For-MacOS;",
            "Install official Office first, then run the Serializer to activate;"
        ],
        "updatedAt": "2026-09-16",
        "topicSlug": "macos",
        "topicTitle": "macOS",
        "icon": "/assets/cheatsheet/macos.svg",
        "categorySlug": "systems",
        "categoryTitle": "Operating Systems & Fundamentals"
    }
]

Generated · Read-only sample
src/content/en/cheatsheets/recent.json

Recent updates: all entries ordered by updatedAt, falling back to publishedAt; pageSize controls pagination.

{
    "pageSize": 30,
    "items": [
        {
            "slug": "office",
            "title": "Install Office (Word/Excel/PowerPoint) on macOS",
            "updatedAt": "2026-09-16",
            "topicSlug": "macos",
            "topicTitle": "macOS",
            "icon": "/assets/cheatsheet/macos.svg",
            "categorySlug": "systems",
            "categoryTitle": "Operating Systems & Fundamentals",
            "description": "Notes on installing Office (Word/Excel/PowerPoint) on macOS.",
            "publishedAt": "2026-09-16"
        }
    ]
}

Generated · Read-only sample
src/content/en/tools/list.json

Tool index: adds id, href, and tags to meta fields, preserving extensions.

[
    {
        "id": "generate-guid-by-crypto",
        "name": "UUID / GUID Generator",
        "description": "Generate random UUID v4 identifiers with the Web Crypto API, one at a time or in batches.",
        "href": "/tools/generate-guid-by-crypto",
        "icon": "/assets/tool/uuid.svg",
        "tags": [
            "UUID",
            "GUID",
            "Generator",
            "Crypto"
        ],
        "sort": 1,
        "author": "Oceanz",
        "version": "1.0.0"
    }
]

Generated · Read-only sample
src/content/en/explore/list.json

Explore index: similar to tools, with /explore/{id} links.

[
    {
        "id": "edge-tts",
        "name": "Edge TTS Voice Samples - 322 Neural Voices Preview",
        "description": "Preview Microsoft Edge TTS voice samples, compare 322 neural voices, and copy voice IDs such as en-US-AriaNeural for Python edge-tts, Azure Speech, narration, and dubbing projects.",
        "href": "/explore/edge-tts",
        "icon": "/assets/explore/edge.png",
        "tags": [
            "Microsoft Edge",
            "TTS",
            "Voice Samples",
            "edge-tts",
            "Python",
            "Azure Speech",
            "Neural Voices",
            "Edge TTS voice samples",
            "Microsoft Edge TTS samples",
            "edge-tts Python",
            "en-US-AriaNeural sample",
            "Azure Cognitive Speech sample",
            "text to speech voice preview"
        ]
    }
]

Generated · Read-only sample
src/generated/content-routes.json

Route inventory: path → kind and language versions, used by static pages, translation notices, and the sitemap.

{
    "/": {
        "kind": "page",
        "versions": {
            "zh-cn": {
                "title": ""
            },
            "en": {
                "title": ""
            }
        }
    },
    "/about": {
        "kind": "page",
        "versions": {
            "zh-cn": {
                "title": ""
            },
            "en": {
                "title": ""
            }
        }
    }
}

Generated · Read-only sample
src/generated/route-locales.json

Language availability: path → published locales, used for language switching and hreflang.

{
    "/": [
        "zh-cn",
        "en"
    ],
    "/about": [
        "zh-cn",
        "en"
    ]
}

src/generated/cheatsheet-content.ts is generated too: it maps locale/topicSlug/articleSlug to MDX loaders and provides topic metadata/list loaders. Regenerate it with generate:cheatsheets; do not edit it manually.

Before publishing

Replace sample IDs, slugs, titles, dates, and icons; do not reuse sample identities across entries.
Metadata must use static literals, without variables, functions, or spread operators.
Publish Chinese and English independently; use an _draft prefix or omit unfinished long-form content instead of publishing untranslated placeholders.
Run pnpm generate:all, preview the content, topic, recent updates, and language switching, then run pnpm build and pnpm verify:content-export.