中文文档

Astro Theme Hiro

Hiro is a minimalist yet powerful Astro blog template.

Preview

Home (Light)	Home (Dark)
Post Content	Decap CMS

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

# 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.
2. Authenticate the Wrangler CLI locally:

pnpm wrangler login

2) Configure Environment Variables

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.
• NODE_ENV=production: Required for pushing schema to the remote D1 database.

3) Create and Bind the D1 Database

Create a new D1 database:

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:

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:

# 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

# 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

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 Guide (Chinese): CONTRIBUTION.zh-CN.md
• Security Policy: SECURITY.md

License

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