Notely

A desktop Markdown notes app for team and project workspaces.

Notely is built with Electron + React and is designed for project notes, meeting records, document history, image handling, and markdown authoring in one place.

Key Features

• Open and manage Markdown notes inside a chosen workspace folder.
• Organize work into projects and a root workspace.
• Edit Markdown in raw, split, preview, and web modes.
• Validate Markdown structure while you type.
• Check typos in the editor.
• Search notes by title, metadata, path, and in-file content with match previews.
  • Regex search with validation and pattern matching for advanced queries.
  • Code-aware search to find patterns inside code blocks only.
• Insert common Markdown snippets from the toolbar.
• Browse, annotate, optimize, and manage linked media.
• Open note files in VS Code or the system default app.
• Open the current workspace folder in VS Code directly from File -> Open Workspace in VS Code (Ctrl/Cmd + Shift + O) on the landing screen.
• Reveal the workspace folder in the system File Explorer from File -> Reveal Workspace in File Explorer (Ctrl/Cmd + Shift + J) on the landing screen.
• Open the project website or the current note's website view from the Web menu (Ctrl/Cmd + Shift + W).
• Compare note history versions and restore context from older revisions.
• Preview Mermaid diagrams and rendered Markdown content.
• Visualize the workspace as an interactive note graph.
• Use built-in AI features powered by Gemini or Groq for chat, queries, and semantic search.
• Aggregate tasks across notes with Open Tasks and All Tasks panels.
  • Open Tasks focuses on unchecked items.
  • All Tasks includes open + closed items with filtering and note grouping.
  • Dashboard widgets and note-level task summaries help you triage quickly.
• Export the workspace as a .zip bundle from the landing File menu with selectable format.
  • Notes as-is (.md + assets)
  • PDF-only (one PDF per note)
  • Web format (static HTML export package)
  • Optional .notes-app metadata inclusion (default off)
• View note statistics (word count, line count, reading time estimate) in the status bar.
• Copy note content as HTML or plain text directly from the editor toolbar.
• Navigate nested folders with breadcrumb links for easy folder traversal.

Getting Started

Current packaged release target:

• Windows x64 portable build via npm run dist:win

Development prerequisites:

• Node.js 20 or later
• npm 10 or later
• Windows if you need packaged build output from the included packaging scripts

Optional environment variables:

• NOTES_ROOT to open a specific workspace folder on launch
• CSC_LINK, CSC_KEY_PASSWORD, or CSC_NAME for Windows signing
• NOTELY_TERMINAL_REQUIRED_ROLE, NOTELY_TERMINAL_POLICY, and NOTELY_TERMINAL_ALLOWLIST for embedded terminal hardening

End-user first run:

1. Launch the app.
2. Open File -> Open Workspace.
3. Choose the folder that should hold your notes.
4. Create a note with File -> New Note.
5. Open Help -> Help Center or Help -> Keyboard Shortcuts if you need guidance.

In-app Help Center

Notely includes built-in user documentation in the app menu:

• Open Help -> Help Center (or press F1) to view app usage guidance directly in the app.
• Open Help -> Keyboard Shortcuts for shortcut references.
• Open Help -> About Notely to view a dedicated About dialog with product identity and build information.

The Help Center includes quick start, core features, shortcuts, and storage/versioning notes so users do not need to leave the app to find documentation. The Help Center now reads its content directly from the repository docs/ folder so in-app and repository documentation stay aligned.

Development

Install dependencies

npm install

Run in development

npm run dev

Build for production

npm run build

Run tests

npm test

Run local P2P harness

npm run test:p2p

This harness is designed for one-machine validation of planned peer-to-peer flows without cloud dependencies. It validates:

• Peer discovery
• Human-readable pairing code handshake
• Workspace key exchange to trusted peers
• Encrypted message sync using workspace keys
• Workspace key rotation and re-share
• Peer revoke behavior

Harness output artifacts are written to .artifacts/p2p-harness/.

Run packaged P2P validation preflight

npm run test:p2p:packaged

This command checks whether expected Windows release executables are present and prints a repeatable two-machine LAN validation checklist.

Markdown linting

npm run lint:markdown

Full CI check

npm run ci:check

Packaging

Windows packaging scripts are included in the repo:

• npm run pack:win builds an unpacked Windows app.
• npm run dist:win builds distributable Windows installers.
• ./build-windows-exe.sh is available for the current packaging flow.

Build versioning & Release

Notely build versions are tracked in app-version.json and package.json.

To release a new version of Notely, simply run the automated release script:

./release.sh

This script will:

• Run the local CI suite (npm run ci:check)
• Automatically bump the patch version in both app-version.json and package.json
• Update the version badge in this README.md
• Ask for your confirmation
• Commit the changes and tag the repo (vX.Y.Z)
• Push the tag to GitHub

Pushing the v* tag triggers the Continuous Deployment (CD) pipeline (.github/workflows/cd.yml), which automatically builds the Windows .exe and publishes it to GitHub Releases.

Project structure

• electron/ Electron main process and preload bridge
• src/ React UI, editor, validation, and utilities
• scripts/ packaging and release helpers
• notes/ sample notes and workspace content
• build/ app icons and build assets
• release/ collected release outputs

Roadmap

Planned additions and improvements for upcoming iterations:

• Diagram version timeline with visual compare and restore.
• Excalidraw element comments and review threads.
• Search indexing for diagram text/content.
• Update-from-source flow for image-converted Excalidraw diagrams.
• Interactive diagram hotspots linking to notes/files.
• Expanded P2P sync dashboard with per-peer media/diagram health.
• OCR-assisted alt text suggestions for inserted images.
• Command palette automation macros for repeated authoring tasks.

License and ownership

This repository is maintained for Notely use.

• Project license: CC BY-NC 4.0 (see LICENSE).
• Third-party dependency notices: see THIRD_PARTY_NOTICES.txt.