\r \r

XI Markdown Editor 本地Markdown编辑器\r

\r English | 中文\r \r

⚠️ Security Notice / 安全声明\r

\r English: \r This skill runs a local-only Flask server for markdown editing. It does NOT:\r

• Connect to external servers (except CDN for libraries)\r
• Send data outside your local machine\r
• Require internet access for core functionality\r
• Execute arbitrary code\r \r Security Features:\r
• Localhost-only server (127.0.0.1)\r
• No external network connections\r
• File operations limited to user-specified paths\r
• All code is open and inspectable\r \r 中文: \r 此技能运行仅限本地的Flask服务器进行Markdown编辑。它不会：\r
• 连接到外部服务器（CDN库除外）\r
• 将数据发送到本地机器之外\r
• 需要互联网访问核心功能\r
• 执行任意代码\r \r 安全特性:\r
• 仅限本地主机服务器 (127.0.0.1)\r
• 无外部网络连接\r
• 文件操作仅限于用户指定的路径\r
• 所有代码都是开放且可检查的\r \r ---\r \r

Overview / 概述\r

\r English: \r A web-based markdown editor that runs locally with a Flask server and provides real-time editing with live preview. Features include sync scrolling between editor and preview, comprehensive markdown toolbar, and direct file saving.\r \r 中文: \r 基于Web的Markdown编辑器，本地运行Flask服务器，提供实时编辑和预览功能。包括编辑器与预览同步滚动、完整的Markdown工具栏、直接文件保存。无需安装，就可以在本地直接编辑markdown。\r \r ---\r \r

Features / 功能特性\r

\r English: \r

• Real-time Preview: Edit on left, see live preview on right\r
• Sync Scrolling: Scroll one side, the other follows automatically\r
• Toolbar: Icons for all markdown tags (H1, H2, bold, italic, lists, etc.)\r
• File Operations: Open any markdown file, edit, save back to original file\r
• Local Server: Flask-based backend with RESTful API\r
• Responsive Design: Works on desktop and mobile\r
• Dark Theme: Modern dark UI with white text\r
• URL Parameter Support: Open files via URL parameter ?file=path\r
• Auto Server Shutdown: Server automatically closes when page is closed\r
• Theme Toggle: Switch between dark and light themes\r
• Relative Path Support: Support for relative paths from workspace\r \r 中文: \r
• 实时预览: 左侧编辑，右侧实时预览\r
• 同步滚动: 滚动一侧，另一侧自动跟随\r
• 工具栏: 所有Markdown标签图标（H1、H2、粗体、斜体、列表等）\r
• 文件操作: 打开任何markdown文件，编辑后保存回原文件\r
• 本地服务器: 基于Flask的后端，提供RESTful API\r
• 响应式设计: 支持桌面和移动设备\r
• 深色主题: 现代深色UI配白色文字\r
• URL参数支持: 通过URL参数 ?file=路径 打开文件\r
• 自动服务器关闭: 页面关闭时服务器自动关闭\r
• 主题切换: 在深色和浅色主题间切换\r
• 相对路径支持: 支持相对于工作空间的相对路径\r \r ---\r \r

Installation & Setup / 安装与设置\r

\r

Requirements / 依赖要求\r

\r

pip install flask flask-cors markdown\r
```\r
\r
### Quick Start / 快速开始\r
\r
**English:**  \r
```bash\r
\r
\r
# Method 1: Direct Python command with file parameter\r
python app.py "path	o\your\file.md" --port 996 --force\r
\r
# Method 2: Open current skill's documentation\r
python app.py SKILL.md --port 996 --force\r
\r
# Method 3: Open empty editor\r
python app.py --port 996 --force\r
\r
# Method 4: Open via URL parameter in browser\r
# After starting server, open in browser:\r
# http://localhost:996/?file=path/to/your/file.md\r
\r
# Method 5: Using relative path (from workspace)\r
python app.py "skills\ace-banana2\SKILL.md" --port 996 --force\r
```\r
\r
**中文:**  \r
```bash\r
\r
# 方法1: 直接Python命令带文件参数\r
python app.py "文件路径\文件名.md" --port 996 --force\r
\r
# 方法2: 打开本技能的文档\r
python app.py SKILL.md --port 996 --force\r
\r
# 方法3: 打开空编辑器\r
python app.py --port 996 --force\r
\r
# 方法4: 通过浏览器URL参数打开\r
# 启动服务器后，在浏览器中打开：\r
# http://localhost:996/?file=路径/文件.md\r
\r
# 方法5: 使用相对路径（相对于工作空间）\r
python app.py "skills\ace-banana2\SKILL.md" --port 996 --force\r
```\r
\r
---\r
\r
## Usage / 使用方法\r
\r
### Opening Files / 打开文件\r
\r
**English:**  \r
1. **Start editor with a file**:\r
   ```bash\r
   python app.py "C:\path	o\file.md"\r
   ```\r
\r
2. **Browser automatically opens** with URL parameter:\r
   - `http://localhost:996/?file=C:\path	o\file.md`\r
   - URL parameter automatically loads the file\r
\r
3. **Alternative method**: Direct URL access\r
   ```\r
   http://localhost:996/?file=path/to/file.md\r
   ```\r
   - Relative paths are supported (from workspace)\r
\r
4. **Edit file** with toolbar and see live preview\r
\r
5. **Click "Save"** button to save changes back to original file\r
\r
**中文:**  \r
1. **使用文件启动编辑器**：\r
   ```bash\r
   python app.py "C:\路径\文件.md"\r
   ```\r
\r
2. **浏览器自动打开**并带URL参数：\r
   - `http://localhost:996/?file=C:\路径\文件.md`\r
   - URL参数自动加载文件\r
\r
3. **替代方法**：直接URL访问\r
   ```\r
   http://localhost:996/?file=路径/文件.md\r
   ```\r
   - 支持相对路径（相对于工作空间）\r
\r
4. **使用工具栏编辑文件**并查看实时预览\r
\r
5. **点击"保存"按钮**将更改保存回原文件\r
\r
### Toolbar Features / 工具栏功能\r
\r
**Icons available:**\r
- **H1-H6**: Headers 标题 (with number badges in light theme)\r
- **B**: Bold 粗体\r
- **I**: Italic 斜体\r
- **S**: Strikethrough 删除线\r
- **Q**: Blockquote 引用\r
- **Code**: Inline code 行内代码\r
- **\x3C/>**: Code block 代码块\r
- **List**: Unordered list 无序列表\r
- **1.**: Ordered list 有序列表\r
- **Link**: Hyperlink 链接\r
- **Image**: Insert image 插入图片\r
- **Table**: Insert table 插入表格\r
- **HR**: Horizontal rule 水平线\r
- **🌙/☀️**: Theme toggle 主题切换\r
- **💾**: Save 保存\r
- **📁**: Open file 打开文件\r
- **🔌**: Shutdown server 关闭服务器\r
- **Undo/Redo**: Undo and redo 撤销/重做\r
\r
---\r
\r
## File Structure / 文件结构\r
\r
```\r
xi-markdown/\r
├── SKILL.md                  # This documentation\r
├── scripts/\r
│   ├── app.py                # Flask server with API (enhanced)\r
│   ├── index.html            # Frontend HTML with JavaScript (redesigned)\r
│   ├── test.md              # Test markdown file\r
│   └── styles.css            # CSS styles (optional)\r
└── references/\r
    └── api_docs.md          # API documentation\r
```\r
\r
---\r
\r
## API Endpoints / API接口\r
\r
### GET `/`\r
- Returns the main HTML page\r
- Supports URL parameter: `?file=path` (opens file via AJAX)\r
\r
### GET `/api/health`\r
- Health check endpoint\r
- Returns: `{"status": "ok", "timestamp": "..."}`\r
\r
### GET `/api/file`\r
- Returns current file content\r
- Query parameter: `path` (file path, supports relative paths)\r
\r
### POST `/api/file`\r
- Saves content to file\r
- JSON body: `{"path": "file_path", "content": "file_content"}`\r
- Supports relative paths (resolved to workspace)\r
\r
### GET `/api/preview`\r
- Converts markdown to HTML for preview\r
- Query parameter: `markdown` (markdown text)\r
\r
### GET `/api/open`\r
- Opens a file in the editor\r
- Query parameter: `path` (file path, supports relative paths)\r
\r
### GET `/api/shutdown`\r
- Shuts down the server\r
- Called automatically when page closes\r
\r
---\r
\r
## Keyboard Shortcuts / 键盘快捷键\r
\r
- **Ctrl+S**: Save file 保存文件\r
- **Ctrl+O**: Open file dialog 打开文件对话框\r
- **Ctrl+Z**: Undo 撤销\r
- **Ctrl+Y**: Redo 重做\r
- **Ctrl+B**: Bold 粗体\r
- **Ctrl+I**: Italic 斜体\r
- **Ctrl+K**: Insert link 插入链接\r
\r
---\r
\r
## New Features / 新功能\r
\r
### URL Parameter Support / URL参数支持\r
**English:**  \r
Open files directly via URL parameter:\r
```\r
http://localhost:996/?file=skills/xi-markdown/SKILL.md\r
```\r
- URL is automatically encoded\r
- Supports relative paths from workspace\r
- AJAX loads file content dynamically\r
\r
**中文:**  \r
通过URL参数直接打开文件：\r
```\r
http://localhost:996/?file=skills/xi-markdown/SKILL.md\r
```\r
- URL自动编码\r
- 支持相对于工作空间的相对路径\r
- AJAX动态加载文件内容\r
\r
### Auto Server Shutdown / 自动服务器关闭\r
**English:**  \r
- Server automatically shuts down when page is closed\r
- Uses `navigator.sendBeacon()` for reliable delivery\r
- Also supports manual shutdown via 🔌 icon\r
\r
**中文:**  \r
- 页面关闭时服务器自动关闭\r
- 使用 `navigator.sendBeacon()` 确保请求送达\r
- 也支持通过🔌图标手动关闭\r
\r
### Theme Support / 主题支持\r
**English:**  \r
- Switch between dark and light themes\r
- H1-H6 icons show number badges in light theme\r
- Responsive CSS for both themes\r
\r
**中文:**  \r
- 在深色和浅色主题间切换\r
- 浅色主题下H1-H6图标显示数字标记\r
- 两个主题都有响应式CSS\r
\r
## Examples / 示例\r
\r
### Edit a skill's documentation:\r
```bash\r
python app.py "skills\a-stock-get\SKILL.md"\r
# or via URL: http://localhost:996/?file=skills/a-stock-get/SKILL.md\r
```\r
\r
### Edit Ace Banana2 skill:\r
```bash\r
python app.py "skills\ace-banana2\SKILL.md" --port 996 --force\r
```\r
\r
### Edit your own notes:\r
```bash\r
python app.py "C:\Users\YourName\
otes.md"\r
```\r
\r
### Start empty and create new file:\r
```bash\r
python app.py\r
# Then use "Save As" in the editor\r
```\r
\r
### Open via URL parameter only:\r
```bash\r
# Start server without file\r
python app.py --port 996 --force\r
# Then open in browser:\r
# http://localhost:996/?file=skills/xi-markdown/SKILL.md\r
```\r
\r
---\r
\r
## Notes / 注意事项\r
\r
**English:**  \r
- The server runs on `localhost:996` by default\r
- Only one file can be edited at a time\r
- Changes are auto-saved locally (in browser) every 30 seconds\r
- Click "Save" to write to original file\r
- Server automatically closes when page is closed\r
- Use `Ctrl+C` to manually stop the server if needed\r
- URL parameters require URL encoding for special characters\r
\r
**中文:**  \r
- 服务器默认运行在 `localhost:996`\r
- 一次只能编辑一个文件\r
- 每30秒自动保存到本地（浏览器存储）\r
- 点击"保存"将写入原文件\r
- 页面关闭时服务器自动关闭\r
- 需要时使用 `Ctrl+C` 手动停止服务器\r
- URL参数中的特殊字符需要URL编码\r
\r
---\r
\r
## Development / 开发\r
\r
### Adding new features:\r
1. Edit `app.py` for backend changes\r
2. Edit `index.html` for frontend changes\r
3. Add new CSS in `\x3Cstyle>` tags or separate file\r
4. Test with different markdown files\r
\r
### Debug mode:\r
```bash\r
python app.py --debug\r
```\r
\r
---\r
\r
## Todo / 待办事项\r
\r
- [x] Basic editor with live preview\r
- [x] Sync scrolling between editor and preview\r
- [x] Complete markdown toolbar\r
- [x] File open/save functionality\r
- [x] URL parameter support for file loading\r
- [x] Auto server shutdown on page close\r
- [x] Theme toggle (dark/light)\r
- [x] Relative path support\r
- [ ] Auto-save with configurable interval\r
- [ ] Multiple file tabs\r
- [ ] Search and replace\r
- [ ] Export to PDF/HTML\r
- [ ] Custom themes\r
- [ ] Plugin system\r
- [ ] Image upload and management\r
- [ ] Keyboard shortcut customization\r
\r
---\r
\r
## References / 参考资料\r
\r
- [Markdown Guide](https://www.markdownguide.org/)\r
- [Flask Documentation](https://flask.palletsprojects.com/)\r
- [Showdown.js](https://github.com/showdownjs/showdown) - Markdown parser\r
- [CodeMirror](https://codemirror.net/) - Text editor component\r
\r
---\r
\r
**Version**: 1.2.0  \r
**Last Updated**: 2026-03-14  \r
**Author**: XI Markdown Editor Team\r
**Email**: [email protected]\r
**Wechat**: jakeycis\r
\r
### Changelog / 更新日志\r
\r
#### v1.2.0 (2026-03-14)\r
- ✅ Added URL parameter support (`?file=path`)\r
- ✅ Added auto server shutdown on page close\r
- ✅ Added theme toggle (dark/light)\r
- ✅ Added relative path support\r
- ✅ Fixed H1-H6 icon badges in light theme\r
- ✅ Enhanced API endpoints\r
- ✅ Improved user experience\r
\r
#### v1.1.0 (2026-03-14)\r
- ✅ Redesigned UI with modern toolbar\r
- ✅ Added sync scrolling\r
- ✅ Added comprehensive markdown toolbar\r
- ✅ Added file operations (open/save)\r
\r
#### v1.0.0 (2026-03-14)\r
- ✅ Initial release\r
- ✅ Basic markdown editor with live preview\r
- ✅ Flask-based local server