Getting Started with Astro-Theme-Aither

This guide covers everything you need to go from zero to a fully deployed, multilingual blog. Read it start to finish, or jump to the section you need.

Prerequisites

• Node.js 22 LTS or later
• pnpm 10 or later
• A GitHub account
• A Cloudflare account (for deployment)

Installation

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
corepack enable
pnpm install
pnpm validate
pnpm dev

Open http://localhost:4321 in your browser. You should see the default blog.

Project Structure

1
src/
2
├── components/        # Astro & React components
3
├── config/site.ts     # Site name, nav, footer, social links
4
├── content/posts/     # Blog posts organized by locale
5
│   ├── en/            # English posts
6
│   ├── zh-hans/       # Simplified Chinese posts
7
│   └── .../           # Other locales
8
├── i18n/              # Translations for UI text
9
├── layouts/           # Page layout (Layout.astro)
10
├── lib/               # Utilities (posts, formatter, etc.)
11
├── pages/             # Route pages
12
└── styles/global.css  # Tailwind v4 theme tokens

Configuration

Site Config

Edit src/config/site.ts — this is the single source of truth for your site.

1
export const siteConfig = {
2
  name: 'Your Blog Name',
3
  title: 'Your tagline here.',
4
  description: 'Your site description for SEO.',
5
  author: {
6
    name: 'Your Name',
7
    avatar: '',
8
  },
9
  // ...
10
};

Key sections:

Environment Variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

Leave any variable empty to disable that service. No code changes needed.

Site URL

The site URL is configured in one place — astro.config.mjs:

1
import { defineConfig } from 'astro/config';
2
import aither from '@aither/astro';
3

4
export default defineConfig({
5
  site: 'https://your-domain.pages.dev',
6
  integrations: [aither()],
7
});

All components read this value via import.meta.env.SITE. No need to configure it elsewhere.

Writing Posts

Create a Post

Create a new .mdx file in src/content/posts/en/:

1
---
2
title: My First Post
3
date: "2026-03-14T16:00:00+08:00"
4
category: General
5
description: A brief summary for SEO and social previews.
6
tags: [Topic, Another]
7
pinned: false
8
---
9

10
Your content starts here. Write in standard Markdown.

Frontmatter Reference

MDX Components

Since all posts use .mdx format, you can import and use React components directly in your content:

1
import MyChart from '@/components/MyChart'
2

3
Here is an interactive chart:
4

5
<MyChart data={[10, 20, 30]} />

This is optional — standard Markdown works exactly the same in .mdx files.

Pinning Posts

Set pinned: true in the frontmatter. Pinned posts appear at the top of the list with a pin icon, sorted by date among themselves.

Internationalization (i18n)

The theme supports 11 locales out of the box: English, Simplified Chinese, Traditional Chinese, Korean, French, German, Italian, Spanish, Russian, Indonesian, and Brazilian Portuguese.

Adding a Translated Post

Create the same filename in the target locale directory:

1
src/content/posts/en/my-post.mdx      # English original
2
src/content/posts/zh-hans/my-post.mdx  # Chinese translation
3
src/content/posts/fr/my-post.mdx       # French translation

Each file is independent — translate the frontmatter fields too.

Translating UI Text

UI strings (navigation, footer, buttons) live in src/i18n/messages/. Each locale has its own file:

1
src/i18n/messages/
2
├── en.ts
3
├── zh-hans.ts
4
├── fr.ts
5
└── ...

Edit the relevant file to change any UI text.

Browser Language Detection

The theme detects the visitor’s browser language and shows a banner suggesting to switch locale. The preference is saved in localStorage.

Custom Content Sections

Beyond blog posts, you can create custom content sections (translations, notes, tutorials, etc.) that get their own list page and detail pages, with a separate navigation entry.

Adding a Section

Step 1 — Register the collection in src/content.config.ts:

1
const translations = defineCollection({
2
  loader: glob({ pattern: '**/*.mdx', base: './src/content/translations' }),
3
  schema: contentSchema,
4
});
5

6
export const collections = { posts, translations };

Step 2 — Add section config in src/config/site.ts:

1
sections: [
2
  { id: 'translations', labelKey: 'translations' },
3
],

Step 3 — Add the nav label to each locale file in src/i18n/messages/:

1
nav: {
2
  blog: 'Blog',
3
  translations: 'Translations',  // add this line
4
  about: 'About',
5
},

Step 4 — Create content in src/content/translations/en/:

1
---
2
title: My Translation
3
date: "2026-03-14T16:00:00+08:00"
4
category: General
5
---
6

7
Your translated content here.

The list page (/translations/), detail pages (/translations/slug/), and navigation entry are generated automatically for all 11 locales.

Theming

Modes and Styles

The theme uses two layers:

• Color mode: Light, Dark, or System (follows OS preference)
• Theme style: default or any built-in custom style such as evolution

The defaults live in src/config/site.ts:

1
ui: {
2
  defaultMode: 'system', // 'light' | 'dark' | 'system'
3
  defaultStyle: 'default', // 'default' | custom style key
4
  showMoreThemesMenu: true, // true to show the custom theme picker
5
},

Picking Light, Dark, or System resets back to the main modes. Picking a custom style keeps your mode preference stored for later. Theme switching uses the View Transitions API for a smooth circular reveal animation.

If you want a simpler theme UI, keep mode switching enabled and set showMoreThemesMenu: false. This hides the custom style list while preserving the Light / Dark / System controls.

Theme labels are managed separately from theme keys:

• Theme keys such as evolution or threebody stay stable and are used only for state and CSS hooks
• User-facing labels are centralized in src/config/themes.ts
• Localized labels should translate generic descriptors, while brand names or strong IP names can stay partially untranslated when that reads better in the target locale

This keeps the theme system predictable in code while allowing locale-specific naming on the UI.

Colors

Edit CSS custom properties in src/styles/global.css. The theme uses Tailwind CSS v4 @theme tokens:

1
:root {
2
  --color-link: ...;
3
  --color-link-hover: ...;
4
  --color-nav-text: ...;
5
  /* etc. */
6
}

Both light and dark modes have their own set of color tokens.

Fonts

The theme uses a system sans-serif font stack by default, following Apple Human Interface Guidelines typography parameters (17px / 1.47 / -0.022em). To use a custom font, update the font-family values in the Tailwind theme configuration.

SEO and AI

Every page is optimized for search engines and AI agents:

Deployment

Cloudflare Pages

Best practice: create the Pages project first. The workflow uses your repository name by default, or CLOUDFLARE_PAGES_PROJECT_NAME if you need to override it.

Set these GitHub Secrets:

Then run pnpm validate and push to main.

Custom Domain

Add a custom domain in the Cloudflare Pages dashboard under your project → Custom domains.

Tech Stack

Useful Commands

Version Scheme

Public release tags follow CalVer-style names such as v2026.04.08.