# Tp-Note: Markup enhanced granular note-taking

**Save and edit your clipboard content as a note file**

[![Cargo](https://img.shields.io/crates/v/tpnote.svg)](https://crates.io/crates/tp-note)
[![Documentation](https://docs.rs/tpnote-lib/badge.svg)](https://docs.rs/tpnote-lib)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](https://gitlab.com/getreu/tp-note)

# 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.

![Screenshot](./assets/tpnote-screenshot.png)

A more sophisticated example using the “Zettelkasten” scheme:

![Screenshot-Zettelkasten](./assets/tpnote-screenshot-zettelkasten.png)

## 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.

## Usage Examples

| Action                       | Command Example                                  |
| ---------------------------- | ------------------------------------------------ |
| Create a note from clipboard    | `tpnote` (when clipboard contains text)          |
| Convert HTML to Markdown        | `curl https://example.com` \| `tpnote`           |
| View a plain Markdown file      | `tpnote --view myfile.md`                        |
| Edit a plain Markdown file      | `tpnote myfile.md`                               |
| Convert plain Markdown to Tp-Note | `tpnote --add-header myfile.md`                |
| Edit an existing Tp-Note file   | `tpnote ./path/to/note.md`                       |
| Generate PDF from a note        | `tpnote -x - note.md` \| `weasyprint - note.pdf` |

## 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].

---

# 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.

# Source code

Repository:

- [Tp-Note on Gitlab]

- [Tp-Note on Github (mirror)]

## Distribution

### 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][Releases - getreu/tp-note]

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.26.5`):

| Asset | Platform / use |
| ----- | -------------- |
| `tpnote-<version>-x64.msi` | **Windows installer** (recommended on Windows) |
| `tpnote_<version>_amd64.deb` | **Debian / Ubuntu installer** (x86-64) |
| `tpnote-<version>-x86_64-unknown-linux-gnu.tar.gz` | Linux x86-64 (glibc), standalone binary |
| `tpnote-<version>-x86_64-unknown-linux-musl.tar.gz` | Linux x86-64, static (musl) — headless/console/servers |
| `tpnote-<version>-aarch64-unknown-linux-gnu.tar.gz` | Linux ARM64 / Raspberry Pi 64-bit |
| `tpnote-<version>-armv7-unknown-linux-gnueabihf.tar.gz` | Linux ARMv7 / Raspberry Pi 32-bit |
| `tpnote-<version>-x86_64-pc-windows-gnu.zip` | Windows x86-64, standalone binary |
| `tpnote-<version>-x86_64-apple-darwin.tar.gz` | macOS (Intel) |
| `tpnote-<version>-aarch64-apple-darwin.tar.gz` | macOS (Apple Silicon) |
| `tpnote-<version>-docs.tar.gz` | User manual and man page (HTML, PDF, man) |
| `tpnote-<version>-winget-manifests.tar.gz` | winget manifests (Windows Package Manager) |

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

### 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.

### Tp-Note Debian/Ubuntu installer package

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

```sh
sudo dpkg -i tpnote_<version>_amd64.deb
```

### 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](#installation) section below).

## Tp-Note in official package repositories

### Windows Package Manager (winget) Distribution

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

```powershell
winget install getreu.tpnote
```

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

### Tp-Note on NetBSD

- An official package is available on NetBSD and other "pkgsrc" supported
  platforms.

  To install Tp-Note on NetBSD, simply use the native package manager:

  ```sh
  pkgin install tpnote
  ```

### Tp-Note on NixOS

- An official package is available on NixOS:

  ```nix
  environment.systemPackages = [ pkgs.tpnote ];
  ```

### Get Tp-Note with the Nix package manager

- First install the [Nix package manager](https://nixos.org/download)
  available for Linux, MacOS and Windows (WSL2).
  Alternatively, for Linux there are also [prebuilt Deb/Pacman/Rpm
  Nix installers](https://nix-community.github.io/nix-installers/)
  available.

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

  ```nix
  nix-shell -p tpnote
  ```

  or follow installation instructions here:
  [NixOS packages - tpnote](https://search.nixos.org/packages?channel=unstable&show=tpnote&from=0&size=50&sort=relevance&type=packages&query=tpnote)

## 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]

# 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](#distribution) above and the
[Installation section] in _Tp-Note_'s manual.

## Upgrading

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
```

Mote, 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).

# 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**

    ```sh
    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).[^no-message-box]

    [^no-message-box]:
        In case an XDG desktop environment is not available, you
        can opt out notifications and message boxes by omitting the `message-box`
        feature by adding
        `--no-default-features --features lang-detection,read-clipboard,renderer,viewer`
        to `cargo install tpnote`.
        Now, all error messages are dumped on the console from
        where you started _Tp-Note_ into `stderr`.

    **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:

    ```sh
    cargo install --no-default-features \
      --features lang-detection,renderer 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[^win] with:

        cargo install tpnote

    [^win]:
        When building for Windows or macOS, it does not make sense to exclude
        the `message-box` feature, because - under Windows and macOS - it does not
        rely on the notification library. Instead, it uses direct OS-API calls for
        popping up alert boxes. As these calls have no footprint in binary size or
        speed, always keep the `message-box` feature compiled in.

## Cross compilation

Tp-Note supports cross-compilation for multiple architectures. This section
explains how to build binaries that work on Debian/Ubuntu systems, including
Raspberry Pi devices.

### Building for Debian/Ubuntu (Recommended)

The project includes pre-configured cross-compilation settings in
`.cargo/config.toml`. To build Debian/Ubuntu-compatible binaries, you only
need to install the cross-compiler toolchains:

**Prerequisites:**

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

**Build for Raspberry Pi 32-bit (ARMv7):**

```sh
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):**

```sh
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 from NixOS

Tp-Note can also be cross-compiled from NixOS using the Nix flake. The ARM
builds produce binaries compatible with Debian 11+ and Ubuntu 20.04+:

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

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

The binaries will be in the Nix store. Copy them to your desired location:

```sh
cp result/bin/tpnote /path/to/destination
```

### Building for Musl Linux (Static)

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

```sh
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

```sh
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
```

### Verifying Binary Compatibility

After building, verify that your binary links against the correct libraries:

```sh
# Check dynamic dependencies (should show glibc, not Nix store paths)
readelf -d target/armv7-unknown-linux-gnueabihf/release/tpnote | grep NEEDED

# Check the dynamic linker (should point to Debian/Ubuntu paths)
readelf -d target/armv7-unknown-linux-gnueabihf/release/tpnote | grep interpreter
```

The binary should NOT contain any `/nix/store` paths. If it does, the build
environment may have introduced Nix-specific dependencies.

This project follows [Semantic Versioning].

# About

Author:

- Jens Getreu

Copyright:

- Apache 2 license or MIT license.

[Tp-Note’s user manual]: https://blog.getreu.net/projects/tp-note/tpnote--manual.html
[Download Tp-Note]: https://blog.getreu.net/projects/tp-note/index.html#distribution
[Tp-Note - Minimalistic note-taking]: https://blog.getreu.net/projects/tp-note/
[Tp-Note - Most common use cases - YouTube]: https://www.youtube.com/watch?v=ODhPytPFtYY
[Tp-Note's project page]: https://blog.getreu.net/projects/tp-note/
[Tp-Note user manual - html]: https://blog.getreu.net/projects/tp-note/tpnote--manual.html
[Tp-Note user manual - pdf]: https://blog.getreu.net/_downloads/tpnote--manual.pdf
[Tp-Note manual page - html]: https://blog.getreu.net/projects/tp-note/tpnote--manpage.html
[Tp-Note manual page - pdf]: https://blog.getreu.net/_downloads/tpnote--manpage.pdf
[Blogposts about Tp-Note]: https://blog.getreu.net/tags/tp-note/
[Tp-Note's config module documentation]: https://docs.rs/tpnote-lib/latest/tpnote_lib/config/
[tpnote]: https://crates.io/crates/tpnote
[tpnote-lib]: https://crates.io/crates/tpnote-lib
[constants in the API documentation]: https://docs.rs/tpnote-lib/latest/tpnote_lib/config/index.html#constants
[Tp-Note on Gitlab]: https://gitlab.com/getreu/tp-note
[Tp-Note on Github (mirror)]: https://github.com/getreu/tp-note
[VirusTotal]: https://www.virustotal.com/gui/home/upload
[Releases - getreu/tp-note]: https://github.com/getreu/tp-note/releases
[latest release]: https://github.com/getreu/tp-note/releases/latest
[tpnote.svg]: https://blog.getreu.net/projects/tp-note/assets/tpnote.svg
[Installation section]: https://blog.getreu.net/projects/tp-note/tpnote--manual.html#installation
[Customization section]: https://blog.getreu.net/projects/tp-note/tpnote--manpage.html#customization
[Install Rust]: https://www.rust-lang.org/tools/install
[Semantic Versioning]: https://semver.org/
