Markdown Smart Manager

A comprehensive VS Code extension for managing and editing Markdown documents with advanced features including custom snippets, MkDocs integration, and task management.

🚀 Features

📋 Commands View

• 11 Built-in Commands: Insert headings, formatting, lists, tables, and more
• Visual Interface: Click buttons instead of memorizing shortcuts
• Context-Aware: Commands adapt to your current selection
• Real-time Feedback: Status messages for all actions

🧩 Snippets View

• Built-in Snippets: Pre-configured snippets for common Markdown patterns
• Custom Snippets: Create, edit, and manage your own snippets
• Visual Catalog: Browse snippets by category with previews
• One-Click Insertion: Click to insert snippets at cursor position
• Task Lists: Specialized snippets for task management with assignees and dates

🛠️ Toolbar View

• Quick Formatting: Bold, italic, headings, lists, and more
• Smart Actions: Format selected text or insert templates
• Organized Categories: Headings, Text Formatting, Lists & Structure, Links & Media
• Task List Button: Quick insertion of task list items

📊 Tasks View (v2.0)

• Workspace Scanning: Automatically detects task lists in all Markdown files
• Smart Parsing: Extracts tasks with assignees (@mentions) and due dates
• Real-time Updates: Monitors file changes and updates task list automatically
• Multiple Grouping: Group tasks by folder, status, or assignee
• Advanced Filtering: Filter by status, assignee, due date, and search text
• Task Navigation: Click any task to navigate to its exact location in the file
• Visual Indicators: Overdue tasks (🔴), upcoming tasks (🟡), completed tasks (☑)
• Statistics Dashboard: View total tasks, completed vs pending, and assignee breakdown

⚙️ Custom Snippets

• Create Your Own: Add custom snippets with title, description, and content
• Category Organization: Organize snippets into categories
• Edit & Delete: Full CRUD operations for custom snippets
• Persistent Storage: Snippets saved across VS Code sessions

📚 MkDocs Integration

• Build Site: Generate static site from your Markdown files
• Live Preview: Serve MkDocs site for real-time preview
• Open Preview: Direct browser integration for current file
• Configuration Detection: Automatic mkdocs.yml detection

Task Management Features

Supported Task Formats

The extension recognizes task lists in the following formats:

- [ ] Basic task
- [x] Completed task
- [ ] Task with assignee @john.doe
- [ ] Task with date 15/08/2024
- [ ] Task with assignee and date @maria.santos 20/08/2024 14:30

Task Detection Rules

• Task Lists: Standard Markdown format - [ ] or - [x]
• Assignees: @ mentions following pattern @username (letters, numbers, dots, hyphens, underscores)
• Dates: Brazilian format dd/mm/yyyy or dd/mm/yy with optional time HH:mm
• File Types: Only .md files in the workspace are scanned
• Exclusions: Automatically excludes node_modules, .git, and other system folders

Task View Interface

• Search Bar: Find tasks by description or assignee
• Group By: Organize tasks by folder structure, completion status, or assignee
• Filters: Filter by status (all/pending/completed), assignee (including unassigned tasks), and due date
• Statistics: Real-time counters showing total, completed, pending, overdue, and upcoming tasks
• Navigation: Click any task to jump to its exact line in the source file

Requirements

• Node.js: Version 18 or higher
• pnpm: Package manager (recommended) or npm
• VS Code: Version 1.99.0 or higher
• MkDocs: For MkDocs integration features (optional)

Installation

1. Clone the repository:

   git clone https://github.com/antoniocarelli/markdown-smart-manager.git
   cd markdown-smart-manager
   

2. Install dependencies:

   pnpm install
   

3. Build the extension:

   pnpm run compile
   

Development

Architecture

HTML Templates for Webviews

This extension follows best practices for VS Code extensions by separating HTML content from TypeScript code:

• HTML Extraction: All webview HTML is stored in separate .html files in src/views/html/
• Template System: Uses a simple placeholder system with {{placeholder}} syntax
• HtmlLoader Utility: A utility class loads HTML files and replaces placeholders
• Modular CSS: Styles are separated into component-specific files
• Base Template: Common HTML structure is defined in a base template

This approach offers several benefits:

• Improved code organization and maintainability
• Easier styling and HTML editing without TypeScript changes
• Better separation of concerns
• Simplified debugging of HTML/CSS issues

For more details, see HTML Templates Documentation.

Testing the Extension

The project includes a comprehensive test script that validates the extension before deployment:

Using the Test Script

# Run the complete test suite
./scripts/test-extension.sh

# Or use the npm script
pnpm run test-extension

Using VS Code Tasks

1. Open the project in VS Code
2. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
3. Type "Tasks: Run Task"
4. Select "test-extension"

The test script performs the following checks:

• ✅ Prerequisites: Verifies Node.js and pnpm are installed
• ✅ Dependencies: Installs missing dependencies if needed
• ✅ Linting: Runs ESLint to check code quality
• ✅ Compilation: Builds the extension using esbuild
• ✅ Tests: Runs the VS Code extension test suite
• ✅ Build Verification: Confirms the extension was built successfully

Manual Testing

1. Press F5 in VS Code to launch the Extension Development Host
2. Open a markdown file (.md) in the new window
3. Look for the "Markdown Smart Manager" icon in the Activity Bar
4. Test the four views: Commands, Snippets, Toolbar, and Tasks
5. Use Ctrl+Shift+P to access extension commands

Extension Settings

This extension contributes the following settings:

MkDocs Configuration

• markdownSmartManager.mkdocs.autoBuildOnSave: Automatically build MkDocs site when Markdown files are saved

• markdownSmartManager.mkdocs.defaultPort: Default port for MkDocs development server (default: 8000)

• markdownSmartManager.mkdocs.autoOpenPreview: Automatically open preview in browser when server starts

• markdownSmartManager.mkdocs.buildOutputPath: Custom path for MkDocs build output directory

• markdownSmartManager.mkdocs.theme: Default theme for new MkDocs projects

UI Configuration

• markdownSmartManager.ui.defaultView: Default view to show when opening the Markdown Smart Manager panel

• markdownSmartManager.ui.showNotifications: Show notifications for build success, errors, and server status

Task Management Configuration

• markdownSmartManager.tasks.enabled: Enable/disable the Tasks view for managing Markdown task lists

• markdownSmartManager.tasks.autoScan: Automatically scan workspace for tasks on startup

• markdownSmartManager.tasks.scanInterval: Interval in milliseconds for automatic task scanning (default: 30000)

• markdownSmartManager.tasks.maxFiles: Maximum number of Markdown files to scan for tasks (default: 1000)

• markdownSmartManager.tasks.excludePatterns: Glob patterns for files to exclude from task scanning

• markdownSmartManager.tasks.dateFormats: Date formats to recognize in task descriptions (default: ["dd/mm/yyyy", "dd/mm/yy"])

• markdownSmartManager.tasks.assigneePattern: Regex pattern for detecting assignees in task descriptions

• markdownSmartManager.tasks.groupBy: Default grouping for tasks in the Tasks view (folder/status/assignee)

• markdownSmartManager.tasks.showCompleted: Show completed tasks in the Tasks view

• markdownSmartManager.tasks.highlightOverdue: Highlight overdue tasks in the Tasks view

For detailed configuration options and examples, see CONFIGURATION.md.

Known Issues

Calling out known issues can help limit users opening duplicate issues against your extension.

Release Notes

Users appreciate release notes as you update your extension.

1.0.0

Initial release of ...

1.0.1

Fixed issue #.

1.1.0

Added features X, Y, and Z.

Following extension guidelines

Ensure that you've read through the extensions guidelines and follow the best practices for creating your extension.

• Extension Guidelines

Working with Markdown

You can author your README using Visual Studio Code. Here are some useful editor keyboard shortcuts:

• Split the editor (Cmd+\ on macOS or Ctrl+\ on Windows and Linux).
• Toggle preview (Shift+Cmd+V on macOS or Shift+Ctrl+V on Windows and Linux).
• Press Ctrl+Space (Windows, Linux, macOS) to see a list of Markdown snippets.

For more information

• Visual Studio Code's Markdown Support
• Markdown Syntax Reference

Enjoy!