CodeMark+

Lightweight operational annotations, contextual navigation, and workspace-first developer workflows for Visual Studio Code.

CodeMark+ helps developers create, discover, navigate, and preserve operational context directly inside the editor using lightweight annotations and Markdown-native workflows.

It combines:

developer annotations (TODO, FIXME, NOTE, HACK, custom tags)
live annotation highlighting
workspace-wide annotation navigation
contextual navigation between Markdown and source code
lightweight operational notes
reusable documentation templates
annotation-aware workflows

into a cohesive operational context system designed for real-world software development.

Why CodeMark+ Exists

Developer annotations already exist naturally in almost every codebase:

// TODO: remove legacy auth flow
// FIXME: race condition during refresh
// NOTE: keep aligned with API v2
// HACK: temporary compatibility patch

But over time these annotations often become:

scattered
invisible
difficult to navigate
disconnected from implementation context
hard to revisit later
operationally fragile

At the same time, lightweight project notes and temporary implementation context often drift away from the code itself.

CodeMark+ exists to make operational context:

visible
navigable
lightweight
filesystem-native
editor-native
easy to preserve
naturally integrated into development workflows

without turning the workspace into a heavyweight documentation or knowledge-management system.

CodeMark+ in Action

What CodeMark+ Is

CodeMark+ is a lightweight operational context extension for VS Code.

It provides:

annotation highlighting
workspace-wide annotation discovery
contextual navigation between Markdown and code
lightweight operational notes
annotation-aware workflows
customizable documentation templates
developer-focused TODO workflows

The extension is designed to complement existing development workflows — not replace:

formatters
language servers
issue trackers
documentation platforms
project management tools

Core Philosophy

CodeMark+ is intentionally:

lightweight
operational-first
filesystem-native
markdown-native
editor-native
deterministic
workspace-oriented
annotation-centric

It is intentionally not:

a PKM system
a semantic graph engine
an AI documentation platform
a knowledge database
a synchronization framework
a heavyweight project management system

Annotations should remain:

fast
local
useful
visible
naturally integrated into coding workflows

without becoming ceremonial.

Operational Context Model

CodeMark+ introduces lightweight contextual addressability between notes and source code.

This allows Markdown notes, annotations, and operational references to navigate directly into the codebase while remaining plain text.

Examples:

src/auth/auth.controller.ts
src/auth/auth.controller.ts#10
src/auth/auth.controller.ts#10:4
src/auth/auth.controller.ts#10:20
TODO(src/auth/auth.controller.ts)
TODO(src/auth/auth.controller.ts#10)
TODO(src/auth/auth.controller.ts#10:20)

These references remain:

plain Markdown
versionable
portable
filesystem-native
editor-friendly

while gaining contextual navigation directly inside VS Code.

CodeMark+ separates:

anchor navigation
explicit range navigation

This distinction keeps contextual discovery deterministic and operationally predictable.

src/auth/auth.controller.ts

Navigate directly to the file.

Contextual Anchor

src/auth/auth.controller.ts#10

Navigate near line 10 and expand contextual discovery around that location.

Precise Anchor

src/auth/auth.controller.ts#10:4

Navigate to a precise line and column anchor.

Explicit Range

src/auth/auth.controller.ts#10:20

Navigate using a deterministic line range.

Scoped Annotation Discovery

TODO(src/auth/auth.controller.ts)

Discover TODO annotations within the file.

TODO(src/auth/auth.controller.ts#10)

Discover TODO annotations near the anchor.

TODO(src/auth/auth.controller.ts#10:20)

Discover TODO annotations inside the explicit range.

The same semantics apply to:

FIXME(...)
NOTE(...)
HACK(...)
custom annotation tags

Core Features

Annotation Highlighting

CodeMark+ highlights operational annotations directly inside the editor.

Examples:

// TODO: refactor auth middleware
// FIXME: duplicate websocket subscription
// NOTE: remove after API v3 migration

Supported workflows include:

TODO tracking
FIXME visibility
operational warnings
migration reminders
temporary implementation notes
custom tags

Annotations remain visible while coding, reducing the chance of losing important implementation context.

Workspace Tag Browser

The Tag Browser provides a workspace-wide operational view of annotations grouped by tag.

Example:

TODO
 ├── auth.service.ts
 │    └── refactor auth middleware
 │
 └── cache.manager.ts
      └── optimize invalidation strategy

FIXME
 └── websocket.ts
      └── duplicate websocket subscription

This makes it easier to:

revisit technical debt
surface operational warnings
coordinate lightweight workflows
navigate temporary decisions
preserve implementation continuity

without requiring external tooling.

CodeMark+ supports editor-native contextual navigation directly from:

Markdown
plaintext documents
operational notes
task lists
annotation references
frontmatter references

Supported examples:

See:
src/auth/auth.controller.ts#10

- [ ] TODO(src/auth/auth.controller.ts#10:20)

---
references:
  - src/auth/auth.controller.ts#10
  - TODO(src/auth/auth.controller.ts)
---

References become navigable using:

Ctrl+Click
command links
editor-native navigation behavior

The system also supports:

contextual annotation discovery
graceful fallback navigation
workspace-first resolution
lightweight contextual locality expansion

without introducing semantic indexing or graph infrastructure.

Lightweight Workspace Notes

CodeMark+ supports lightweight Markdown-based operational notes.

Examples include:

migration notes
implementation reminders
temporary investigation logs
scratchpads
lightweight TODO tracking
operational coordination

The notes remain:

plain Markdown
filesystem-native
versionable
portable
editor-friendly

while gaining contextual navigation into the codebase.

Customizable Annotation Templates

CodeMark+ includes reusable Mustache-based templates for generating structured comments and documentation blocks.

Templates support:

multiple programming languages
reusable structures
configurable formatting
wrapping behaviors
team conventions

Example:

{
  "language": "typescript",
  "template": [
    "/**",
    " * {{functionName}}",
    " *",
    " * @description {{description}}",
    " * @returns {{returnType}}",
    " */"
  ]
}

Generated output:

/**
 * fetchUserProfile
 *
 * @description Retrieves the active user profile
 * @returns Promise<UserProfile>
 */

The goal is to reduce repetitive documentation work while preserving developer control over formatting and style.

Example Workflows

Track Technical Debt

// TODO: remove legacy auth adapter
// FIXME: retry loop can duplicate requests

Use highlighting and the Tag Browser to keep operational debt visible while coding.

Preserve Operational Context

## Websocket Migration

See:
backend/ws/reconnect.ts#10

TODO(backend/ws/reconnect.ts#10:20)

Navigate directly from notes into implementation context.

Lightweight Investigation Notes

## Refresh Token Investigation

FIXME(src/auth/auth.controller.ts#40)

Possible duplicate refresh flow during reconnect.

Keep temporary operational context close to the codebase.

Generate Consistent Documentation

Use reusable templates to generate structured comments across projects and languages.

Especially useful for:

service layers
repetitive APIs
large codebases
shared conventions
public SDKs

Screenshots

Replace placeholders with updated screenshots focused on operational workflows.

Annotation Highlighting

Highlighted TODO/FIXME/NOTE annotations directly inside the editor.

Workspace Tag Browser

Workspace-wide annotation navigation grouped by tag.

Markdown references navigating directly into source code using Ctrl+Click.

Workspace Notes

Operational Markdown notes integrated with contextual navigation.

Documentation Templates

Reusable annotation and documentation templates generated directly in the editor.

Configuration

CodeMark+ is intentionally configurable.

The extension supports:

custom annotation tags
highlight rules
template generation
wrapping behavior
Tag Browser behavior
operational workflows
language-specific templates

without forcing a rigid workflow model.

Highlight Rules

Highlighting behavior can be customized using annotation rules.

Example:

"codeMarkPlus.highlight.highlightRules": [
  {
    "tag": "TODO",
    "color": "#FFCC00",
    "fontWeight": "bold"
  },
  {
    "tag": "FIXME",
    "color": "#FF5555"
  },
  {
    "tag": "NOTE",
    "color": "#4FC1FF"
  }
]

This allows teams to create consistent operational visibility directly inside the editor.

Annotation Templates

Templates can be customized per language using Mustache placeholders.

Example:

"codeMarkPlus.templates.customTemplates": [
  {
    "language": "typescript",
    "template": [
      "/**",
      " * {{functionName}}",
      " *",
      " * @description {{description}}",
      " */"
    ]
  }
]

Templates support:

reusable documentation structures
language-specific formatting
configurable wrapping behavior
custom annotation styles

Storage Philosophy

Workspace notes and operational references remain intentionally lightweight and developer-owned.

The goal is to keep operational context:

visible
portable
versionable
easy to share
close to the codebase
naturally navigable

without introducing heavyweight external systems.

Performance

CodeMark+ is designed to remain lightweight during everyday development workflows.

The extension focuses on:

fast annotation discovery
responsive highlighting
lightweight contextual navigation
bounded workspace scanning
deterministic behavior
minimal workflow interruption

while avoiding unnecessary architectural complexity.

Design Philosophy

CodeMark+ prioritizes:

operational annotations
contextual continuity
filesystem-native workflows
lightweight workspace memory
editor-native navigation
deterministic operational behavior
annotation discoverability

The extension intentionally avoids becoming:

a semantic graph engine
a PKM platform
an AI orchestration system
a contextual database
a synchronization framework
a heavyweight documentation platform

The focus remains on preserving lightweight operational continuity directly inside the editor.

Best Use Cases

CodeMark+ works especially well for:

TODO/FIXME workflows
lightweight technical debt tracking
operational implementation notes
contextual navigation between notes and code
migration workflows
temporary investigation tracking
large codebases with scattered annotations
annotation-driven operational workflows
developer-focused workspace documentation

Requirements

Visual Studio Code ^1.102.0

Extension Settings

CodeMark+ includes configurable settings for:

annotation highlighting
contextual navigation
template generation
wrapping behavior
Tag Browser behavior
Markdown workspace notes
formatting preferences
language-specific templates

Open:

Preferences → Settings → CodeMark+

to explore available configuration options.

Contributing

CodeMark+ is open-source and welcomes community contributions:

Fork the GitHub repository.
Create a new branch:
```
git checkout -b feature/your-feature
```
Make your changes, commit them, and push to your fork.
Submit a Pull Request against the main branch.

Before contributing, please review the Contribution Guidelines for coding standards, testing, and commit message conventions. Open an Issue if you find a bug or want to request a new feature.

Code of Conduct

We are committed to providing a friendly, safe, and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or other personal characteristic. Please review our Code of Conduct before participating in our community.

Changelog

For a complete list of changes, see the CHANGELOG.md.

Authors

Manuel Gil - Owner - @ManuelGil

See also the list of contributors who participated in this project.

Follow Me

GitHub:
X (formerly Twitter):

Other Extensions

Auto Barrel Automatically generates and maintains barrel (index.ts) files for your TypeScript projects.
Angular File Generator Generates boilerplate and navigates your Angular (9→20+) project from within the editor, with commands for components, services, directives, modules, pipes, guards, reactive snippets, and JSON2TS transformations.
NestJS File Generator Simplifies creation of controllers, services, modules, and more for NestJS projects, with custom commands and Swagger snippets.
NestJS Snippets Ready-to-use code patterns for creating controllers, services, modules, DTOs, filters, interceptors, and more in NestJS.
T3 Stack / NextJS / ReactJS File Generator Automates file creation (components, pages, hooks, API routes, etc.) in T3 Stack (Next.js, React) projects and can start your dev server from VSCode.
Drizzle ORM Snippets Collection of code snippets to speed up Drizzle ORM usage, defines schemas, migrations, and common database operations in TypeScript/JavaScript.
CodeIgniter 4 Spark Scaffolds controllers, models, migrations, libraries, and CLI commands in CodeIgniter 4 projects using Spark, directly from the editor.
CodeIgniter 4 Snippets Snippets for accelerating development with CodeIgniter 4, including controllers, models, validations, and more.
CodeIgniter 4 Shield Snippets Snippets tailored to CodeIgniter 4 Shield for faster authentication and security-related code.
Mustache Template Engine - Snippets & Autocomplete Snippets and autocomplete support for Mustache templates, making HTML templating faster and more reliable.

Recommended Browser Extension

For developers who work with .vsix files for offline installations or distribution, the complementary One-Click VSIX extension is recommended, available for both Chrome and Firefox.

One-Click VSIX integrates a direct "Download Extension" button into each VSCode Marketplace page, ensuring the file is saved with the .vsix extension, even if the server provides a .zip archive. This simplifies the process of installing or sharing extensions offline by eliminating the need for manual file renaming.

License

This project is licensed under the MIT License. See the LICENSE file for details.

CodeMark+ - Annotations & Comment Templates

Manuel Gil

CodeMark+

Why CodeMark+ Exists

What CodeMark+ Is

Core Philosophy

Operational Context Model

Contextual Navigation Semantics

File Navigation

Contextual Anchor

Precise Anchor

Explicit Range

Scoped Annotation Discovery

Core Features

Annotation Highlighting

Workspace Tag Browser

Contextual Navigation

Lightweight Workspace Notes

Customizable Annotation Templates

Example Workflows

Track Technical Debt

Preserve Operational Context

Lightweight Investigation Notes

Generate Consistent Documentation

Screenshots

Annotation Highlighting

Workspace Tag Browser

Contextual Navigation

Workspace Notes

Documentation Templates

Configuration

Highlight Rules

Annotation Templates

Storage Philosophy

Performance

Design Philosophy

Best Use Cases

Requirements

Extension Settings

Contributing

Code of Conduct

Changelog

Authors

Follow Me

Other Extensions

Recommended Browser Extension

License