https://github.com/nicksp/vscode-notelets
Sticky notes for your codebase. Create and manage Markdown notes linked to source files in VS Code.
https://github.com/nicksp/vscode-notelets
Last synced: 10 months ago
JSON representation
Sticky notes for your codebase. Create and manage Markdown notes linked to source files in VS Code.
- Host: GitHub
- URL: https://github.com/nicksp/vscode-notelets
- Owner: nicksp
- License: mit
- Created: 2025-08-23T02:18:13.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-09-03T17:37:42.000Z (11 months ago)
- Last Synced: 2025-09-24T13:59:18.991Z (11 months ago)
- Language: TypeScript
- Homepage: https://marketplace.visualstudio.com/items?itemName=nicksp.notelets
- Size: 330 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Notelets
Add sticky notes for your code — Markdown files alongside your project, organized by path.
**Install from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=nicksp.notelets) or [Open VSX Registry](https://open-vsx.org/extension/nicksp/notelets).**
## Features
- Add a note for any non-Markdown file with a single command or click.
- Notes are plain Markdown files stored under a configurable folder (defaults to `.vscode/notelets/`) mirroring your project structure.
- Fast, minimal, zero distractions:
- CodeLens at the top of source files: "Add Note" / "Open Note".
- Optional status bar indicator showing if a note exists.
- Possibility to browse all notes in the workspace.
- Smart behavior:
- Renaming a file renames its note.
- Deleting a file deletes its note.
- No notes for Markdown files or notes themselves (by design).
- Almost zero config; sensible defaults.
## Motivation
I wanted a coherent workflow where lightweight documentation lives with the code it describes using the familiar convenience of Markdown:
- Notes are plain Markdown inside your repo, version‑controlled with your code and reviewable.
- The folder mirrors your project structure, so a note naturally “belongs” to a file and travels with it on rename/move.
- No proprietary storage, no external sync, and works offline on any machine.
- Collaboration is simple: commit, push, review, and share with the team like any other code change.
- Minimal UI and zero lock‑in by design.
> [!TIP]
> To exclude notelets from version control, add `notelets.notesFolder` setting value to your `.gitignore`:
>
> ```shell
> .vscode/notelets/
> ```
## Commands
You can run these commands from the Command Palette (Cmd+Shift+P on a Mac, or Ctrl+Shift+P on Windows).
| Description | Name | Default Mac | Default Windows |
| --------------------- | ------------------- | ----------- | --------------- |
| Open or create a note | `notelets.openNote` | — | — |
| Focus on notes view | | — | — |
> [!TIP]
> [Bind a key](https://code.visualstudio.com/docs/configure/keybindings) to `notelets.openNote` for even faster access.
## Settings
You can change the following options in the [Visual Studio Code settings](https://code.visualstudio.com/docs/configure/settings).
| Description | Setting | Default |
| ---------------------------------------------------------- | ------------------------------------------------------------------ | ------------------ |
| Relative path to the root folder where Notelets are stored | [notelets.notesFolder](vscode://settings/notelets.notesFolder) | `.vscode/notelets` |
| How to open notes: editor or Markdown preview | [notelets.openBehavior](vscode://settings/notelets.openBehavior) | `editor` |
| Show a status bar item when a file has a Notelet | [notelets.showStatusBar](vscode://settings/notelets.showStatusBar) | `true` |
## How It Works
- For a file like `src/utils/math.ts`, its note will be created (by default) at:
- `.vscode/notelets/src/utils/math.ts.md`
- Notes follow file renames and moves, and are removed when the source file is deleted.
- Notes are not created for Markdown files or for note files themselves.
## Changelog
The changelog can be found in [CHANGELOG.md](CHANGELOG.md).
## You May Also Like
Check out my other Visual Studio Code extensions:
- [Reveal on GitHub](https://marketplace.visualstudio.com/items?itemName=nicksp.reveal-on-github) — open the current project or file on GitHub
- [Tidy Space](https://marketplace.visualstudio.com/items?itemName=nicksp.tidy-space) — keep your workspace clutter-free: only one sidebar at a time
## Sponsoring
This project is maintained in my spare time. If this has been helpful to you, consider supporting its continued development and maintenance.
## Contributing
Bug fixes are welcome, but not new features. Read our [contributing guidelines](CONTRIBUTING.md) to learn more.
[Open an issue](https://github.com/nicksp/vscode-notelets/issues) on GitHub and [submit a pull request](https://github.com/nicksp/vscode-notelets/pulls).
## Authors and License
[Nick Plekhanov](https://plekhanov.me) and [contributors](https://github.com/nicksp/vscode-notelets/graphs/contributors).
[Icon by Creative Squad](https://www.freepik.com/search).
[MIT License](LICENSE.md).