Real-Fruit-Snacks/Surge
GitHub: Real-Fruit-Snacks/Surge
Surge 将 Markdown 命令笔记编译为带模糊搜索、变量替换和离线 PWA 功能的静态命令参考站点。
Stars: 0 | Forks: 0
# Surge
支持模糊搜索、变量替换和离线 PWA 的可搜索命令参考工具。
[](https://github.com/Real-Fruit-Snacks/Surge/releases)
[](LICENSE)
## 概述
Surge 是一个由 markdown 笔记生成的静态命令参考工具。只需将笔记放入 `notes/` 目录，运行 `build.py`，网站便会编译生成一个涵盖标题、分类、标签、笔记和代码块的模糊搜索索引。格式为 `
` 的占位符会在用户界面中高亮显示，你可以设定一次变量值，在复制到剪贴板时即可自动完成替换。工作区（Workspaces）可以为不同环境（例如 Lab、Production 或自定义环境）保存命名的变量集合。
Fuse.js 驱动了模糊搜索功能，在整个索引范围内提供低于 50 毫秒的响应时间。Service worker 会缓存所有静态资源，从而在首次访问后实现完全离线功能。笔记采用带有 YAML frontmatter 的标准 markdown 格式编写，这使得 Surge 能够与 Obsidian 完全兼容。
在线演示地址：https://Real-Fruit-Snacks.github.io/Surge/
## 主要功能
- **模糊搜索**：使用 Fuse.js 对标题、分类、标签、笔记和命令进行低于 50 毫秒的搜索。
- **变量替换**：高亮显示 `` 字段，并在复制时自动替换为相应的值。
- **环境工作区**：针对不同环境保存并切换自定义的变量集合。
- **Catppuccin 主题**：支持四种 Catppuccin 配色：Mocha、Macchiato、Frappe 和 Latte。
- **离线功能**：构建为 Progressive Web App (PWA)，利用 service worker 实现完全离线访问。
- **Markdown 兼容性**：支持带有 YAML frontmatter 的标准 markdown 文件，与 Obsidian 兼容。
- **极简构建**：使用 Python 3 标准库进行编译，无需 Node 或 npm 依赖。
- **平台支持**：在 Chrome、Firefox、Safari、Edge 上完全兼容搜索、变量替换、主题切换、键盘导航、复制功能和语法高亮等功能。
## 开始使用 / 安装说明
### 前置条件
- Python 3.7 或更高版本
### 安装指南
克隆仓库并构建搜索索引：
```
git clone https://github.com/Real-Fruit-Snacks/Surge.git
cd Surge
# 从 markdown 笔记构建搜索索引
python3 build.py
# 启动本地 web 服务器
python3 -m http.server 8080 --directory site
```
打开浏览器并访问 `http://localhost:8080` 即可进入操作界面。
验证构建和服务器状态：
```
# 验证生成的索引文件
ls -la site/commands.json
# 验证本地服务器响应
curl -s http://localhost:8080 | head -n 5
```
## 使用说明
### 键盘快捷键
- `/`：聚焦搜索框
- `方向键`：导航条目
- `Enter`：展开或折叠条目卡片
- `c`：复制命令到剪贴板
- `v`：打开变量面板
- `w`：切换代码自动换行
- `Escape`：清除搜索或关闭面板
### 变量模板
命令中可以包含占位符：
```
ssh @ -p
```
设置变量时会自动更新它们：
```
ssh admin@10.0.0.1 -p 22
```
工作区允许配置不同的变量：
- **Lab 工作区**：`=10.0.0.50`，`=admin`
- **Production 工作区**：`=192.168.1.100`，`=deploy`
### 笔记格式化
笔记的结构应当如下所示：
```
---
tags: [networking, linux]
---
## Searchable Card 标题
### Step 标题
```bash
ssh @ -p
```
```
Step headings containing `[optional]` are excluded from "Copy All" actions.
### Tag 过滤
Modify `site/config.js` to configure default visible tags:
```javascript
const TOGGLES = [
{ tag: 'Draft', label: 'Drafts', default: false },
{ tag: 'Reference', label: 'Reference', default: true },
{ tag: 'Lab', label: 'Lab Notes', default: false }
];
```
## 架构 / 文件结构
```
Surge/
├── build.py Markdown parser and index generator
├── site/
│ ├── index.html Single-page shell
│ ├── app.js Application logic
│ ├── config.js Filter tag configuration
│ ├── styles.css Catppuccin themes and styling
│ ├── commands.json Generated search index (gitignored)
│ ├── sw.js Service worker for offline support
│ └── vendor/ Bundled Fuse.js and Highlight.js
├── notes/ Markdown source files by category
└── docs/ GitHub Pages project site
```
- **构建**：`build.py` 解析 markdown 并在 `site/commands.json` 生成 JSON 索引。
- **搜索**：Fuse.js 在浏览器中运行并高亮匹配的结果。
- **变量**：剪贴板工具使用工作区的值替换 `` 字符串。
- **主题**：通过 CSS 自定义属性和 `localStorage` 实现持久化。
- **离线**：Service worker 在安装时缓存所有静态资源。
- **部署**：静态站点可部署到任何 Web 服务器或在本地运行。
## 贡献指南
在提交贡献之前，请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 中的指南。
## 许可证
本项目基于 MIT 许可证授权。详情请参阅 [LICENSE](LICENSE)。标签：Markdown, PWA, SOC Prime, 前端, 命令参考, 开发工具, 数据可视化, 模糊搜索, 自定义脚本