Passion's Log

English | 简体中文

A bilingual personal blog system built with Astro, file-based authoring, Feishu auto-sync pipeline, and GitHub Pages deployment.

Legal Notice

This repository is not an unrestricted open-source template. Usage is governed by LICENSE. Without prior written permission, commercial use, redeployment, and derivative distribution are prohibited.

What This Project Includes

• Bilingual site structure: /zh and /en
• Static blog rendering with Astro + MDX
• Locale switch and translation pairing via translationKey
• Light/Dark theme, post TOC, previous/next navigation, code copy button
• Category and tag filters with i18n label mapping
• Local static search index endpoint: /search-index.json
• /admin is disabled by default for security hardening
• Optional Feishu Drive -> content sync (with optional AI zh->en translation)
• GitHub Actions deployment to GitHub Pages

Tech Stack

• Astro 5
• MDX
• Tailwind CSS (@tailwindcss/typography)
• giscus (GitHub Discussions)
• GitHub Actions + GitHub Pages
• Feishu API + feishu-docx

Project Structure

src/
  components/
  config/
  content/
    blog/
      zh/
      en/
  layouts/
  lib/
  pages/
    zh/
    en/
    search-index.json.ts
  styles/
public/
  images/
  uploads/
oauth-proxy/
  api/
  vercel.json
scripts/
  translate-post.mjs
  feishu-cms-bridge/
.github/workflows/
  deploy.yml
  feishu-sync.yml

Prerequisites

• Node.js >= 20 (Node 22 is used in CI)
• npm

Quick Start

npm install
cp .env.example .env.local
npm run dev

Local URL: http://localhost:4321

Build and check:

npm run check
npm run build

Available Scripts

npm run dev                 # local dev server
npm run build               # production build
npm run preview             # preview built site
npm run check               # astro check
npm run check:all           # check + build
npm run translate -- --source src/content/blog/zh/your-post.mdx
npm run feishu:sync         # sync Feishu folder into src/content/blog

Routing and Content Model

• Site root (/) performs language-based redirect (zh if browser language starts with zh, otherwise en).
• Main routes per locale:
  • /[locale]
  • /[locale]/blog
  • /[locale]/about
  • /[locale]/projects
  • /[locale]/uses
  • /[locale]/contact
  • /[locale]/search
  • /[locale]/[...slug] (post pages)
• Search index endpoint:
  • /search-index.json

Post schema is defined in src/content.config.ts, including:

• core fields: lang, title, description, date, updated, category, tags, draft, translationKey
• optional fields: summary, seoDescription, keywords, social, heroImage

Environment Variables

See .env.example for the full list.

Key groups:

• Site branding/SEO: PUBLIC_SITE_*, PUBLIC_AUTHOR_*, PUBLIC_OG_IMAGE
• Social/contact: PUBLIC_SOCIAL_GITHUB_URL, PUBLIC_CONTACT_EMAIL_*
• giscus: PUBLIC_GISCUS_*
• Taxonomy display overrides:
  • PUBLIC_CATEGORY_MAP_ZH, PUBLIC_CATEGORY_MAP_EN
  • PUBLIC_TAG_MAP_ZH, PUBLIC_TAG_MAP_EN
• Feishu bridge: FEISHU_*, TRANSLATE_*

Content Editing Workflows

1. File-Based Authoring

• Chinese posts: src/content/blog/zh/*.mdx
• English posts: src/content/blog/en/*.mdx

2. AI Translation Helper

npm run translate -- --source src/content/blog/zh/your-post.mdx

• reads config/translation.config.json
• uses prompt template config/translation.prompt.md
• writes translated post to src/content/blog/en/
• optionally creates .review.md QA checklist

Admin Route Policy

• Public /admin route is intentionally disabled.
• If you need CMS UI again later, deploy it behind a private auth gateway and do not expose it on the public Pages domain.

giscus Setup

Required IDs (typically configured as GitHub Secrets in CI):

• PUBLIC_GISCUS_REPO_ID
• PUBLIC_GISCUS_CATEGORY_GENERAL_ID
• PUBLIC_GISCUS_CATEGORY_ENGINEERING_ID
• PUBLIC_GISCUS_CATEGORY_LIFE_ID

If missing, post pages display a fallback hint instead of a broken widget.

Feishu CMS Bridge

Bridge code: scripts/feishu-cms-bridge/

Main behavior:

• scans Feishu folder tree (zh / en)
• converts doc/docx to Markdown/MDX
• downloads assets to public/uploads/feishu/...
• generates frontmatter and writes posts into src/content/blog/{zh|en}
• optionally translates zh->en and generates SEO metadata via AI
• optionally auto-commits and pushes

Local run:

npm run feishu:sync

Workflow automation:

• feishu-sync.yml
• scheduled daily (0 2 * * *) + manual trigger

CI/CD and Deployment

Deploy Workflow

deploy.yml

Triggers:

• push to main
• successful workflow_run from Feishu CMS Sync
• manual dispatch

Build output is deployed to GitHub Pages via actions/deploy-pages.

Feishu Sync Workflow

feishu-sync.yml

• checks out full history
• runs npm run feishu:sync
• auto-pushes synced content to main
• then deployment is handled by deploy.yml

Common Maintenance

• Update project/about/uses/contact static data in src/lib/page-data.ts
• Adjust category/tag display mapping in env (PUBLIC_CATEGORY_MAP_*, PUBLIC_TAG_MAP_*)
• Update site identity defaults in src/config/site.ts and env vars
• Keep locale pairs aligned via translationKey

Troubleshooting

• giscus not rendered:
  • check PUBLIC_GISCUS_REPO_ID and category IDs
• Feishu sync exits early:
  • verify FEISHU_APP_ID, FEISHU_APP_SECRET, and folder token/name
  • verify TRANSLATE_API_KEY when AI translation is enabled
  • tune FEISHU_AI_TIMEOUT_MS if the provider is slow for long documents
  • keep FEISHU_AI_FAIL_ON_TRANSLATION_ERROR=false to let nightly sync continue with zh content and preserved stale en output on retryable AI failures

License

See LICENSE.