From 116c74d8f448816c87e43f58c09f99d5b291d6d9 Mon Sep 17 00:00:00 2001 From: kennethcheng Date: Mon, 27 Apr 2026 16:26:13 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 3 +- README.md | 207 ++++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 150 insertions(+), 60 deletions(-) diff --git a/.gitignore b/.gitignore index 298a7e8..5392ef7 100644 --- a/.gitignore +++ b/.gitignore @@ -24,4 +24,5 @@ pnpm-debug.log* .idea/ -.vscode \ No newline at end of file +.vscode +src/content/docs/上下文工程理论与实践.md diff --git a/README.md b/README.md index edef7d0..e241d19 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,185 @@ -# LLM Log Frontend +# 📚 LLM Log Frontend -基于 **Astro 6**、**Tailwind CSS v4** 和 **Content Collections** 构建的现代化文档站点。 +> 基于 Astro v6 构建的现代化离线知识库系统，融合极客美学与静态站点极致性能。 -## 功能特性 +--- -- **Astro 6** - 下一代静态站点生成器，支持 Content Collections -- **Tailwind CSS v4** - 使用 `@tailwindcss/vite` 集成的原子化 CSS 框架 -- **排版插件** - 使用 `@tailwindcss/typography` 实现美观的 Markdown 渲染 -- **数学公式** - 通过 `remark-math` + `rehype-katex` 支持 LaTeX 数学公式 -- **代码高亮** - 使用 `rehype-pretty-code` 实现语法高亮（github-dark 主题） -- **中文优化** - 专为中文文档内容优化 +## ✨ 核心特性 -## 技术栈 +| 特性 | 说明 | +|------|------| +| 🚀 **极致性能** | Astro 静态生成，零运行时开销，首屏秒开 | +| 🔍 **离线全文搜索** | Pagefind 本地索引，无需后端，支持中文分词 | +| 🎨 **2026 极简 UI** | Tailwind CSS v4 驱动，半透明磨砂玻璃效果，明暗双模式 | +| 📐 **Markdown / MDX** | 原生支持 Markdown，混写 JSX 组件，渲染动态看板 | +| 🧮 **数学公式** | KaTeX 实时渲染，完美支持 LaTeX 公式 | +| 💻 **代码增强** | 语法高亮 (rehype-pretty-code)，一键复制，语言标签 | +| 🧭 **智能导航** | 左侧动态侧边栏 + 右侧 TOC 目录，滚动自动高亮 | +| 🌊 **SPA 体验** | Astro Transitions 无缝路由过渡，全站无刷新跳转 | +| 📱 **响应式布局** | 自适应桌面/平板/手机，移动端侧边栏自动隐藏 | -| 包名 | 版本 | 用途 | -|------|------|------| -| astro | ^6.1.9 | 静态站点生成器 | -| tailwindcss | ^4.2.4 | CSS 框架 | -| @tailwindcss/vite | ^4.2.4 | Tailwind Vite 插件 | -| @tailwindcss/typography | ^0.5.19 | Markdown 文章样式 | -| remark-math | ^6.0.0 | Markdown 数学插件 | -| rehype-katex | ^7.0.1 | KaTeX HTML 渲染器 | -| rehype-pretty-code | ^0.14.3 | 代码语法高亮 | +--- -## 项目结构 +## 🛠 技术栈 + +``` +Astro v6 ─┬── Tailwind CSS v4 (样式系统) + ├── @astrojs/mdx (MDX 混排) + ├── rehype-pretty-code (代码语法高亮) + ├── rehype-katex + KaTeX (数学公式渲染) + ├── remark-math (数学语法解析) + └── Pagefind (静态全文搜索) +``` + +**运行环境要求：** Node.js >= 22.12.0 + +--- + +## 📂 项目结构 ``` llm_log_frontend/ -├── src/ -│ ├── content/ -│ │ └── docs/ # Markdown 文档文件 -│ │ └── test.md -│ ├── layouts/ -│ │ └── BaseLayout.astro # 基础 HTML 布局 -│ ├── pages/ -│ │ ├── index.astro # 首页 -│ │ └── docs/ -│ │ └── [...slug].astro # 动态文档路由 -│ └── styles/ -│ └── global.css # Tailwind 入口 ├── public/ # 静态资源 -├── astro.config.mjs # Astro 配置 -├── tailwind.config.mjs # Tailwind + Typography 配置 +│ ├── favicon.ico +│ └── favicon.svg +├── src/ +│ ├── components/ # Astro 组件 +│ │ ├── BaseLayout.astro # 全局布局 (侧边栏 + 内容区) +│ │ ├── Sidebar.astro # 左侧导航栏 (动态渲染文档列表) +│ │ ├── TOC.astro # 右侧目录 (滚动监听 + 高亮跟随) +│ │ ├── Search.astro # 搜索框 (Pagefind 动态加载) +│ │ ├── CodeBlockHelper.astro # 代码块增强 (复制 + 语言标签) +│ │ └── ModernTable.astro # 现代表格组件 +│ ├── content/ +│ │ └── docs/ # 知识库文档 (MD/MDX) +│ ├── layouts/ +│ │ └── BaseLayout.astro # 基础布局模板 +│ ├── pages/ +│ │ ├── index.astro # 门户主页 (卡片网格导航) +│ │ └── docs/[...slug].astro # 文档路由 +│ ├── styles/ +│ │ └── global.css # 全局样式入口 +│ └── content.config.ts # Content Layer 配置 (Zod Schema) +├── astro.config.mjs ├── package.json -└── tsconfig.json +└── tailwind.config.mjs ``` -## 快速开始 +--- + +## 🚦 快速开始 + +### 安装依赖 ```bash -# 安装依赖 npm install +``` -# 启动开发服务器 +### 开发模式 + +```bash npm run dev +``` -# 构建生产版本 +启动后访问 `http://localhost:4321`，支持热更新。 + +### 构建生产版本 + +```bash npm run build +``` -# 预览生产构建 +构建流程自动执行： +1. `astro build` → 生成 `dist/` 静态站点 +2. `pagefind --site dist` → 扫描全文并生成搜索索引 + +### 本地预览 + +```bash npm run preview ``` -## 命令说明 +--- -| 命令 | 操作 | -|------|------| -| `npm run dev` | 在 `localhost:4321` 启动开发服务器 | -| `npm run build` | 构建输出到 `./dist/` | -| `npm run preview` | 本地预览生产构建 | -| `npm run astro -- --help` | 获取 Astro CLI 帮助 | +## 🎯 内容管理 -## 编写文档 +### 添加新文档 -在 `src/content/docs/` 目录下创建 Markdown 文件： +在 `src/content/docs/` 下创建 `.md` 或 `.mdx` 文件： ```markdown --- -title: "我的文档" +title: "文档标题" +description: "文档描述" --- -# 标题 - -内容含 LaTeX 公式：$E=mc^2$ - -```javascript -const hello = "world"; -``` +# 正文内容... ``` -文档会自动通过 `[...slug].astro` 页面进行路由。 +侧边栏和主页卡片网格将**自动更新**，无需手动配置路由。 -## License +### 使用 MDX 组件 + +`.mdx` 文件支持混写 JSX 组件： + +```mdx +--- +title: "交互式文档" +--- + +这是一段普通文本。 + + +``` + +--- + +## 🎨 设计系统 + +### 色彩方案 + +| 主题 | 背景 | 文字 | 强调色 | +|------|------|------|--------| +| 浅色 | `white` | `gray-900` | `blue-500` | +| 深色 | `#0a0c10` | `gray-100` | `blue-400` | + +### 组件样式 + +- **圆角**: `rounded-xl` / `rounded-lg` 统一 10-12px +- **阴影**: 代码块 `shadow-2xl`，卡片 `shadow-sm` +- **磨砂玻璃**: `bg-opacity-40` + `backdrop-blur` +- **过渡**: `transition-all` + `duration-300` + +--- + +## 📖 文档列表 + +| 文档 | 类型 | +|------|------| +| [2026-04-26](src/content/docs/2026-04-26.md) | 业务数据看板 | +| [test](src/content/docs/test.mdx) | MDX 交互测试 | +| [上下文工程理论与实践](src/content/docs/上下文工程理论与实践.md) | 理论文章 | + +--- + +## 🔄 构建流程 + +``` +源码 (src/) + │ + ├─ Astro 编译 ──────────────► dist/ (静态 HTML/CSS/JS) + │ + └─ Pagefind 索引 ───────────► dist/pagefind/ (搜索资源) + ├── pagefind-ui.js + ├── pagefind-ui.css + ├── pagefind*.js (索引分片) + └── pagefind.json (元数据) +``` + +最终产物为纯静态文件，可部署至任何静态托管服务（Vercel、Netlify、GitHub Pages 等）。 + +--- + +## 📄 License MIT