plain Markdown files with no database and no lock-in**

1 Overview of Tp-Note

Tp-Note is a versatile note-taking tool designed for both desktop and console environments. It allows users to create, edit, and manage notes efficiently. Tp-Note is designed to bridge the gap between unstructured clipboard data and organized, local file storage. It is primarily built in Rust and follows a “file-centric” philosophy where the filename itself acts as a synchronized piece of metadata. This tool is ideal for users looking for a simple yet powerful way to manage their notes across different platforms.

A more sophisticated example using the “Zettelkasten” scheme:

1.1 Key Features

• Clipboard Integration: Tp-Note can save and edit clipboard content as note files, making it easy to capture information quickly.

• Template System: It uses customizable templates to synchronize note metadata with filenames, enhancing organization.

• Markdown Support: Users can convert HTML content to Markdown. Notes are rendered from Markdown to HTML when viewed with Tp-Note’s internal web server.

• Plain Markdown Viewer/Editor: Tp-Note can open, view, and edit any plain Markdown file — even without a YAML front matter header — without modifying it. Use --add-header to additionally prepend a YAML header and convert the file into a full Tp-Note note.

• File Management: Notes can be created from existing files or directories, and users can easily navigate and edit their notes.

1.2 Usage Examples

1.3 User review

On Tue, 2023-12-19 at 12:58 +1100, Dev Rain wrote:

Found Tp-Note awhile back and it has become part of my daily workflow, and indeed part of my daily note-taking life. I wanted to extend my thanks; so thank you. dev.rain

Read more in Tp-Note’s user manual, Download Tp-Note or visit the project page: Tp-Note - Minimalistic note-taking.

2 Documentation

User documentation:

• Introductory video

  Tp-Note - Most common use cases - YouTube

• Project page:

  Tp-Note’s project page, which you are reading right now, lists where you can download Tp-Note and gives an overview of Tp-Note’s resources and documentation.

• User manual:

  The user manual showcases how to best use use Tp-Note and how to integrate it with your file manager.

  Tp-Note user manual - html

  Tp-Note user manual - pdf

• Unix man-page:

  The Unix man-page is Tp-Note’s technical reference. Here you learn how to customize Tp-Note’s templates and how to change its default settings.

  Tp-Note manual page - html

  Tp-Note manual page - pdf

• Blogposts about Tp-Note

Developer documentation:

• API documentation

  Tp-Note’s program code documentation targets mainly software developers. The code is split into a library tpnote-lib and the command line application tpnote. The advanced user may consult the Tp-Note’s config module documentation and the constants in the API documentation which explain the various settings. Most of them can be customized through Tp-Note’s configuration file.

3 Source code

Repository:

• Tp-Note on Gitlab

• Tp-Note on Github (mirror)

3.1 Distribution

3.1.1 Download from the GitHub releases page

All precompiled binaries, installer packages and the documentation are published on the GitHub releases page — the single official download location:

• Tp-Note releases on GitHub

Open the latest release and download the asset for your platform from its Assets list. Every release provides the following files (<version> is the release number, e.g. 1.27.0):

Each .tar.gz / .zip archive contains a single, stripped tpnote executable; the .deb and .msi are installer packages.

3.1.2 Tp-Note Microsoft Windows installer package

Download and run tpnote-<version>-x64.msi from the latest release.

As this early version of the Windows installer is not signed yet, Windows will show the error message “Windows protected your PC”. As a work-around, when you click on the link “More info”, a ”Run anyway” button will appear allowing you to continue the installation process. In general, regardless of where a program comes from, I recommend checking every installable file with VirusTotal.

Once installation is complete, right-click on the Desktop and select “Show more options” to find the “New Tp-Note” entry in the menu.

3.1.3 Tp-Note Debian/Ubuntu installer package

Download tpnote_<version>_amd64.deb from the latest release and install it:

sudo dpkg -i tpnote_<version>_amd64.deb

3.1.4 Standalone binaries for Windows, macOS and Linux

Prefer a bare executable? From the latest release, download the .tar.gz (Linux/macOS) or .zip (Windows) archive for your target (see the table above), unpack the single tpnote binary and place it on your PATH (see the Installation section below).

3.2 Tp-Note in official package repositories

3.2.1 Windows Package Manager (winget) Distribution

Tp-Note is also available through the Windows Package Manager. To install:

winget install -e --id getreu.tpnote

Following installation, right-click the Desktop and click “Show more options” to reveal the “New Tp-Note” context menu entry.

3.2.2 Tp-Note on NixOS

• An official package is available on NixOS:

  environment.systemPackages = [ pkgs.tpnote ];

3.2.3 Get Tp-Note with the Nix package manager

• First install the Nix package manager available for Linux, MacOS and Windows (WSL2). Alternatively, for Linux there are also prebuilt Deb/Pacman/Rpm Nix installers available.

  Once you have the Nix package manager installed on your system, try out Tp-Note with:

  nix-shell -p tpnote

  or follow installation instructions here: NixOS packages - tpnote

3.3 Other resources

• The Unix man page ships inside tpnote-<version>-docs.tar.gz (see the latest release); unpack it and copy to /usr/local/share/man/man1.

• Copy Tp-Note’s icon to /usr/local/share/icons/:

  • tpnote.svg

4 Installation

Tp-Note can be installed via a Windows installer package or by placing the binary directly on your desktop for easy access. It is recommended to integrate it into your file manager’s context menu for convenience.

Depending on the availability of installer packages for your operating system, the installation process is more or less automated. For Windows users the fully automated installer tpnote-<version>-x64.msi is available on the latest release. After installation, click right on the desktop and select “Show more options”, then “New Tp-Note” to get started. For more information, please consult the Distribution section above and the Installation section in Tp-Note’s manual.

4.1 Upgrading

This section only applies to you if you have overwritten some of Tp-Note’s internal default configuration values with a custom configuration file. Learn more about how the configuration is merged from different file locations in the Customization section of Tp-Note’s manual page.

While upgrading Tp-Note, new features may cause a change in Tp-Notes’s configuration file structure, e.g.:

*** ERROR:
Can not load or parse the (merged) configuration file(s):
---
invalid length 3, expected fewer elements in array in `viewer.served_mime_types`


Note: this error may occur after upgrading Tp-Note due to some incompatible
configuration file changes.

Tp-Note renames and thus disables the last sourced configuration file.

Additional technical details:
*    Command line parameters:
tpnote -b
*    Sourced configuration files:
/home/joe/.config/tpnote/tpnote.toml

Note, the configuration file backup is stored in the same directory as the last sourced configuration file, e.g. /home/joe/.config/tpnote/. If Tp-Note sources more than one configuration file, consider the possibility of syntax errors in any of these files (cf. Customization section of Tp-Note’s man-page).

5 Building

If the above precompiled binaries do not suite you, you can compile Tp-Note yourself.

1. Install Rust

2. Download, compile and install Tp-Note:

   Building on Linux

   cargo install tpnote
   sudo cp ~/.cargo/bin/tpnote /usr/local/bin
   # Download icon
   cd /usr/local/share/icons
   sudo wget https://blog.getreu.net/projects/tp-note/assets/tpnote.svg

   On Linux, Tp-Note displays errors and debug messages as notifications. This requires a Linux/BSD based desktop environment that follows the XDG specification, e.g. KDE, Gnome, XFCE, LXDC, Mate (and most others).¹

   Recommended Linux console and server version

   The full-featured version of Tp-Note depends on GUI libraries like Xlib which might not be available on a headless system. Either download the Musl archive tpnote-<version>-x86_64-unknown-linux-musl.tar.gz from the latest release or compile Tp-Note yourself without default features:

   cargo install --no-default-features \
     --features lang-detection,renderer,mermaid,latex tpnote
   sudo cp ~/.cargo/bin/tpnote /usr/local/bin

   If Tp-Note’s binary size if of concern, omit the lang-detection feature in the cargo invocation above. The lang-detection feature causes 95% of the final binary size because of its extensive language models.

   Building on Windows and macOS

   Build the full-featured version² with:

   cargo install tpnote

5.1 Cross compilation

Tp-Note supports cross-compilation for multiple architectures. There are two independent ways to do this: with the standard Rust toolchain (rustup + cargo), or with Nix, if you already work in a Nix/NixOS environment. Pick one — they are not meant to be mixed.

5.1.1 Standard cross compilation (rustup + cargo)

The project includes pre-configured cross-compilation settings in .cargo/config.toml. This is the recommended path if you are not using Nix.

Building for Debian/Ubuntu, including Raspberry Pi (Recommended)

Install the cross-compiler toolchains:

sudo apt update
sudo apt install crossbuild-essential-armhf crossbuild-essential-arm64

Build for Raspberry Pi 32-bit (ARMv7):

rustup target add armv7-unknown-linux-gnueabihf
cargo build --release --target armv7-unknown-linux-gnueabihf

The binary will be at: target/armv7-unknown-linux-gnueabihf/release/tpnote

Build for Raspberry Pi 64-bit (ARM64):

rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu

The binary will be at: target/aarch64-unknown-linux-gnu/release/tpnote

Building for Musl Linux (static)

For a fully static binary that works on any Linux distribution:

rustup target add x86_64-unknown-linux-musl
sudo apt install musl-tools
cargo build --release --target x86_64-unknown-linux-musl

Building for Windows

rustup target add x86_64-pc-windows-gnu
sudo apt install binutils-mingw-w64 mingw-w64
cargo build --release --target x86_64-pc-windows-gnu

5.1.2 Cross compilation with Nix

The recommended way on NixOS, instead of rustup/cargo above, is to use the Nix flake. The flake offers separate targets for standard Linux and for NixOS itself — see the comments at the top of flake.nix for the full compatibility matrix and rationale.

Building for standard Linux (glibc, portable binary) — architectures: x86_64, armv7 (Raspberry Pi 32-bit), aarch64 (Raspberry Pi 64-bit / ARM servers). Compatible with Debian 11+, Ubuntu 20.04+, Raspberry Pi OS:

# Build for x86_64
nix build .#tpnote-x86_64-unknown-linux-gnu

# Build for ARMv7 (32-bit) for Raspberry Pi
nix build .#tpnote-armv7-unknown-linux-gnueabihf

# Build for ARM64 (64-bit) for Raspberry Pi and ARM servers
nix build .#tpnote-aarch64-unknown-linux-gnu

# Build the Debian package (for x86_64 only)
nix build .#tpnote-deb

Building for NixOS (native Nix-store binary) — architecture: x86_64. Runs via nix run/nix build on NixOS (or any host with access to the same Nix store), but will not run if copied to a system without that store:

nix build

Building a static and portable (musl) binary — architecture: x86_64. Fully static, no dynamic interpreter at all: runs unmodified on both NixOS and any standard Linux distribution:

nix build .#tpnote-x86_64-unknown-linux-musl

Building for Windows — architecture: x86_64:

nix build .#tpnote-x86_64-pc-windows-gnu

To also package the binary as a Windows installer (.msi), use scripts/18-make-win-msi-package.nu, which builds the binary above and then packages it via the wix/ flake’s dev shell (WiX Toolset running under Wine). Unlike the nix build commands above, this does not produce ./result; it writes the finished installer to build/tpnote-<version>-x64.msi:

nu scripts/18-make-win-msi-package.nu

The nix build commands above put their binaries in the Nix store, symlinked as ./result. Copy them to your desired location:

cp result/bin/tpnote* /path/to/destination

This project follows Semantic Versioning.

6 About

Author:

• Jens Getreu

Copyright:

• Apache 2 license or MIT license.