Markdown大纲查看器 (增强版) 🚀

一个强大的VS Code扩展，提供Markdown文档大纲的可视化显示，支持实时位置跟踪、智能导航和扩展协作。

✨ 核心特性

🎯 现代化Webview界面

自定义Webview - 现代化界面，无缓存问题，完全可定制样式
完全重构 - 告别传统TreeView的限制，拥抱全新体验

🐍 Python驱动解析

高性能Markdown解析引擎，基于正则表达式优化
智能代码块过滤，避免误识别代码中的 # 符号
精确的层次结构构建，支持6级标题嵌套

🎨 清晰的等级标识

H1① 一级标题    🔶 红色标识
H2② 二级标题    🔸 橙色标识  
H3③ 三级标题    🔹 黄色标识
H4④ 四级标题    🔸 绿色标识
H5⑤ 五级标题    🔹 蓝色标识
H6⑥ 六级标题    🔶 紫色标识

🔄 实时同步功能

✅ 光标位置同步 - 编辑器光标移动时自动高亮对应大纲项
✅ 滚动跟随 - 滚动文档时大纲安静跟随，双状态显示
✅ 点击跳转 - 点击大纲项立即跳转到对应行
✅ 文档变化实时更新 - 文档修改时大纲自动刷新
✅ 智能展开 - 自动展开到当前项，支持手动折叠
✅ 扩展协作 - 与其他Markdown扩展（如预览插件）协同工作

🍞 面包屑导航 (NEW!)

📍 当前路径
┌── H1① 测试文档              [1]
├── H2② 二级标题1            [27]  
└── H3③ 三级标题1.1 (当前)   [41]

✨ 纵向树状显示 - 清晰展示从根到当前标题的完整路径
🎛️ 一键开关 - 🍞 按钮随时控制显示/隐藏
👆 点击跳转 - 面包屑每一级都可以点击跳转
💾 记忆设置 - 自动保存显示偏好

🔌 扩展API支持

// 其他扩展可以调用的API
interface MarkdownOutlineAPI {
    getCurrentOutline(): Promise<OutlineData | null>;
    jumpToOutlineItem(line: number): void;
    highlightLine(line: number): void;
    onOutlineUpdated(callback: Function): Disposable;
    refresh(): void;
}

🚀 快速开始

安装使用

打开Markdown文件: 在VS Code中打开任意 .md 文件
查看大纲面板: 在资源管理器中找到 "Markdown大纲" 面板
享受功能:
- 光标移动时自动蓝色高亮当前标题
- 滚动文档时大纲安静跟随（淡色提示）
- 点击大纲项快速跳转
- 🍞 面包屑导航显示完整路径
- 实时查看文档结构

功能展示

# H1① 主标题
## H2② 章节1
### H3③ 小节1.1
#### H4④ 详细内容
## H2② 章节2
### H3③ 小节2.1
### H3③ 小节2.2

在大纲中显示为带颜色标识的层次结构，一目了然！

🛠️ 技术架构

混合架构设计

┌─────────────────┬─────────────────┬─────────────────┐
│   VS Code集成    │   Python解析     │   Webview UI    │
│                 │                 │                 │
│ ✓ 文件监听       │ ✓ Markdown解析   │ ✓ 自定义样式     │
│ ✓ 光标同步       │ ✓ 等级识别       │ ✓ 实时高亮       │
│ ✓ 跳转功能       │ ✓ 结构分析       │ ✓ 交互动画       │
│ ✓ 扩展通信       │ ✓ 数据处理       │ ✓ 响应式布局     │
└─────────────────┴─────────────────┴─────────────────┘

技术栈

前端: TypeScript + HTML/CSS + JavaScript
后端: Python 3.6+ (标准库)
集成: VS Code Extension API
通信: JSON数据交换

🔧 开发指南

环境要求

VS Code 1.74.0+
Node.js 16+
Python 3.6+
TypeScript 4.9+

本地开发

# 1. 克隆项目
git clone <project-url>
cd vscode-markdown-outline

# 2. 安装依赖
npm install

# 3. 编译TypeScript
npm run compile

# 4. 测试Python解析器
python python/markdown_parser.py test-example.md

# 5. 启动调试
# 在VS Code中按F5启动扩展开发窗口

目录结构

vscode-markdown-outline/
├── src/                    # TypeScript源码
│   ├── extension.ts       # 主扩展文件
│   ├── markdownOutlineWebview.ts  # Webview提供器
│   ├── markdownOutlineProvider.ts # 传统TreeView
│   └── extensionAPI.ts    # 扩展协作API
├── python/                # Python解析器
│   ├── markdown_parser.py # 核心解析逻辑
│   └── README.md         # Python模块文档
├── media/                 # Webview资源
│   ├── main.css          # 主样式文件
│   ├── main.js           # 交互脚本
│   ├── vscode.css        # VS Code主题适配
│   └── reset.css         # 样式重置
├── out/                   # 编译输出
└── package.json          # 扩展配置

🤝 扩展协作

与Markdown预览插件协作

// 监听预览滚动事件
vscode.commands.executeCommand('markdownOutline.api.highlightLine', lineNumber);

// 获取当前大纲数据
const outline = await vscode.commands.executeCommand('markdownOutline.api.getCurrentOutline');

API命令列表

markdownOutline.api.getCurrentOutline - 获取当前大纲
markdownOutline.api.jumpToLine - 跳转到指定行
markdownOutline.api.highlightLine - 高亮指定行
markdownOutline.api.refresh - 刷新大纲

📝 更新日志

v3.0.0 (当前版本) - 2024-10-06

🍞 面包屑导航: 纵向树状路径显示，一键开关
🔄 滚动同步: 编辑器滚动时大纲智能跟随
🎯 双状态显示: 蓝色激活 vs 淡色跟随，互不干扰
⚡ 即时响应: 移除延时，滚动跟随更流畅
🎨 视觉增强: 脉搏动画、闪烁高亮等视觉效果
🧠 智能展开: 自动展开到当前项的完整路径

v2.0.0

🎉 全新架构: Python + Webview混合驱动
✨ 等级标识: H1①、H2②清晰显示
🎨 自定义UI: 现代化界面设计
🔌 扩展API: 支持与其他扩展协作
⚡ 性能优化: 防抖更新，智能缓存
🐛 问题修复: 解决TreeView缓存问题

v1.0.0

基础大纲显示功能
当前位置高亮
实时刷新

🙋‍♂️ 常见问题

Q: 为什么看不到H1①、H2②标识？

A: 请确保：

重新加载VS Code窗口 (Ctrl+Shift+P → Developer: Reload Window)
Python解析器工作正常，检查控制台是否有错误
打开.md文件时大纲面板应该自动显示

Q: Python解析器无法运行？

A: 检查：

Python是否安装并在PATH中 (python --version)
是否有文件权限问题
查看VS Code开发者控制台的错误信息

Q: 如何与其他扩展集成？

A: 参考 src/extensionAPI.ts 中的API接口，使用命令调用方式集成。

📄 许可证

MIT License - 自由使用、修改和分发。

🌟 贡献

欢迎提交Issue和Pull Request！让我们一起让Markdown编辑体验更好！

享受更好的Markdown大纲体验！ 🎉

Markdown Outline Viewer

xiaohutech