astro-theme-hiro — Astro 博客模板

SHA-256: 1bdc9043cc910e4411398966e78e8398b5101e88c70bf4d6214a015d569b1514

2026-10-02T21:01:30.326Z

[中文文档](./README.zh-CN.md)

# Astro Theme Hiro

<p align="center">
  <img alt="Astro" src="https://img.shields.io/badge/Astro-FF5D01?style=for-the-badge&logo=astro&logoColor=white">
  <img alt="Cloudflare" src="https://img.shields.io/badge/Cloudflare-F38020?style=for-the-badge&logo=Cloudflare&logoColor=white">
  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white">
  <img alt="Tailwind CSS" src="https://img.shields.io/badge/Tailwind_CSS-38B2AC?style=for-the-badge&logo=tailwind-css&logoColor=white">
</p>

Hiro is a minimalist yet powerful Astro blog template.

## Preview

<table>
  <tr>
    <td align="center">
      <img src="./.github/readme/index-light.png" alt="Home light mode" /><br />
      Home (Light)
    </td>
    <td align="center">
      <img src="./.github/readme/index-dark.png" alt="Home dark mode" /><br />
      Home (Dark)
    </td>
  </tr>
  <tr>
    <td align="center">
      <img src="./.github/readme/post-content.png" alt="Post content page" /><br />
      Post Content
    </td>
    <td align="center">
      <img src="./.github/readme/decap-cms.png" alt="Decap CMS admin" /><br />
      Decap CMS
    </td>
  </tr>
</table>

## Key Features

- Automatic email notifications for new friend-link requests and comments.
- D1 + Workers-powered backend enabling likes and comments at zero cost.
- Built-in Decap CMS for easier blog post editing.
- Pagefind integration for fast on-site search.

## Project Structure (Template User Perspective)

### Configuration Files

- `src/consts.ts`: Core site identity, homepage copy, and feature flags (`ENABLE_*`).
- `astro.config.ts`: Astro integrations, output mode, and markdown/search/sitemap settings.
- `wrangler.jsonc`: Cloudflare Worker configuration and D1 database bindings.
- `.env`: Build-time variables and API credentials (site URL, repo info, D1 config).
- `.dev.vars`: Runtime secrets for local Worker preview.
- `src/content.config.ts`: Content collection schemas and loader rules.

### Content Directory

- `src/content/blog/`: Your blog posts (`.md` / `.mdx`).
- `src/content/project/`: Portfolio and project showcase entries.
- `src/content/friend/`: Friend links and blogroll entries.

## Local Development Guide

### Prerequisites

- Node.js 20+
- pnpm 10+

### Quick Start

```bash
# Install dependencies
pnpm install

# Prepare environment variable files
cp .env.example .env
cp .dev.vars.example .dev.vars

# Start the development server
pnpm dev
```

After startup, visit `http://localhost:4321` in your browser.

## Deployment Tutorial (Cloudflare Worker + D1)

### 1) Prepare Your Cloudflare Account

1. Sign up or log in to your [Cloudflare Dashboard](https://dash.cloudflare.com/).
2. Authenticate the Wrangler CLI locally:

```bash
pnpm wrangler login
```

### 2) Configure Environment Variables

```bash
cp .env.example .env
cp .dev.vars.example .dev.vars
```

Update `.env` with your specific details before deploying:

- `SITE_URL`: Your final production URL.
- `GITHUB_REPO` / `REPO_BRANCH`: Your GitHub repository format (`username/repo`) and branch name.
- `CLOUDFLARE_ACCOUNT_ID`: Your Cloudflare Account ID (found on the right sidebar of the Cloudflare dashboard).
- `APP_CF_ACCOUNT_ID`: Same as above.
- `APP_CF_API_TOKEN`: Cloudflare API Token with **D1 Edit** permissions. [Create one here](https://dash.cloudflare.com/profile/api-tokens).
- `NODE_ENV=production`: Required for pushing schema to the remote D1 database.

### 3) Create and Bind the D1 Database

Create a new D1 database:

```bash
pnpm wrangler d1 create astro-blog-template
```

Update your `wrangler.jsonc` with the output provided by the command:

- Update `d1_databases[0].database_name` and `database_id`.
- Update `name` if you want a different Worker name.

**Important:** Also set `APP_CF_D1_DATABASE_ID` in your `.env` file to the same database ID.

### 4) Initialize the Database Schema

Push the Drizzle schema to your remote D1 database:

```bash
pnpm db:push
```

### 5) Configure Production Secrets

Depending on the features enabled in `src/consts.ts`, securely store your runtime secrets in Cloudflare using Wrangler:

```bash
# Optional: For JWT Authentication (Generate using `openssl rand -hex 32` or any random strong string)
pnpm wrangler secret put JWT_KEY

# Optional: For Cloudflare Turnstile (Anti-spam) - Get it from https://dash.cloudflare.com/?to=/:account/turnstile
pnpm wrangler secret put CF_CAPTCHA_SECRETKEY

# Optional: For Email Notifications via Resend - Get it from https://resend.com/api-keys
pnpm wrangler secret put RESEND_API_KEY
pnpm wrangler secret put RESEND_EMAIL_FROM
pnpm wrangler secret put RESEND_EMAIL_TO

# Optional: For Decap CMS GitHub OAuth - Get it from https://github.com/settings/developers (OAuth Apps)
pnpm wrangler secret put GITHUB_CLIENT_ID
pnpm wrangler secret put GITHUB_CLIENT_SECRET
```

### 6) Build and Deploy

```bash
# Generate the Astro production build
pnpm build

# Deploy to Cloudflare Workers
pnpm wrangler deploy
```

> **Note**: `pnpm build` not only generates Astro output, but also runs a D1 content sync script.

### 7) Post-Deployment Verification

1. Visit your deployed Worker URL to ensure the homepage and articles load correctly.
2. Verify system routes: `/rss.xml`, `/sitemap-index.xml`, and `/search`.
3. If enabled, test the comment system, friend link submissions, email notifications, and the CMS admin panel (`/admin`).

## Common Commands

```bash
pnpm dev          # Start local development server
pnpm build        # Generate production build (with wrangler types)
pnpm build:static # Generate static-only output
pnpm preview      # Local Cloudflare-style preview
pnpm code:check   # Run Astro check + Biome lint/format
pnpm db:push      # Push database schema changes via Drizzle
pnpm sync         # Sync remote D1 data to local SQLite database
```

## Documentation & Policies

- Contribution Guide: [`CONTRIBUTION.md`](./CONTRIBUTION.md)
- Contribution Guide (Chinese): [`CONTRIBUTION.zh-CN.md`](./CONTRIBUTION.zh-CN.md)
- Security Policy: [`SECURITY.md`](./SECURITY.md)

## License

This project is licensed under the terms described in the `LICENSE` file.