186 lines
4.9 KiB
Markdown
186 lines
4.9 KiB
Markdown
# 📚 LLM Log Frontend
|
||
|
||
> 基于 Astro v6 构建的现代化离线知识库系统，融合极客美学与静态站点极致性能。
|
||
|
||
---
|
||
|
||
## ✨ 核心特性
|
||
|
||
| 特性 | 说明 |
|
||
|------|------|
|
||
| 🚀 **极致性能** | Astro 静态生成，零运行时开销，首屏秒开 |
|
||
| 🔍 **离线全文搜索** | Pagefind 本地索引，无需后端，支持中文分词 |
|
||
| 🎨 **2026 极简 UI** | Tailwind CSS v4 驱动，半透明磨砂玻璃效果，明暗双模式 |
|
||
| 📐 **Markdown / MDX** | 原生支持 Markdown，混写 JSX 组件，渲染动态看板 |
|
||
| 🧮 **数学公式** | KaTeX 实时渲染，完美支持 LaTeX 公式 |
|
||
| 💻 **代码增强** | 语法高亮 (rehype-pretty-code)，一键复制，语言标签 |
|
||
| 🧭 **智能导航** | 左侧动态侧边栏 + 右侧 TOC 目录，滚动自动高亮 |
|
||
| 🌊 **SPA 体验** | Astro Transitions 无缝路由过渡，全站无刷新跳转 |
|
||
| 📱 **响应式布局** | 自适应桌面/平板/手机，移动端侧边栏自动隐藏 |
|
||
|
||
---
|
||
|
||
## 🛠 技术栈
|
||
|
||
```
|
||
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/
|
||
├── public/ # 静态资源
|
||
│ ├── 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
|
||
└── 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
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 内容管理
|
||
|
||
### 添加新文档
|
||
|
||
在 `src/content/docs/` 下创建 `.md` 或 `.mdx` 文件：
|
||
|
||
```markdown
|
||
---
|
||
title: "文档标题"
|
||
description: "文档描述"
|
||
---
|
||
|
||
# 正文内容...
|
||
```
|
||
|
||
侧边栏和主页卡片网格将**自动更新**，无需手动配置路由。
|
||
|
||
### 使用 MDX 组件
|
||
|
||
`.mdx` 文件支持混写 JSX 组件：
|
||
|
||
```mdx
|
||
---
|
||
title: "交互式文档"
|
||
---
|
||
|
||
这是一段普通文本。
|
||
|
||
<ModernTable headers={["列1", "列2"]} data={[...]} />
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 设计系统
|
||
|
||
### 色彩方案
|
||
|
||
| 主题 | 背景 | 文字 | 强调色 |
|
||
|------|------|------|--------|
|
||
| 浅色 | `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
|