ccblog — Next.js 博客模板

SHA-256: fd4a4b982419205a24b17c31828a591611ded8f20009e989ad9cf1ec106c8f63

2026-09-30T07:56:37.229Z

# ccblog

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Next.js](https://img.shields.io/badge/Next.js_16-000?logo=next.js&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white)
![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)

Forkable terminal blog. C and C++ compile in the browser. One config file, then deploy.

[Use this template](https://github.com/crazycloudcc/ccblog/generate)
 · 
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fcrazycloudcc%2Fccblog&env=NEXT_PUBLIC_SITE_URL&envDescription=Canonical%20public%20URL%20(e.g.%20https%3A%2F%2Fyour-domain.com)&project-name=ccblog&repository-name=ccblog)
 · 
[Live demo](https://crazycloud.cc)
 · 
[Run quicksort in the article](https://crazycloud.cc/blog/quicksort)
 · 
[中文文档](README.zh-CN.md)

![ccblog terminal boot and in-browser C++ run](docs/media/boot-and-run.gif)

<p align="center">
  <img src="docs/media/home-dark.png" alt="Home terminal session" width="32%" />
  <img src="docs/media/playground-run.png" alt="Playground compile and run" width="32%" />
  <img src="docs/media/quicksort-embed.png" alt="Annotated quicksort in a post" width="32%" />
</p>

### Why fork this

- Rebrand by editing `ccblog.config.ts` — name, social links, feature flags
- In-browser **C11 / C++17** via clang-in-WASM (no server, no install)
- Posts can embed a live runner (`:::playground`) plus annotate / steps / bench blocks
- Static search (Pagefind), RSS, sitemap, JSON-LD, Open Graph
- No App Store? Leave `features.apps` off (the default in the example config)

The first Deploy still looks like the demo site. Copy `ccblog.config.example.ts` over `ccblog.config.ts`, set `NEXT_PUBLIC_SITE_URL`, and redeploy.

---

## What it is

**ccblog** is a Next.js site styled like a macOS terminal session. Posts live as markdown files; the UI leans into `cd`, `cat`, `grep`, and panel chrome rather than a conventional blog layout.

The home page opens with a short boot sequence (notes type in, then settle). Theme follows light / dark / system, with reduced-motion respected throughout.

### Highlights

| Area | What you get |
|------|----------------|
| **Blog** | Markdown + frontmatter, tag & series filters, reading time, prev/next, related posts |
| **Search** | [Pagefind](https://pagefind.app/) static index, built on `postbuild` |
| **Playground** | C11 / C++17 compile & run via [browsercc](https://www.npmjs.com/package/browsercc) WASM - Monaco editor, stdin, share links, compile timeline |
| **Content blocks** | `:::trace`, `:::bench`, `:::annotate`, `:::playground` directives in posts |
| **Meta** | RSS, sitemap, JSON-LD, Open Graph image |
| **Apps** | Optional App Store catalog, off unless you turn `features.apps` on |

---

## Stack

- [Next.js 16](https://nextjs.org) (App Router) · React 19 · TypeScript
- [Tailwind CSS v4](https://tailwindcss.com)
- [gray-matter](https://github.com/jonschlinkert/gray-matter) for post frontmatter
- [Monaco Editor](https://microsoft.github.io/monaco-editor/) + browsercc for `/playground`
- [Pagefind](https://pagefind.app) for client-side search
- [@vercel/analytics](https://vercel.com/analytics) for privacy-friendly page-view stats (auto on Vercel; remove `<Analytics />` in `app/layout.tsx` to disable)

---

## Fork & deploy

**Requirements:** Node.js 20+, npm 9+.

```bash
# 1. Use this template (or fork), then clone your copy
git clone https://github.com/<your-username>/ccblog.git
cd ccblog
npm install

# 2. Make it yours — do this before the first real deploy
cp ccblog.config.example.ts ccblog.config.ts
#    edit name, author, social links, url
#    leave features.apps false unless you have an Apple developer ID

# 3. Run locally
npm run dev    # http://localhost:3000

# 4. Deploy on Vercel
#    Use the Deploy button above, or Import the repo at https://vercel.com/new
#    Set NEXT_PUBLIC_SITE_URL to your production URL
```

A few things the first deploy will otherwise get wrong:

- The committed `ccblog.config.ts` is the **demo identity**. Until you copy the example file, the site still says crazycloudcc and may sync the demo App Store list.
- Search on `/blog` needs `npm run build` (Pagefind is generated at `postbuild`). `next dev` alone has no index.
- Playground WASM is fetched from unpkg in production, not bundled into the deploy.

That is the whole loop. For a detailed walkthrough, see the **Start Up** post (`content/notes/nextjs-blog-setup.md`). Maintainer dry-run: `docs/fork-dry-run.md`.

---

## Configure

`ccblog.config.ts` at the repo root is the single rebrand surface - identity, social links, feature flags, and the App Store ID all live there. Everything works with zero environment variables on `npm run dev`; in production set the canonical URL:

```bash
# .env.local (not committed)
NEXT_PUBLIC_SITE_URL=https://your-domain.com
```

| Variable | When | Purpose |
|----------|------|---------|
| `NEXT_PUBLIC_SITE_URL` | Production | Canonical URL for RSS, sitemap, Open Graph |
| `NEXT_PUBLIC_CCBLOG_BRANCH` | Optional | Git branch shown in the terminal status bar |
| `APPLE_DEVELOPER_ID` | Optional | Overrides `apps.developerId` for `/apps` sync |
| `NEXT_PUBLIC_TOOLCHAIN_BASE` | Optional | Override Playground WASM CDN in production |

Feature flags in `ccblog.config.ts` (`features.blog`, `features.apps`, `features.playground`, `features.about`) toggle whole routes - nav, sitemap, and the apps sync all respect them. `/apps` defaults to **off**.

---

## Writing posts

Add markdown files under `content/notes/`:

```yaml
---
title: My Post
excerpt: One-line summary for lists and RSS.
date: 2026-07-08
tags:
  - nextjs
series: my-series        # optional
seriesSlug: my-series    # optional; public page at /blog/series/my-series
index: false             # optional; keep the URL, omit it from sitemap, RSS, and the public list
difficulty: intermediate # optional
---
```

Inline links, code spans, bold, emphasis, and strikethrough render in headings, paragraphs, and list items. Raw HTML stays escaped; links support relative URLs, HTTP(S), and email. Custom blocks and fenced code keep their existing rendering.

The filename becomes the URL (`/blog/my-post`). The body supports standard markdown, fenced code, images, and custom blocks (`:::trace`, `:::bench`, `:::annotate`, `:::playground`, …) - see `content/notes/content-blocks.md` for examples.

---

## Scripts

```bash
npm run dev          # local dev (webpack)
npm run build        # validate config -> sync apps -> build -> pagefind index
npm run start        # serve the production build
npm run lint         # eslint
npm test             # inline Markdown regression tests
npm run sync:apps    # refresh lib/apps.ts from the iTunes API
```

`npm run build` runs:

1. **prebuild** - `validate-config.mjs` checks `ccblog.config.ts`, then `sync-apps.mjs` syncs App Store metadata (skipped when `features.apps` is false)
2. **build** - Next.js static generation
3. **postbuild** - Pagefind search index into `public/pagefind/`

Search on `/blog` needs a production build; `next dev` alone does not generate the index.

---

## Routes

| Path | Description |
|------|-------------|
| `/` | Home - boot sequence + recent notes |
| `/blog` | Notes list, tag/series filters, search |
| `/blog/[slug]` | Post detail |
| `/playground` | In-browser C/C++ editor & runner |
| `/apps` | App Store releases (optional, off by default) |
| `/about` | About & contact |
| `/feed.xml` | RSS |

---

## Playground toolchain

| Environment | Source |
|-------------|--------|
| **Development** | `/api/toolchain` - local proxy (GitHub release, falls back to `node_modules/browsercc`) |
| **Production** | [unpkg](https://unpkg.com) CDN (`[email protected]`), overridable via `NEXT_PUBLIC_TOOLCHAIN_BASE` |

Toolchain files are not bundled into the deployment (keeps Vercel Hobby under size limits). The browser fetches and caches them on first load.

---

## Project layout

```
app/              # Next.js routes & API
components/       # UI (terminal shell, blog, playground, …)
content/notes/    # Markdown posts
lib/              # Site config adapter, posts parser, playground core
ccblog.config.ts  # the single rebrand surface
scripts/          # Build helpers (config validation, apps sync)
public/           # Static assets (pagefind index generated at build)
```

---

## Contributing

Bug fixes, new content-block directives, social icons, and docs are all welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). The golden rule: never hardcode identity into a component; route it through `ccblog.config.ts` via `lib/site.ts`.

## Author

Built and maintained by [crazycloudcc](https://github.com/crazycloudcc). Questions or forks welcome - see `/about` on the live site for contact links.

---

## License

[MIT](LICENSE) © 2026 crazycloudcc