NoteThink

A VS Code extension that renders markdown files as interactive visualizations.

Status: Preview / Beta - this is an early release. Expect rough edges.

Features

• Custom Editor: Open markdown files in a visual editor alongside the standard text editor
• Interactive Views: Notes rendered as structured, interactive components
• Component Library: Reusable React components for building note visualizations
• Live Updates: File changes detected and re-rendered with debounce
• GFM Support: Tables, strikethrough, task lists, footnotes
• Frontmatter: YAML frontmatter parsed and handled
• Debug Support: Built-in debug logging for development

Installation

From Marketplace

Install NoteThink from the Visual Studio Marketplace:

• In VS Code, open the Extensions view (Ctrl+Shift+X), search for NoteThink, and click Install, or

• From the command line:

  code --install-extension NoteThink.notethink
  

From .vsix

pnpm run package:vsix
code --install-extension notethink-<version>.vsix

Usage

1. Open any markdown file (.md)
2. Use the command palette (Ctrl+Shift+P) and run "NoteThink: Open Viewer"
3. Or right-click on a markdown file and select "Open With..." → "NoteThink"

For the conventions your markdown should follow - heading levels, story structure, linetag syntax, epics, Folder mode - see AUTHORING_GUIDE.md.

Development

Prerequisites

• Node.js 20+
• pnpm 9+
• VS Code

Setup

git clone https://github.com/ZoomBuzz/NoteThink.git
cd NoteThink
pnpm install

postinstall runs automatically and installs dependencies in the client/extension, client/webview, and client/webview/src/notethink-views sub-packages.

Dev workflow

1. Open the repo in VS Code: code .
2. Press F5 (or Run > Start Debugging). This launches "Run Web Extension" which:
   • Runs pnpm run watch (webpack in watch mode) as a pre-launch task
   • Opens a new Extension Development Host window
3. In the dev host, open any .md file and right-click → "Open With..." → "NoteThink"
4. Edit the markdown in the standard editor - the NoteThink view updates live (250ms debounce)
5. Code changes in client/extension/src/ or client/webview/src/ are recompiled automatically by webpack watch. Reload the dev host window (Ctrl+R) to pick them up.

Inspecting the webview

The NoteThink view runs in a webview iframe. To inspect it:

• In the dev host: Help > Toggle Developer Tools (Shift+Ctrl+I)
• Enable debug logging in the console: localStorage.debug = 'nodejs:*'

For a fuller walkthrough - where host vs webview logs land, how the dev-only notethink-extension.log file works, and what to capture when filing a bug - see docstech/bug-reports.md.

Commands

Command	Description
pnpm install	Install all dependencies (root + sub-packages)
pnpm run compile	One-shot webpack build
pnpm run watch	Webpack watch mode (used by F5 launch)
pnpm run package	Production build (minified, hidden source maps)
pnpm run lint	ESLint
pnpm test	Run all unit tests (webview + notethink-views)
pnpm run chrome	Launch in browser via vscode-test-web (Chromium)
pnpm run package:vsix	Build a .vsix for local install

Testing

Unit tests (Jest):

pnpm test                        # all tests (35)
cd client/webview && pnpm test   # webview tests (14)
cd client/webview/src/notethink-views && pnpm test  # component library tests (21)

Manual extension testing: Press F5, then in the dev host:

• Open a .md file → right-click → "Open With..." → NoteThink
• Run "NoteThink: Open Viewer" from the command palette
• Check that headings, code blocks, lists, and task lists render
• Edit the file and verify the view updates
• Open Toggle Developer Tools and check for console errors

Browser testing: pnpm run chrome launches the extension in Chromium via vscode-test-web, opening the docstech/ folder as a workspace.

Building a .vsix

pnpm run package:vsix

This runs the production build (vscode:prepublish) then packages into notethink-<version>.vsix. Install locally with:

code --install-extension notethink-<version>.vsix

Project Structure

notethink/
├── client/
│   ├── extension/           # VS Code extension (runs in webworker)
│   │   ├── src/
│   │   │   ├── extension.ts # entry point
│   │   │   ├── vscode/      # notethinkEditor, custom editor provider
│   │   │   └── lib/         # parseops, crypto, utils, errorops
│   │   └── dist/            # compiled output (gitignored)
│   │
│   └── webview/             # React webview (renders in iframe)
│       ├── src/
│       │   ├── components/  # ExtensionReceiver, NoteRenderer, App
│       │   └── notethink-views/  # component library (DocumentView, GenericNote, etc.)
│       └── dist/            # bundled webview (gitignored)
│
├── .github/workflows/ci.yml # CI: lint, test (webview + notethink-views)
├── webpack.config.js        # two configs: extension + webview
└── eslint.config.mjs

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        VS Code                              │
│  ┌───────────────────┐    ┌─────────────────────────────┐   │
│  │    Extension      │    │        Webview              │   │
│  │  (webworker)      │    │      (iframe)               │   │
│  │                   │    │                             │   │
│  │  ┌─────────────┐  │    │  ┌───────────────────────┐  │   │
│  │  │ notethink   │──┼────┼──│  ExtensionReceiver    │  │   │
│  │  │ Editor.ts   │  │    │  │  (hash-based delta)   │  │   │
│  │  └─────────────┘  │    │  └───────────┬───────────┘  │   │
│  │         │         │    │              │              │   │
│  │         ▼         │    │              ▼              │   │
│  │  ┌─────────────┐  │    │  ┌───────────────────────┐  │   │
│  │  │  parseops   │  │    │  │    NoteRenderer       │  │   │
│  │  │  crypto     │  │    │  │                       │  │   │
│  │  └─────────────┘  │    │  └───────────┬───────────┘  │   │
│  │                   │    │              │              │   │
│  └───────────────────┘    │              ▼              │   │
│                           │  ┌───────────────────────┐  │   │
│                           │  │   notethink-views     │  │   │
│                           │  │   (React.memo'd)      │  │   │
│                           │  └───────────────────────┘  │   │
│                           └─────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Data flow:

1. Extension finds all *.md files, parses each to MDAST, computes SHA-256 hash
2. Docs sent to webview via postMessage
3. ExtensionReceiver compares hashes - unchanged docs are skipped
4. NoteRenderer converts MDAST to NoteProps hierarchy via convertMdastToNoteHierarchy
5. DocumentView and GenericNote (both React.memo'd) render the note tree

Known Limitations

• Read-only: No editing support yet - NoteThink is a viewer, not an editor

Contributing

See CODING_STANDARDS.md for code style guidelines and AGENTS.md for project conventions.

License

Apache-2.0