TopMind Notes Workspace Assistant
🚀 Smart VSCode Markdown Notes Management Extension
中文版
A simplified notes management tool designed for knowledge workers, based on GTD principles, providing unified collection, intelligent organization, and periodic archiving workflow.
✨ Why Choose TopMind?
- 🎯 Simplified Workflow: Based on GTD principles, unified inbox design reduces decision fatigue
- 📱 Out-of-the-Box: One-click initialization, start using without complex configuration
- 🤖 Smart Organization: AI-assisted content analysis and periodic summaries, discover knowledge connections
- ⚡ Lightweight & Efficient: Focus on core features, perfectly integrated with VS Code
🚀 Core Features
📋 Workspace Management
- Auto Recognition: Detects
.topmind/notes.config.json
configuration file on startup
- One-click Initialization:
Topmind: 工作区初始化 (Workspace Init)
command creates complete configuration
- Directory Structure Generation:
Topmind: 工作区目录生成 (Workspace Directory Structure Generating)
automatically creates directories and templates
Simplified Directory Structure:
workspace/
├── .topmind/
│ ├── notes.config.json # Main configuration file
│ ├── templates_notes/ # Note templates directory
│ └── templates_reports/ # Report templates directory
├── 00_Inbox/ # 📥 Unified Collection Box (all daily notes)
├── 01_Reference/ # 📚 Reference Materials (long-term storage)
├── 02_Reports/ # 📊 Periodic Summary Reports
└── 03_Archive/ # 🗄️ Completed Archive
- Smart Insertion:
Topmind: 元数据插入 (Metadata Insert)
intelligently infers status and category based on file location
- Quick Status Management:
Topmind: 笔记 - 设置状态 (Note - Set Status)
quickly changes note status
- Auto Folding: YAML Front Matter regions can be automatically folded (configurable)
Generated Metadata Example:
---
title: "My Note Title"
date: 2025-01-26
status: inbox
category: General
tags: []
summary: ''
---
✨ Note Creation
- Multiple Access Methods: Command palette, right-click folder, editor context menu
- Smart Template Selection: Supports blank notes, custom templates, built-in templates
- Smart Placeholders: Supports
{{TITLE}}
, {{DATE}}
, {{AUTHOR}}
and many other placeholders
- Auto Save: Automatically saves after creation, ensuring metadata is properly written
🎨 Visual Decoration System
- Smart Badges: Display processing status based on content richness
◬
Metadata corrupted | ●
Complete note | ☉
In progress | ○
Raw file
- Preset Theme Colors: Green indicates status match, orange suggests needs organization
- Hover Tips: Mouse hover shows metadata details
📊 Enhanced Smart Status Bar
- Rich Metadata Display: Shows current note status, category, tags count, and file name
- Detailed Tooltips: Hover to see comprehensive note information including summary, date, and all metadata
- Quick Metadata Access: One-click metadata editing for Markdown files
- Workflow Insights: Displays note counts by status to help manage workflow
- Smart Context Switching: Automatically adjusts actions based on current file type
🛠️ Quick Start
1. Install Extension
2. Initialize Notes Workspace
- Open or create a folder as your notes workspace.
- Press
Ctrl+Shift+P
(or Cmd+Shift+P
on macOS) to open the command palette.
- Type and execute:
Topmind: 工作区初始化 (Workspace Init)
.
- The plugin will automatically create the
.topmind/notes.config.json
configuration file. You can choose whether to generate the directory structure immediately or manually execute the Topmind: 工作区目录生成 (Workspace Directory Structure Generating)
command later. It is recommended to reload the window after initialization to ensure all features are activated correctly.
3. Use Core Features
- Insert Metadata: Right-click on a Markdown file →
Topmind: 元数据插入 (Metadata Insert)
- Set Note Status: Right-click on a Markdown file →
Topmind: 笔记 - 设置状态 (Note - Set Status)
or click the Status
button in status bar
- Generate Directory Structure: Command Palette →
Topmind: 工作区目录生成 (Workspace Directory Structure Generating)
- Create New Note:
- Command Palette:
Topmind: 笔记 - 新建 (Note - New)
- Right-click on a folder in Explorer:
Topmind: 笔记 - 新建 (Note - New)
- Click the
New Note
button in status bar
- Enhanced Status Bar Features:
- View current note status, category, tags, and workspace statistics
- Rich tooltips with comprehensive metadata information
- Quick metadata editing (in Markdown files) - click "Metadata" button
- Quick note creation (in non-Markdown files) - click "New Note" button
- Hover over status bar to see detailed note information including summary
⚙️ Configuration
Configuration file is located at .topmind/notes.config.json
, including the following main configurations:
Basic Configuration Structure
{
"workspaceType": "notes", // Must be "notes"
"version": "0.7.2", // Configuration version
"decorations": {
"enable": true, // UI enhancement master switch
"hover": {
"enabled": true, // Hover tips switch
"fields": ["title", "date", "status", "category", "tags", "summary"]
}
},
"directoryProfiles": [ // Directory configuration
{
"path": "00_Inbox/",
"expectedStatus": "inbox"
},
{
"path": "01_Reference/",
"expectedStatus": "reference"
},
{
"path": "02_Reports/",
"expectedStatus": "report"
},
{
"path": "03_Archive/",
"expectedStatus": "archived"
}
],
"statusSettings": { // Status configuration
"inbox": {
"displayName": "📥 Inbox",
"icon": "inbox"
},
"reference": {
"displayName": "📚 Reference",
"icon": "book"
},
"report": {
"displayName": "📊 Report",
"icon": "graph"
},
"archived": {
"displayName": "🗄️ Archived",
"icon": "archive"
}
}
}
Custom Directory Structure (directoryProfiles
)
{
// ...
"directoryProfiles": [
{
"path": "00_Inbox/", // Directory path (relative to workspace root)
"expectedStatus": "inbox" // Expected status for notes in this directory
},
{
"path": "01_Reference/",
"expectedStatus": "reference"
},
{
"path": "02_Reports/",
"expectedStatus": "report"
},
{
"path": "03_Archive/",
"expectedStatus": "archived"
}
],
// ...
}
Custom Status Settings (statusSettings
)
{
// ...
"statusSettings": {
"inbox": { // Status key, must correspond to expectedStatus in directoryProfiles
"displayName": "📥 Inbox", // Name displayed in UI
"icon": "inbox", // VSCode Codicon Icon ID (optional)
"label": "[Inbox]" // Optional label
},
"reference": {
"displayName": "📚 Reference",
"icon": "book",
"label": "[Reference]"
},
"report": {
"displayName": "📊 Report",
"icon": "graph",
"label": "[Report]"
},
"archived": {
"displayName": "🗄️ Archived",
"icon": "archive",
"label": "[Archived]"
}
},
// ...
}
VS Code Extension Settings
topmind.defaultAuthor
: Default author name for new notes (string)
topmind.features.folding.autoFoldOnOpen
: Whether to auto-fold metadata (boolean, default true)
📋 Simplified Notes Workflow
- Collection →
00_Inbox/
(all ideas, notes, meeting records unified collection)
- Organization → Enhance content directly in
00_Inbox/
, no need to move files
- Reports → Periodically let AI analyze and generate summaries to
02_Reports/
- Archiving → Move completed projects/topics to
03_Archive/
🎨 Visual Indicators
Badge Meanings
◬
Metadata corrupted | ●
Complete note | ☉
In progress | ○
Raw file
Color System
- Green: Status matches | Orange: Needs organization | Default: No status
❓ FAQ
Q: Extension not activated?
Ensure the workspace contains .topmind/notes.config.json
file. If status bar shows "Not Configured", click it to initialize the workspace.
Q: Not seeing UI enhancement effects?
- Check if
decorations.enable
is true
in configuration file
- Reload VSCode window (
Developer: Reload Window
)
Q: Badges display inaccurately?
Ensure Markdown files have correct YAML Front Matter with required fields: title
, date
, status
, tags
Q: How to enable auto-save?
In VSCode settings, search for files.autoSave
and set it to afterDelay
Q: How to fully clean the environment to solve plugin build/install/activation issues?
- Clean dependencies and build cache:
Remove-Item node_modules -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item package-lock.json -Force -ErrorAction SilentlyContinue
Remove-Item out -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item coverage -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item *.vsix -Force -ErrorAction SilentlyContinue
npm cache clean --force
- Clean VS Code extension cache (if activation issues or old versions remain):
Remove-Item "$env:USERPROFILE\.vscode\extensions\TopMind.topmind-notes-workspace-*" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.vscode-insiders\extensions\TopMind.topmind-notes-workspace-*" -Recurse -Force -ErrorAction SilentlyContinue
- Clear Jest test cache (if test issues occur):
npx jest --clearCache
- Reinstall dependencies and recompile:
npm install
npm run compile
Current Version: v0.7.2 (Simplified Architecture Refactoring)
Latest Improvements (December 19, 2024):
- 🎯 Architecture Simplification: Based on GTD principles, simplified from 5-level to 4-level directory structure, reducing cognitive load
- 📁 Unified Collection: All notes go to Inbox, reducing decision fatigue
- 🔄 In-Place Organization: Enhance content directly in Inbox without file movement
- 📊 Quality Assurance: 130 test cases with 100% pass rate, ensuring refactoring quality
For detailed version history and change information, please see CHANGELOG.md.
🧪 Development and Build
- Clone the project:
git clone <repository-url>
- Install dependencies:
npm install
- Compile and bundle:
npm run compile
or npm run watch
(real-time compilation with webpack)
- Run tests:
npm test
- Package for production:
npm run package
(creates optimized bundle)
- Package VSIX:
vsce package
(Requires vsce
to be installed globally first: npm install -g @vscode/vsce
)
- Press
F5
in VSCode to start the Extension Development Host for debugging.
Note: The extension now uses webpack for bundling dependencies. The main entry point is dist/extension.js
(bundled) rather than out/extension.js
(compiled only).
🤝 Contributing
Contributions are welcome! Please visit our GitHub repository to:
- Report bugs or request features in Issues
- Submit improvements via Pull Requests
- View the source code and documentation
📄 License
MIT License