SkillHub

local-markdown-editor

v1.0.1

Local Markdown Editor with Live Preview - A web-based markdown editor that opens a Flask server and provides real-time editing with live preview, sync scrolling, and toolbars for all markdown tags.

Sourced from ClawHub, Authored by xiyunnet

Installation

Please help me install the skill `local-markdown-editor` from SkillHub official store. npx skills add xiyunnet/local-markdown-editor

XI Markdown Editor 本地Markdown编辑器

English | 中文

⚠️ Security Notice / 安全声明

English:
This skill runs a local-only Flask server for markdown editing. It does NOT: - Connect to external servers (except CDN for libraries) - Send data outside your local machine - Require internet access for core functionality - Execute arbitrary code

Security Features: - Localhost-only server (127.0.0.1) - No external network connections - File operations limited to user-specified paths - All code is open and inspectable

中文:
此技能运行仅限本地的Flask服务器进行Markdown编辑。它不会： - 连接到外部服务器（CDN库除外） - 将数据发送到本地机器之外 - 需要互联网访问核心功能 - 执行任意代码

安全特性: - 仅限本地主机服务器 (127.0.0.1) - 无外部网络连接 - 文件操作仅限于用户指定的路径 - 所有代码都是开放且可检查的

Overview / 概述

English:
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.

中文:
基于Web的Markdown编辑器，本地运行Flask服务器，提供实时编辑和预览功能。包括编辑器与预览同步滚动、完整的Markdown工具栏、直接文件保存。无需安装，就可以在本地直接编辑markdown。

Features / 功能特性

English:
- Real-time Preview: Edit on left, see live preview on right - Sync Scrolling: Scroll one side, the other follows automatically - Toolbar: Icons for all markdown tags (H1, H2, bold, italic, lists, etc.) - File Operations: Open any markdown file, edit, save back to original file - Local Server: Flask-based backend with RESTful API - Responsive Design: Works on desktop and mobile - Dark Theme: Modern dark UI with white text - URL Parameter Support: Open files via URL parameter ?file=path - Auto Server Shutdown: Server automatically closes when page is closed - Theme Toggle: Switch between dark and light themes - Relative Path Support: Support for relative paths from workspace

中文:
- 实时预览: 左侧编辑，右侧实时预览 - 同步滚动: 滚动一侧，另一侧自动跟随 - 工具栏: 所有Markdown标签图标（H1、H2、粗体、斜体、列表等） - 文件操作: 打开任何markdown文件，编辑后保存回原文件 - 本地服务器: 基于Flask的后端，提供RESTful API - 响应式设计: 支持桌面和移动设备 - 深色主题: 现代深色UI配白色文字 - URL参数支持: 通过URL参数 ?file=路径 打开文件 - 自动服务器关闭: 页面关闭时服务器自动关闭 - 主题切换: 在深色和浅色主题间切换 - 相对路径支持: 支持相对于工作空间的相对路径

Installation & Setup / 安装与设置

Requirements / 依赖要求

pip install flask flask-cors markdown

Quick Start / 快速开始

English: 

# Method 1: Direct Python command with file parameter
python app.py "pathtoyourfile.md" --port 996 --force

# Method 2: Open current skill's documentation
python app.py SKILL.md --port 996 --force

# Method 3: Open empty editor
python app.py --port 996 --force

# Method 4: Open via URL parameter in browser
# After starting server, open in browser:
# http://localhost:996/?file=path/to/your/file.md

# Method 5: Using relative path (from workspace)
python app.py "skillsace-banana2SKILL.md" --port 996 --force

中文: 

# 方法1: 直接Python命令带文件参数
python app.py "文件路径文件名.md" --port 996 --force

# 方法2: 打开本技能的文档
python app.py SKILL.md --port 996 --force

# 方法3: 打开空编辑器
python app.py --port 996 --force

# 方法4: 通过浏览器URL参数打开
# 启动服务器后，在浏览器中打开：
# http://localhost:996/?file=路径/文件.md

# 方法5: 使用相对路径（相对于工作空间）
python app.py "skillsace-banana2SKILL.md" --port 996 --force

Usage / 使用方法

Opening Files / 打开文件

English:
1. Start editor with a file: bash python app.py "C:pathtofile.md"

  1. Browser automatically opens with URL parameter:
  2. http://localhost:996/?file=C:pathtofile.md

  3. URL parameter automatically loads the file

  4. Alternative method: Direct URL access http://localhost:996/?file=path/to/file.md

  5. Relative paths are supported (from workspace)

  6. Edit file with toolbar and see live preview

  7. Click "Save" button to save changes back to original file

中文:
1. 使用文件启动编辑器： bash python app.py "C:路径文件.md"

  1. 浏览器自动打开并带URL参数：
  2. http://localhost:996/?file=C:路径文件.md

  3. URL参数自动加载文件

  4. 替代方法：直接URL访问 http://localhost:996/?file=路径/文件.md

  5. 支持相对路径（相对于工作空间）

  6. 使用工具栏编辑文件并查看实时预览

  7. 点击"保存"按钮将更改保存回原文件

Toolbar Features / 工具栏功能

Icons available: - H1-H6: Headers 标题 (with number badges in light theme) - B: Bold 粗体 - I: Italic 斜体 - S: Strikethrough 删除线 - Q: Blockquote 引用 - Code: Inline code 行内代码 - </>: Code block 代码块 - List: Unordered list 无序列表 - 1.: Ordered list 有序列表 - Link: Hyperlink 链接 - Image: Insert image 插入图片 - Table: Insert table 插入表格 - HR: Horizontal rule 水平线 - 🌙/☀️: Theme toggle 主题切换 - 💾: Save 保存 - 📁: Open file 打开文件 - 🔌: Shutdown server 关闭服务器 - Undo/Redo: Undo and redo 撤销/重做

File Structure / 文件结构

xi-markdown/
├── SKILL.md                  # This documentation
├── scripts/
│   ├── app.py                # Flask server with API (enhanced)
│   ├── index.html            # Frontend HTML with JavaScript (redesigned)
│   ├── test.md              # Test markdown file
│   └── styles.css            # CSS styles (optional)
└── references/
    └── api_docs.md          # API documentation

API Endpoints / API接口

GET /

  • Returns the main HTML page
  • Supports URL parameter: ?file=path (opens file via AJAX)

GET /api/health

  • Health check endpoint
  • Returns: {"status": "ok", "timestamp": "..."}

GET /api/file

  • Returns current file content
  • Query parameter: path (file path, supports relative paths)

POST /api/file

  • Saves content to file
  • JSON body: {"path": "file_path", "content": "file_content"}
  • Supports relative paths (resolved to workspace)

GET /api/preview

  • Converts markdown to HTML for preview
  • Query parameter: markdown (markdown text)

GET /api/open

  • Opens a file in the editor
  • Query parameter: path (file path, supports relative paths)

GET /api/shutdown

  • Shuts down the server
  • Called automatically when page closes

Keyboard Shortcuts / 键盘快捷键

  • Ctrl+S: Save file 保存文件
  • Ctrl+O: Open file dialog 打开文件对话框
  • Ctrl+Z: Undo 撤销
  • Ctrl+Y: Redo 重做
  • Ctrl+B: Bold 粗体
  • Ctrl+I: Italic 斜体
  • Ctrl+K: Insert link 插入链接

New Features / 新功能

URL Parameter Support / URL参数支持

English:
Open files directly via URL parameter:

http://localhost:996/?file=skills/xi-markdown/SKILL.md
  • URL is automatically encoded
  • Supports relative paths from workspace
  • AJAX loads file content dynamically

中文:
通过URL参数直接打开文件：

http://localhost:996/?file=skills/xi-markdown/SKILL.md
  • URL自动编码
  • 支持相对于工作空间的相对路径
  • AJAX动态加载文件内容

Auto Server Shutdown / 自动服务器关闭

English:
- Server automatically shuts down when page is closed - Uses navigator.sendBeacon() for reliable delivery - Also supports manual shutdown via 🔌 icon

中文:
- 页面关闭时服务器自动关闭 - 使用 navigator.sendBeacon() 确保请求送达 - 也支持通过🔌图标手动关闭

Theme Support / 主题支持

English:
- Switch between dark and light themes - H1-H6 icons show number badges in light theme - Responsive CSS for both themes

中文:
- 在深色和浅色主题间切换 - 浅色主题下H1-H6图标显示数字标记 - 两个主题都有响应式CSS

Examples / 示例

Edit a skill's documentation:

python app.py "skillsa-stock-getSKILL.md"
# or via URL: http://localhost:996/?file=skills/a-stock-get/SKILL.md

Edit Ace Banana2 skill:

python app.py "skillsace-banana2SKILL.md" --port 996 --force

Edit your own notes:

python app.py "C:UsersYourNamenotes.md"

Start empty and create new file:

python app.py
# Then use "Save As" in the editor

Open via URL parameter only:

# Start server without file
python app.py --port 996 --force
# Then open in browser:
# http://localhost:996/?file=skills/xi-markdown/SKILL.md

Notes / 注意事项

English:
- The server runs on localhost:996 by default - Only one file can be edited at a time - Changes are auto-saved locally (in browser) every 30 seconds - Click "Save" to write to original file - Server automatically closes when page is closed - Use Ctrl+C to manually stop the server if needed - URL parameters require URL encoding for special characters

中文:
- 服务器默认运行在 localhost:996 - 一次只能编辑一个文件 - 每30秒自动保存到本地（浏览器存储） - 点击"保存"将写入原文件 - 页面关闭时服务器自动关闭 - 需要时使用 Ctrl+C 手动停止服务器 - URL参数中的特殊字符需要URL编码

Development / 开发

Adding new features:

  1. Edit app.py for backend changes
  2. Edit index.html for frontend changes
  3. Add new CSS in <style> tags or separate file
  4. Test with different markdown files

Debug mode:

python app.py --debug

Todo / 待办事项

  • [x] Basic editor with live preview
  • [x] Sync scrolling between editor and preview
  • [x] Complete markdown toolbar
  • [x] File open/save functionality
  • [x] URL parameter support for file loading
  • [x] Auto server shutdown on page close
  • [x] Theme toggle (dark/light)
  • [x] Relative path support
  • [ ] Auto-save with configurable interval
  • [ ] Multiple file tabs
  • [ ] Search and replace
  • [ ] Export to PDF/HTML
  • [ ] Custom themes
  • [ ] Plugin system
  • [ ] Image upload and management
  • [ ] Keyboard shortcut customization

References / 参考资料

  • Markdown Guide
  • Flask Documentation
  • Showdown.js - Markdown parser
  • CodeMirror - Text editor component

Version: 1.2.0
Last Updated: 2026-03-14
Author: XI Markdown Editor Team Email: [email protected] Wechat: jakeycis

Changelog / 更新日志

v1.2.0 (2026-03-14)

  • ✅ Added URL parameter support (?file=path)
  • ✅ Added auto server shutdown on page close
  • ✅ Added theme toggle (dark/light)
  • ✅ Added relative path support
  • ✅ Fixed H1-H6 icon badges in light theme
  • ✅ Enhanced API endpoints
  • ✅ Improved user experience

v1.1.0 (2026-03-14)

  • ✅ Redesigned UI with modern toolbar
  • ✅ Added sync scrolling
  • ✅ Added comprehensive markdown toolbar
  • ✅ Added file operations (open/save)

v1.0.0 (2026-03-14)

  • ✅ Initial release
  • ✅ Basic markdown editor with live preview
  • ✅ Flask-based local server