███╗   ██╗ ██████╗ ████████╗███████╗██████╗    ███╗   ███╗██████╗
          ████╗  ██║██╔═══██╗╚══██╔══╝██╔════╝██╔══██╗   ████╗ ████║██╔══██╗
          ██╔██╗ ██║██║   ██║   ██║   █████╗  ██║  ██║   ██╔████╔██║██║  ██║
          ██║╚██╗██║██║   ██║   ██║   ██╔══╝  ██║  ██║   ██║╚██╔╝██║██║  ██║
          ██║ ╚████║╚██████╔╝   ██║   ███████╗██████╔╝██╗██║ ╚═╝ ██║██████╔╝
          ╚═╝  ╚═══╝ ╚═════╝    ╚═╝   ╚══════╝╚═════╝ ╚═╝╚═╝     ╚═╝╚═════╝
  

A command-line tool to convert handwritten notes into a clean and readable Markdown file.

---

noted.md is a CLI tool that uses LLMs to convert your handwritten text into markdown files. It's an interactive program that accepts pdfs, jpg, jpeg, png as an input and processes them accordingly. It can recognize mathematical equations too and can correctly format them in LaTeX. noted.md now supports processing specific pages of a PDF (e.g., "1,3-5,8"), efficiently handles batches of pages in a single AI request, and intelligently resumes interrupted conversions! And if you have a bunch of files to convert them at once, noted.md supports batch processing for directories too!

Additional features include per-page JSON output, extracting specific pages into a named file, automatic retry on API failures, and verbose debugging for troubleshooting.

notedmd.mp4

Installation

noted.md can be installed on macOS, Linux, and Windows.

macOS & Linux (Recommended: Homebrew)

For the easiest installation on macOS and Linux, use Homebrew:

brew tap tejas-raskar/noted.md
brew install notedmd

To update noted.md to the latest version:

brew upgrade notedmd

Manual Download (Windows)

For Windows, download the latest .zip archive from the Releases page. Extract the contents and add the bin directory to your system's PATH.

Building from Source

If you prefer to build from source, clone the repository and use Cargo:

git clone https://github.com/tejas-raskar/noted.md.git
cd noted.md
cargo build --release
# The executable will be in target/release/notedmd

Usage

The typical workflow is:

1. Configure your AI provider: Use notedmd config --edit for a guided setup.
2. Convert your files: Use notedmd convert <path> to process your notes.

Commands

Command	Description
notedmd convert	Converts a file or all supported files in a directory into Markdown.
notedmd config	Manages the AI provider configuration. Shows the current config if no flags are used.

---

Configuration

Interactive Setup (Recommended)

For first-time users, the interactive setup is the easiest way to get started. Run:

notedmd config --edit

This will guide you through selecting an AI provider (Gemini, Claude, or Ollama) and entering the necessary credentials, such as API keys or server details.

AI Providers

You can choose between three AI providers.

Gemini and Claude APIs

You will need an API key from your chosen provider:

• Gemini API: Google AI Studio
• Claude API: Anthropic's website

Ollama

Make sure Ollama is installed and running on your local machine. You can download it from Ollama's website.

OpenAI API compatible clients

Supports all clients that are compatible with the OpenAI API. LM Studio for example.

Managing Configuration via Flags

You can also manage your configuration directly using flags.

Flag	Description
--set-provider <provider>	Set the active provider (gemini, claude, ollama).
--set-api-key <key>	Set the API key for Gemini.
--set-claude-api-key <key>	Set the API key for Claude.
--show	Display the current configuration.
--show-path	Show the path to your configuration file.
--edit	Start the interactive configuration wizard.

Examples:

• Set the active provider to Claude:

  notedmd config --set-provider claude

• Set your Gemini API key:

  notedmd config --set-api-key YOUR_GEMINI_API_KEY

---

Converting Files

Once configured, you can convert your handwritten notes.

Flag	Description
-o, --output <dir>	Specify a directory to save the converted Markdown file(s).
-p, --prompt <prompt>	Add a custom prompt to override the default instructions for the LLM.
--api-key <key>	Temporarily override the stored API key for a single convert command.
--pages <ranges>	For PDFs: Specify specific pages or page ranges to convert (e.g., "1,3-5,8"). Can resume from last progress.
--pages-per-batch <num>	Number of pages to process at once (max 30). Default: 1.
--json	Output a JSON file alongside the Markdown with per-page OCR results.
--extract <pages-file>	For PDFs: Extract specific pages into a named file (e.g., "1,22,54,86-table.md").
--retry <num>	Number of times to retry on API failure. Default: 3.
-v, --verbose	Enable verbose output for debugging (shows full API request/response).

Examples:

• Convert a single file: The converted file will be saved in the same directory with a .md extension (e.g., my_document.md).

  notedmd convert my_document.pdf

• Convert specific pages of a PDF:

  notedmd convert my_textbook.pdf --pages "1,5-7,10"

• Convert a file with a custom prompt:

  notedmd convert my_notes.png --prompt "Transcribe this into a bulleted list."

• Convert a file and save it to a different directory:

  notedmd convert my_document.pdf --output ./markdown_notes/

• Generate per-page JSON alongside the markdown:

  notedmd convert my_textbook.pdf --json

• Extract specific pages into a named file:

  notedmd convert my_textbook.pdf --extract "1,22,54,86-table.md"

• Increase retries and enable verbose debugging:

  notedmd convert my_document.pdf --retry 5 -v

• Convert all supported files in a directory:

  notedmd convert ./my_project_files/

• Convert all files in a directory to a specific output directory:

  notedmd convert ./my_project_files/ --output ./markdown_notes/

Contributing

Contributions are welcome! If you have a feature request, bug report, or want to contribute to the code, please feel free to open an issue or a pull request on our GitHub repository.

License

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