gopuntes

gopuntes_demo.mp4

A flexible note-browsing tool 💖🇪🇸

gopuntes is a terminal-based application for browsing and viewing your local notes. It provides a fast and simple TUI (Text User Interface) to navigate through your Markdown and PDF files stored in a designated directory.

Built with Go & Bubble Tea framework.

🧰 Features

• Terminal-based UI: Browse your notes without leaving the terminal.
• Multi-format Support: Natively renders Markdown (.md) files and opens PDF (.pdf) files in your system's default viewer.
• Simple Setup: On first run, gopuntes will prompt you to set the path to your notes directory.
• Fuzzy Search: Quickly filter and find the note you're looking for.
• Cross-Platform: Works on macOS & Linux.

🛠️ Installation

📦 Binary Releases

Pre-compiled binaries for Linux, Windows, and macOS are available on the Releases page.

🐹Using Go

You can install gopuntes directly using go install:

go install github.com/qrxnz/gopuntes@latest

🏗️ Build from Source

To build from source, you need to have Go installed.

git clone https://github.com/qrxnz/gopuntes.git
cd gopuntes
go build -o gopuntes .

Alternatively, if you have Task installed, you can use:

task build

❄️ Using Nix

• Run without installing:

nix run github:qrxnz/gopuntes

• Add to a Nix Flake:

Add input in your flake like

{
 inputs = {
   gopuntes = {
     url = "github:qrxnz/gopuntes";
     inputs.nixpkgs.follows = "nixpkgs";
   };
 };
}

With the input added you can reference it directly

{ inputs, system, ... }:
{
  # NixOS
  environment.systemPackages = [ inputs.gopuntes.packages.${pkgs.system}.default ];
  # home-manager
  home.packages = [ inputs.gopuntes.packages.${pkgs.system}.default ];
}

• Install imperatively:

nix profile install github:qrxnz/gopuntes

📖 Usage

Simply run the application from your terminal:

gopuntes

On the first launch, you will be prompted to enter the absolute path to the directory where your notes are stored. This path is saved in ~/.config/gopuntes/config.toml.

Keybindings

• Arrow Keys (↑/↓): Navigate the list of notes.
• Enter: View the selected note. (Renders Markdown inside the TUI, opens PDFs externally).
• /: Start filtering/searching.
• q / esc: Quit the note view or the filter view.
• Ctrl+C: Exit the application.

👨🏻‍💻 Development

This project uses Nix with flakes and direnv to provide a reproducible development environment.

1. Clone the repository:

   git clone https://github.com/qrxnz/gopuntes.git
   cd gopuntes

2. Activate the environment: If you have Nix and direnv installed, the environment should be activated automatically when you enter the directory. If not, run:

   direnv allow

3. Available Commands: This project uses go-task as a command runner. Here are the most common commands:

   • task build: Build a production binary.
   • task test: Run unit tests.
   • task lint: Run the linter and fix issues.

🗒️ Credits

🎨 Inspiration

I was inspired by:

• charmbracelet/glow

📜 License

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