文档
This commit is contained in:
parent
42d8063886
commit
116c74d8f4
3
.gitignore
vendored
3
.gitignore
vendored
@ -24,4 +24,5 @@ pnpm-debug.log*
|
||||
.idea/
|
||||
|
||||
|
||||
.vscode
|
||||
.vscode
|
||||
src/content/docs/上下文工程理论与实践.md
|
||||
|
||||
207
README.md
207
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: "交互式文档"
|
||||
---
|
||||
|
||||
这是一段普通文本。
|
||||
|
||||
<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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user