Weblog Setup Guide

Welcome

Weblog is a modern blog system built with Next.js, featuring MDX content, internationalization, dark mode, documentation center, and more.

Check out the live demo: aaronlamz.github.io/Weblog

Key Features

Clean, modern design
Dark/light theme support
Chinese and English bilingual support
Responsive layout
Glassmorphism navigation effects
Blog system with tags and archives
Documentation center with category organization and sidebar navigation

Tech Stack

Next.js 15 — Full-stack React framework
TypeScript — Type safety
Tailwind CSS — Styling solution
MDX — Markdown + JSX content format
next-intl — Internationalization support

Prerequisites

Make sure you have the following tools installed:

Node.js (v18 or higher)
pnpm (v8 or higher)
Git

Quick Start

Clone the repository:

bash
git clone https://github.com/aaronlamz/Weblog.git
cd Weblog

Install dependencies:

bash
pnpm install

Start the development server:

bash
pnpm dev

Your site should now be running at http://localhost:3000!

Configuration

Basic Site Configuration

The main configuration file is located at src/config/site.config.ts:

typescript
export const siteConfig = {
  name: 'Your Site Name',
  title: 'Your Site Title',
  description: 'Your site description',

  author: {
    name: 'Your Name',
    email: 'your.email@example.com',
    avatar: 'https://github.com/yourusername.png',
    bio: 'Your bio',
  },

  social: {
    github: 'https://github.com/yourusername',
    twitter: 'https://twitter.com/yourusername',
    email: 'your.email@example.com',
  }
}

Setting Up Giscus Comments

Weblog uses Giscus as its comment system, powered by GitHub Discussions:

Make sure your repository is public
Enable GitHub Discussions: Repository Settings → Features → Check Discussions
Install the Giscus GitHub App for your repository
Visit giscus.app, enter your repository info, and copy the generated config
Update the Giscus config in src/components/comments.tsx:

typescript
<Giscus
  repo="yourusername/reponame"
  repoId="your-repo-id"
  category="Announcements"
  categoryId="category-id"
  mapping="pathname"
  theme={theme === 'dark' ? 'dark_dimmed' : 'light'}
  lang={locale === 'zh' ? 'zh-CN' : 'en'}
/>

Internationalization

Weblog supports Chinese and English by default. Translation files are located at:

messages/en.json — English translations
messages/zh.json — Chinese translations

Using translations in components:

typescript
const t = useTranslations('namespace')
// ...
<div>{t('key')}</div>

Writing Blog Posts

Blog posts use MDX format and are stored in:

content/blog/en/ — English posts
content/blog/zh/ — Chinese posts

Each post requires frontmatter:

mdx
---
title: "Post Title"
description: "A short description"
date: "2024-03-20"
featured: false
tags: ["tag1", "tag2"]
---

Your post content...

Writing Documentation

Documentation uses MDX format, organized by category under content/docs/:

content/docs/
└── en/
    └── category-slug/
        ├── _meta.json        # Category metadata
        ├── article-slug.mdx  # Document file
        └── ...

Each category needs a _meta.json file:

json
{
  "title": "Category Title",
  "description": "Category description",
  "icon": "BookOpen",
  "order": 1
}

Document frontmatter:

mdx
---
title: "Document Title"
description: "Document description"
order: 1
---

Deployment

GitHub Pages

GitHub Actions workflows are already configured in .github/workflows/
Enable GitHub Pages in repository settings, set source to "GitHub Actions"
Push your code to deploy automatically:

bash
git add .
git commit -m "configure deployment"
git push

Custom Domain

Set customDomain in src/config/site.config.ts to auto-generate a CNAME file during deployment:

typescript
customDomain: 'www.yourdomain.com',

Customization

Styling

Weblog uses Tailwind CSS. Key config files:

tailwind.config.ts — Tailwind configuration
src/styles/globals.css — Global styles

Components

Key components you may want to customize:

src/components/header.tsx — Navigation and site header
src/components/footer.tsx — Site footer
src/components/theme-toggle.tsx — Dark/light mode toggle
src/components/language-switcher.tsx — Language switcher

Need Help?

If you run into issues:

Check GitHub Issues
Create a new issue if you can't find a solution