Marker Jump

A VS Code extension that allows you to mark and navigate between specific lines in the editor with visual flag icons and numbered shortcuts.

📺 Demo

Mark lines with visual flags and navigate between them using keyboard shortcuts

📖 Documentation

• English: README.md (Current)
• 中文: README.zh-cn.md
• 日本語: README.ja.md

✨ Features

• 🚩 Visual Flag Markers: Beautiful flag-style markers with customizable colors and optional numbers
• 🔢 Smart Numbering: First 9 markers get numbers 1-9 for quick keyboard access
• ⌨️ Flexible Navigation: Multiple navigation orders (line order vs creation order)
• 📊 Status Bar Toolbar: Quick access toolbar that appears when markers exist
• 💾 Persistent Markers: Optional persistence between VS Code sessions
• 📁 Untitled File Support: Automatic marker migration when saving untitled files
• ⚡ Conflict Resolution: Smart handling of marker conflicts during file operations
• 🎯 F2 Double-tap: Optional secondary shortcut for toggling markers
• 🌍 Multi-language: Full support for English, Chinese, and Japanese

🚀 Usage

Basic Commands

• Cmd+M (Mac) / Ctrl+M (Windows/Linux): Toggle marker on current line
• Cmd+Alt+↑ (Mac) / Ctrl+Alt+↑ (Windows/Linux): Jump to previous marker
• Cmd+Alt+↓ (Mac) / Ctrl+Alt+↓ (Windows/Linux): Jump to next marker
• Cmd+Shift+M (Mac) / Ctrl+Shift+M (Windows/Linux): Clear all markers
• Alt+Cmd+1-9 (Mac): Jump directly to marker number 1-9

Status Bar Toolbar

When markers exist in the current file, a toolbar appears in the status bar showing:

• 🚩 2/5: Current marker position and total count
• ⬆️: Previous marker button
• ⬇️: Next marker button
• ❌: Clear all markers button

F2 Double-tap Feature

Enable markerJump.doubleKeyToggle setting to use F2 as a secondary shortcut:

• Press F2 twice quickly (within 300ms) to toggle a marker

Untitled File Support

When you save an untitled file that contains markers:

• Markers are automatically migrated to the saved file
• If the target file already has markers, you'll see a dialog to choose:
  • Replace with new markers: Replace existing markers
  • Keep existing markers: Preserve current markers

⚙️ Configuration

Navigation Order Options

• Creation Order: Markers numbered by when they were created (1st created = #1)
• Line Order: Markers numbered by line position (top to bottom)
• Number Order: Navigate by marker numbers (1 → 2 → 3...)
• Line Order: Navigate by line position (top → bottom)

🌍 Multi-language Support

This extension provides full localization in multiple languages:

The interface language automatically matches your VS Code language setting.

📦 Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Marker Jump"
4. Click Install

From VSIX

1. Download the .vsix file
2. Open VS Code
3. Go to Extensions → Install from VSIX
4. Select the downloaded file

🛠️ Development

Building from Source

git clone <repository-url>
cd marker-jump
npm install
npm run compile

Project Structure

marker-jump/
├── src/
│   ├── extension.ts          # Extension entry point
│   ├── markerManager.ts      # Core marker management
│   ├── commandHandler.ts     # Command handling
│   ├── uiOverlay.ts         # Status bar UI
│   └── l10n.ts              # Internationalization
├── l10n/                    # Localization files
│   ├── bundle.l10n.json     # English
│   ├── bundle.l10n.zh-cn.json # Chinese
│   └── bundle.l10n.ja.json  # Japanese
└── package.json             # Extension manifest

Adding New Languages

To add support for a new language:

1. Create package.nls.<language-code>.json for package.json translations
2. Create l10n/bundle.l10n.<language-code>.json for runtime translations
3. Follow the existing translation structure
4. Test with VS Code in the target language

🐛 Troubleshooting

Markers not persisting

• Check that markerJump.persistent is enabled in settings
• Markers in untitled files are not persisted until the file is saved

F2 double-tap not working

• Ensure markerJump.doubleKeyToggle is enabled
• Press F2 twice within 300ms
• Note: VS Code cannot detect raw Cmd key presses

Status bar toolbar not showing

• Toolbar only appears when the current file has markers
• Check that markerJump.showToolbar is enabled

📄 License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

AGPL v3 License Summary

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

Key Points:

• ✅ Free to use, modify, and distribute
• ✅ Source code must remain open
• ⚠️ Network use requires source code availability
• 📋 Modifications must be shared under same license

🤝 Contributing

Contributions are welcome! Please feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve translations

📝 Changelog

1.0.0

• ✨ Initial release
• 🚩 Visual flag markers with customizable colors
• 🔢 Numbered markers (1-9) with keyboard shortcuts
• ⌨️ Flexible navigation orders
• 📊 Status bar toolbar with marker count
• 💾 Optional marker persistence
• 📁 Untitled file marker migration
• ⚡ Marker conflict resolution
• 🎯 F2 double-tap feature
• 🌍 Multi-language support (English, Chinese, Japanese)