nReceipts

by NlckySolutions

A cute little receipt studio for Linux. The receipt on your screen is the editor — type on it, style it with Markdown (emoji too), hit the big red button, and it comes out of your USB thermal printer.

Works with generic 58mm ESC/POS printers (Sunydog, NETUM, MUNBYN, Goojprt, Rongta, and most other USB thermal receipt printers under $30).

Install

git clone https://github.com/nlckysolutions/nReceipts.git
cd nReceipts
bash setup.sh

That's it. nReceipts (by NlckySolutions) appears in your app menu (Office / Utilities), no root needed except one optional step the installer will offer to do for you (a udev rule so your printer works without sudo).

Use

• Just type on the receipt. It grows as you write, and shrinks back down — a one-word receipt prints as a one-word receipt, not a foot of blank paper.

• Markdown works live, right on the paper:

  You type	You get
  # Title	big centered heading
  ## Subtitle	medium centered heading
  ### Section	bold line
  **bold** *ital*	inline styles
  `code`	highlighted text
  - item	bullet list
  > words	quote
  ---	dashed divider
  🎉 ☕ 🔥	emoji (printed as tiny images)

• The 😀 button opens a quick emoji picker. The ⚙ button opens paper settings — side margin and feed-before-tear, so you control how much blank paper it uses.

• Open .md loads any Markdown file onto the paper. Save writes it back.

• The pill in the top-right shows your printer's connection status. Click it any time for the connection helper.

• The big red button prints. Ctrl+P also prints. Ctrl+O opens, Ctrl+S saves, Ctrl+N starts a fresh receipt.

Printer not found?

Click the status pill for a friendly walkthrough with a live "Scan for printers" button:

The short version:

1. Plug in via USB and power the printer on.

2. Click the status pill → Scan for printers.

3. Still nothing? Give yourself USB permission (one time):

   bash setup.sh --udev
   sudo usermod -aG lp,dialout $USER   # then log out & back in

4. Bluetooth-only mode won't show up — connect the USB cable.

Right-click printing, everywhere

setup.sh also offers to wire up:

Files (Nemo right-click) — right-click any image, PDF, or text/.md file → Print via nReceipts. Images print as a dithered bitmap, PDFs print their real text if there is any (falling back to a page-image if the PDF is scanned), and text/Markdown files print through the normal Markdown pipeline.

Highlighted text, in any app — Linux has no universal "add this to every app's right-click menu" hook, so instead you get a keyboard shortcut (you choose the combo during setup, e.g. Super+Shift+P): highlight text anywhere — a PDF viewer, a terminal, LibreOffice, Firefox, anywhere — press the shortcut, and it prints.

Firefox — a real right-click menu, via a small extension:

• Right-click selected text → Print "..." via nReceipts
• Right-click an image → Print image via nReceipts
• Right-click a link to a .pdf → Print PDF via nReceipts

The extension talks to nReceipts through Firefox's native messaging, which setup.sh registers for you automatically.

Installing the Firefox extension

The extension source lives in firefox-extension/ (also copied to ~/.local/share/nreceipts/firefox-extension/ by setup.sh). Firefox requires extensions to be signed by Mozilla to load permanently, so pick one of these:

1. Quickest (temporary): about:debugging#/runtime/this-firefox → Load Temporary Add-on → pick manifest.json. Works immediately, but resets when Firefox restarts.
2. Firefox Nightly, Developer Edition, or ESR: set xpinstall.signatures.required to false in about:config, then install the extension permanently — regular release Firefox ignores this setting.
3. Self-sign (permanent, works in normal Firefox): get a free API key at https://addons.mozilla.org/developers/addon/api/key/, then:

   cd firefox-extension
   npx web-ext sign --api-key=YOUR_KEY --api-secret=YOUR_SECRET --channel=unlisted

   Install the signed .xpi it produces from about:addons.

How it works

• nreceipts/mdlite.py — a tiny Markdown parser tuned for a 32-char receipt strip.
• nreceipts/receipt.py — the on-screen paper widget: a Canvas for the torn-edge paper shape, a Text widget on top as the editor, with live Markdown styling as you type.
• nreceipts/printerlink.py — finds USB printer-class devices and drives them via python-escpos. Emoji get rendered to small bitmaps (thermal printers can't render emoji glyphs natively) and sent as raster images; everything else prints as fast native text.
• nreceipts/fileprint.py — the "print this file" layer used by Nemo actions and the Firefox extension: images, PDFs (text-extracted via pdftotext, or rasterized via pdftoppm as a fallback for scanned PDFs), and plain text.
• nreceipts/settings.py — the two paper preferences (margin, feed), persisted to ~/.config/nreceipts/settings.json.

Uninstall

bash uninstall.sh

Contributing

Issues and PRs welcome — this started as "I want a cute receipt printer app" and grew from there. If your printer doesn't work, open an issue with what happened; the ESC/POS clone market is a wild west and I'd like to make this work with as many of them as possible.

License

See LICENSE.

---

Made with ❤ and a 1500 mAh battery.