Skip to content

Noveris-AI/Noveris-AI.github.io

BranchesTags

Repository files navigation

Passion's Log / 刘耀杰·言

A bilingual personal blog system built with Astro and deployed to GitHub Pages. 基于 Astro 的双语个人博客系统，部署在 GitHub Pages。

Legal Notice / 法律声明

  • This repository is not open-source software for unrestricted reuse.
  • 本仓库并非“可随意复用”的开源模板。
  • Usage is governed by LICENSE: no commercial use, no redeployment, no derivative distribution without prior written permission.
  • 具体使用边界以 LICENSE 为准：未经书面授权，禁止商用、禁止再部署、禁止衍生分发。

中文说明

1. 项目定位

这是一个面向个人品牌建设的双语博客系统，强调：

  • 高质量 UI（亮/暗主题 + 现代科技感）
  • 双语路由（/zh 与 /en）
  • 双内容来源（MD/MDX 文件 + Decap CMS 可视化）
  • 免费评论（giscus + GitHub Discussions）
  • 跨中英文静态搜索（文章 + 页面 + 项目 + 装备）
  • GitHub Actions 自动部署到 GitHub Pages

2. 功能清单

  • 首页、博客、关于、项目、装备、联系、搜索（中英双版本）
  • 文章页面目录（TOC）+ 上一篇/下一篇导航
  • 博客分类与标签筛选（自定义下拉组件，非浏览器默认 select）
  • 分类/标签显示国际化（支持 env 覆盖映射）
  • Contact 页面为双邮箱 + GitHub 图标入口
  • 站点主要配置支持 env 驱动，降低后续改动成本

3. 技术栈

  • Astro 5
  • MDX
  • Tailwind CSS
  • Decap CMS
  • giscus
  • GitHub Actions + GitHub Pages

4. 快速开始

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

开发地址：http://localhost:4321

生产构建：

npm run build

类型与内容检查：

npx astro check

5. 环境变量（核心）

请参考 .env.example。

重点变量：

  • 站点基础：PUBLIC_SITE_URL、PUBLIC_OG_IMAGE、PUBLIC_AVATAR_PATH
  • 品牌文案：PUBLIC_SITE_NAME_ZH/EN、PUBLIC_SITE_SUBTITLE_ZH/EN
  • 作者信息：PUBLIC_AUTHOR_ZH/EN、PUBLIC_SITE_INTRO_ZH/EN
  • 联系方式：PUBLIC_SOCIAL_GITHUB_URL、PUBLIC_CONTACT_EMAIL_CN、PUBLIC_CONTACT_EMAIL_GLOBAL
  • Decap：PUBLIC_SITE_REPO、PUBLIC_SITE_BRANCH、PUBLIC_DECAP_BASE_URL、PUBLIC_DECAP_AUTH_ENDPOINT
  • giscus：PUBLIC_GISCUS_REPO*、PUBLIC_GISCUS_CATEGORY_*
  • 国际化映射（可选）：PUBLIC_CATEGORY_MAP_ZH/EN、PUBLIC_TAG_MAP_ZH/EN

6. 内容管理（两种方式）

6.1 文件直写（推荐）

  • 中文：src/content/blog/zh/*.mdx
  • 英文：src/content/blog/en/*.mdx

6.2 Decap CMS 可视化

  • 地址：/admin
  • 配置由模板生成：
    • 模板：public/admin/config.template.yml
    • 输出：public/admin/config.yml
    • 命令：npm run sync:admin-config
  • dev/build 前会自动执行同步脚本（predev / prebuild）

7. 评论系统（giscus）

必须配置以下 Secrets：

  • PUBLIC_GISCUS_REPO_ID
  • PUBLIC_GISCUS_CATEGORY_GENERAL_ID
  • PUBLIC_GISCUS_CATEGORY_ENGINEERING_ID
  • PUBLIC_GISCUS_CATEGORY_LIFE_ID

未配置时，文章页会显示可读提示，而不是静默失败。

8. GitHub Pages 自动部署

工作流文件：.github/workflows/deploy.yml

已支持读取仓库 Variables / Secrets 注入配置。

部署流程：

  1. 推送到 main
  2. Actions 构建
  3. 发布到 GitHub Pages

9. Feishu CMS Bridge（自动同步飞书文档）

已内置飞书同步脚本：scripts/feishu-cms-bridge，入口命令：

npm run feishu:sync

建议在飞书云盘创建如下目录（根目录名可配置）：

Passion's Blogs/
  zh/
    AI/
    DevOps/
    LLM/
    MCP/
  en/
    AI/
    DevOps/
    LLM/
    MCP/

同步行为：

  • 只扫描该根目录下 zh / en 子树内的飞书文档（doc/docx）
  • 自动拉取正文并转 Markdown（依赖 feishu-docx）
  • 自动下载文档图片/附件到 public/uploads/feishu/...
  • 自动生成 Astro 需要的 frontmatter 并写入 src/content/blog/{zh|en}
  • 可选自动提交推送（FEISHU_GIT_AUTO_PUSH=true）

GitHub Actions 工作流：.github/workflows/feishu-sync.yml

  • 默认每天执行一次（cron：0 2 * * *）
  • 触发后自动同步并 push 到 main
  • push 后由现有 deploy.yml 自动发布到 GitHub Pages

所需 GitHub Secrets（至少）：

  • FEISHU_APP_ID
  • FEISHU_APP_SECRET
  • FEISHU_FOLDER_TOKEN（推荐直接填，最稳）

可选 Variables：

  • FEISHU_ROOT_FOLDER_NAME（默认 Passion's Blogs）
  • FEISHU_CLEAN_REMOVED（默认 true，会清理已从飞书移除的生成内容）

10. 常见维护命令

# 本地开发
npm run dev

# 重新生成 Decap 配置
npm run sync:admin-config

# 校验
npx astro check

# 构建
npm run build

# AI 翻译脚本
npm run translate -- --source src/content/blog/zh/your-post.mdx

English Guide

1. What This Project Is

This is a bilingual personal blog framework focused on:

  • polished UI (light/dark themes)
  • bilingual routing (/zh and /en)
  • dual writing workflows (MD/MDX + Decap CMS)
  • free comments via giscus
  • cross-language static search
  • GitHub Actions deployment to GitHub Pages

2. Feature Highlights

  • Home / Blog / About / Projects / Uses / Contact / Search (both locales)
  • TOC + previous/next navigation on post pages
  • custom dropdown filters for categories/tags (non-native select)
  • localized category/tag rendering with env-based overrides
  • contact section with two email addresses and GitHub icon link
  • env-driven site defaults for easier long-term maintenance

3. Tech Stack

  • Astro 5
  • MDX
  • Tailwind CSS
  • Decap CMS
  • giscus
  • GitHub Actions + GitHub Pages

4. Quick Start

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

Dev URL: http://localhost:4321

Build:

npm run build

Type/content checks:

npx astro check

5. Environment Variables

See .env.example for the full list.

Key groups:

  • site identity and branding (PUBLIC_SITE_*, PUBLIC_AUTHOR_*)
  • social/contact (PUBLIC_SOCIAL_GITHUB_URL, PUBLIC_CONTACT_EMAIL_*)
  • Decap backend (PUBLIC_SITE_REPO, PUBLIC_DECAP_BASE_URL, etc.)
  • giscus (PUBLIC_GISCUS_*)
  • optional taxonomy label overrides (PUBLIC_CATEGORY_MAP_*, PUBLIC_TAG_MAP_*)

6. Content Editing Modes

6.1 File-based authoring

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

6.2 Decap CMS

  • Admin URL: /admin
  • Config generation:
    • template: public/admin/config.template.yml
    • output: public/admin/config.yml
    • command: npm run sync:admin-config
  • predev / prebuild run this automatically.

7. giscus Setup

Required GitHub Secrets:

  • PUBLIC_GISCUS_REPO_ID
  • PUBLIC_GISCUS_CATEGORY_GENERAL_ID
  • PUBLIC_GISCUS_CATEGORY_ENGINEERING_ID
  • PUBLIC_GISCUS_CATEGORY_LIFE_ID

8. Deployment

Workflow: .github/workflows/deploy.yml

The workflow reads repository Variables/Secrets, builds the site, and deploys to GitHub Pages on push to main.

9. Feishu CMS Bridge (Auto Sync from Feishu)

This repo now includes a Feishu sync bridge under scripts/feishu-cms-bridge.

Run locally:

npm run feishu:sync

Recommended Feishu folder structure:

Passion's Blogs/
  zh/
    AI/
    DevOps/
    LLM/
    MCP/
  en/
    AI/
    DevOps/
    LLM/
    MCP/

What it does:

  • scans only this folder tree (zh / en)
  • converts Feishu doc/docx blocks into Markdown
  • downloads assets into public/uploads/feishu/...
  • generates frontmatter and writes posts to src/content/blog/{zh|en}
  • optionally commits and pushes automatically

Workflow: .github/workflows/feishu-sync.yml

  • scheduled daily (0 2 * * *)
  • can also run manually via workflow_dispatch
  • pushes to main, then existing deploy workflow publishes to GitHub Pages

Required GitHub Secrets:

  • FEISHU_APP_ID
  • FEISHU_APP_SECRET
  • FEISHU_FOLDER_TOKEN (recommended)

Optional Variables:

  • FEISHU_ROOT_FOLDER_NAME (default: Passion's Blogs)
  • FEISHU_CLEAN_REMOVED (default: true)

10. Maintenance Commands

npm run dev
npm run sync:admin-config
npx astro check
npm run build
npm run translate -- --source src/content/blog/zh/your-post.mdx

Directory Overview

src/
  components/
  config/
  content/
    blog/zh/
    blog/en/
  layouts/
  lib/
  pages/
public/
  admin/
  images/
  uploads/
scripts/
.github/workflows/

License

Use of this project is strictly governed by LICENSE.

About

noveris-ai-github-ionoveris-ai-deca.vercel.app

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages