personal-web-template — Next.js Portfolio Template

SHA-256: 7f791309d3eec697ec0825529aa122cc88b185be6fa86ec10800280dae5ecb7c

2026-10-03T15:11:42.529Z

# personal-web-template

A polished **personal site starter** for developers who want a modern personal website with a strong landing page, a media-friendly projects section, and a file-based blog — without adding a CMS.

Built with **Next.js**, **TypeScript**, **Tailwind CSS**, and a **file-based MDX content workflow**.

Created by **Xinjie** — shaped by a practical view of personal sites for builders, developers, and product-minded people.

This repo is meant to be **forked, customized, and deployed**.

---

## Preview

![personal-web-template preview](./page-shot.png)

---

## What this template is

This template is for people who want:

- a homepage that feels like a real personal brand page, not a default post index
- a projects section that works more like a portfolio showcase than a plain list
- a blog powered by files in the repo
- an About page that is structured, but still personalizable
- a starter that already feels publishable before heavy redesign

A lot of personal-site starters land at one of two extremes:

1. **Too bare** — technically fine, but still obviously a scaffold
2. **Too opinionated** — visually strong, but annoying to adapt

This repo aims for the middle:

- **polished enough to publish**
- **structured enough to reuse**
- **simple enough to fork quickly**
- **flexible enough to make your own**

---

## Core highlights

- **Landing-style homepage** instead of a plain content index
- **File-based MDX blog and projects** stored inside the repo
- **Media-friendly Projects page** with richer metadata like summary, status, role, tags, period, cover, and optional video
- **Modular About page** driven by config instead of hardcoded copy
- **Dark / light theme** with a unified animated background system
- **Config-first customization** for site identity, homepage copy, and about-page structure
- **SEO foundations** included: metadata, sitemap, robots, not-found, OG route placeholder

---

## Current page structure

- `/` — landing / homepage
- `/about` — modular about page
- `/projects` — portfolio showcase
- `/projects/[slug]` — project detail page from MDX
- `/blog` — blog index
- `/blog/[slug]` — blog post detail page from MDX
- `/contact` — simple contact page

---

## Tech stack

- **Framework:** Next.js 15
- **Language:** TypeScript
- **Styling:** Tailwind CSS + CSS variables
- **Content:** file-based MDX + gray-matter + next-mdx-remote
- **Rendering model:** App Router + static generation where appropriate

---

## Quick start

Install dependencies:

```bash
npm install
```

Run the dev server:

```bash
npm run dev
```

Then open:

```txt
http://localhost:3000
```

---

## Start here after forking

If you only want the fastest path to your own version, do this in order:

### 1. Update site identity
Edit:

```bash
src/config/site.ts
```

Change:
- site name
- title / description
- URL
- author info
- socials
- nav

### 2. Rewrite the homepage
Edit:

```bash
src/config/home.ts
```

Change:
- hero headline
- description
- CTA labels / links
- feature cards
- positioning pillars
- status strip

### 3. Replace About page content
Edit:

```bash
src/config/about.ts
```

Change:
- headline
- manifesto
- bio
- values
- work style
- interests
- current focus
- stack
- availability

### 4. Replace example content
Edit:

```bash
src/content/projects/
src/content/blog/
```

### 5. Replace placeholder assets
Current placeholder assets live under:

```bash
public/
```

### 6. Verify locally

```bash
npm run build
```

That sequence should get most users from fork → local personalized version very quickly.

---

## What it includes

- **Next.js App Router** structure
- **TypeScript-first** codebase
- **MDX-based content system** for blog posts and projects
- **Dark / light theme** with CSS variable theming
- **Reusable config layer** for site identity and core page content
- **Portfolio-style Projects page** with richer project cards
- **Modular About page** with configurable sections
- **SEO-ready app shell** for personal site use cases

---

## Documentation map

Use the docs like this:

- [`docs/customization.md`](./docs/customization.md) — what to change first after forking
- [`docs/deployment.md`](./docs/deployment.md) — how to verify and deploy
- [`docs/release-checklist.md`](./docs/release-checklist.md) — final checks before publishing the template publicly
- [`docs/github-release-notes.md`](./docs/github-release-notes.md) — suggested GitHub description, topics, and first release copy
- [`docs/repo-architecture.md`](./docs/repo-architecture.md) — how the repo is organized internally
- [`docs/roadmap.md`](./docs/roadmap.md) — what still needs polishing or future expansion

---

## Project structure

```bash
personal-web-template/
├─ public/
├─ src/
│  ├─ app/
│  ├─ components/
│  ├─ config/
│  ├─ content/
│  ├─ data/
│  ├─ hooks/
│  ├─ lib/
│  ├─ styles/
│  └─ types/
├─ docs/
├─ README.md
└─ package.json
```

---

## Content system direction

This template currently adopts a **file-based MDX content workflow**.

That means:
- blog posts and projects live in `src/content/**`
- frontmatter is parsed with `gray-matter`
- MDX is rendered with `next-mdx-remote`
- the content layer is intentionally simple, readable, and easy to fork

It does **not** currently use Contentlayer as the active content pipeline.

A placeholder `contentlayer.config.ts` still exists in the repo, but it is there only as a compatibility / future-extension stub. It is **not part of the current runtime architecture**.

Why this route was chosen:
- fewer moving parts for template users
- easier onboarding for people forking the repo
- clearer debugging when editing local content files
- enough structure for a personal site without adding build-time schema tooling yet

If you want to extend the content system, the intended default is:
1. keep content in MDX files
2. evolve frontmatter deliberately
3. update `src/lib/content.ts` and the related types as the schema grows

If you personally prefer Contentlayer, you can add it in your own fork — but this template should currently be understood as a **file-based MDX starter, not a Contentlayer starter**.

---

## Content model

### Blog posts
Create files in:

```bash
src/content/blog/
```

Example frontmatter:

```md
---
title: "My First Post"
description: "A short intro post"
date: "2026-03-26"
tags: ["nextjs", "personal-site"]
published: true
cover: "/images/blog/first-post.jpg"
---
```

### Projects
Create files in:

```bash
src/content/projects/
```

Example frontmatter:

```md
---
title: "Personal Web Template"
description: "A reusable personal site starter"
summary: "A polished portfolio + blog starter for developers"
slug: "personal-web-template"
stack: ["Next.js", "TypeScript", "Tailwind CSS"]
featured: true
featuredOrder: 1
status: "shipped"
role: "Template design + implementation"
client: "Self-initiated"
period: "2026"
tags: ["starter", "portfolio", "blog"]
github: "https://github.com/your-name/personal-web-template"
demo: "https://your-demo-url.com"
cover: "/images/projects/my-project-cover.png"
video: "https://www.youtube.com/embed/..." # optional
category: "Open Source"
year: "2026"
---
```

---

## Important local dev workflow note

During active development, keep:

```bash
npm run dev
```

running while you iterate.

When you want a production verification pass:

1. stop the dev server
2. run:

```bash
npm run build
```

This helps avoid local `.next` cache / chunk confusion during iteration.

---

## Build for production

```bash
npm run build
npm run start
```

---

## Good fit if...

This template is a good fit if you want:
- a personal website starter with a stronger visual baseline
- a portfolio + blog in one repo
- content stored as files
- a modern starter without adding a CMS backend
- a template that can be personalized mostly through config + MDX

## Probably not the right fit if...

This is probably not the right fit if you want:
- a CMS-backed editorial workflow
- a multi-author publishing platform
- a no-code website builder
- a full marketing-site framework with many business pages

---

## Current strengths

At the current stage, this project already has:

- a clear starter-template direction
- a reusable config layer
- a functioning file-based content system
- a stronger homepage than a typical starter
- a portfolio page that feels more like showcase than list
- a modular about page with room for expression
- a unified animated background system

---

## What still needs polishing

This repo is already usable, but if the goal is a stronger open-source release, the next layers are:

- tighter documentation and onboarding
- better placeholder assets / screenshots / demo materials
- richer portfolio content schema over time
- stronger release packaging for GitHub discovery

See [`docs/roadmap.md`](./docs/roadmap.md).

---

## Author

Created by **Xinjie**.

- GitHub: <https://github.com/KYD-bloody>

The template defaults remain intentionally easy to replace (`Your Name`, `your-handle`, `your-domain.com`) so that people forking the repo can adapt it quickly without inheriting someone else's personal site.

---

## License

MIT — see [`LICENSE`](./LICENSE).