Skip to content

Refactor README formatting and content #377

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SakuraMathcraft merged 2 commits into from
Sep 21, 2026
Merged

Refactor README formatting and content #377

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c11dbb1
Refactor README formatting and content
SakuraMathcraft Sep 21, 2026
d8e27af
Merge branch 'main' into SakuraMathcraft-patch-1
SakuraMathcraft Sep 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 71 additions & 42 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# LaTeXSnipper ✨

<div align="center">

Turn screenshots, images, PDFs, and handwriting into editable formulas and text.
# LaTeXSnipper ✨

**Turn screenshots, images, PDFs, and handwriting into editable formulas and text.**

[![GitHub Release](https://img.shields.io/github/v/release/SakuraMathcraft/LaTeXSnipper?style=flat-square)](https://github.com/SakuraMathcraft/LaTeXSnipper/releases/latest)
![Stars](https://img.shields.io/github/stars/SakuraMathcraft/LaTeXSnipper?style=flat-square&label=Stars&color=FFD700)
[![GitHub Release](https://img.shields.io/github/v/release/SakuraMathcraft/LaTeXSnipper?style=flat-square\&label=Release)](https://github.com/SakuraMathcraft/LaTeXSnipper/releases/latest)
[![GitHub Stars](https://img.shields.io/github/stars/SakuraMathcraft/LaTeXSnipper?style=flat-square\&label=Stars\&color=FFD700)](https://github.com/SakuraMathcraft/LaTeXSnipper/stargazers)
[![GitHub Downloads](https://img.shields.io/github/downloads/SakuraMathcraft/LaTeXSnipper/total?style=flat-square\&label=Downloads)](https://github.com/SakuraMathcraft/LaTeXSnipper/releases)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-orange?style=flat-square)
![License](https://img.shields.io/badge/license-GPLv3-blue?style=flat-square)
[![License](https://img.shields.io/badge/license-GPLv3-blue?style=flat-square)](LICENSE)

**[Download](https://github.com/SakuraMathcraft/LaTeXSnipper/releases/latest)** · [User Manual (Chinese)](user_manual/user_manual.md) · [FAQ](docs/faq.md) · [Demos](#demos)

Expand All @@ -17,34 +18,45 @@ English · [简体中文](README.zh-CN.md)

</div>

---

## What You Can Do

| Feature | What it offers |
|---|---|
| 📸 Recognize | Capture a region, open an image, select PDF pages, or write by hand; recognize formulas, text, and mixed content |
| ⌨️ Edit and compute | Edit with MathLive and live preview; simplify, evaluate, and solve in the math workspace |
| 🔄 Export | Copy formulas or export documents in 20 formats, including LaTeX, MathML, Word, PDF, and Typst |
| 🧩 Integrate | Work in Word/PowerPoint or connect scripts and other tools through the Automation API |
| 🧠 Choose your model | Run MathCraft OCR locally after downloading dependencies and weights, or configure a local/online external model |
| 🎨 Make it yours | English/Chinese interface, light/dark themes, configurable shortcuts, history, and favorites |
| Feature | What it offers |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| 📸 **Recognize** | Capture a region, open an image, select PDF pages, or write by hand; recognize formulas, text, and mixed content |
| ⌨️ **Edit and compute** | Edit with MathLive and live preview; simplify, evaluate, and solve in the math workspace |
| 🔄 **Export** | Copy formulas or export documents in 20 formats, including LaTeX, MathML, Word, PDF, and Typst |
| 🧩 **Integrate** | Work in Word/PowerPoint or connect scripts and other tools through the Automation API |
| 🧠 **Choose your model** | Run MathCraft OCR locally after downloading dependencies and weights, or configure a local/online external model |
| 🎨 **Make it yours** | English/Chinese interface, light/dark themes, configurable shortcuts, history, and favorites |

**MathCraft OCR:** [benchmark results](https://github.com/SakuraMathcraft/MathCraft-Models/tree/main/benchmarks) · [reproduce the benchmarks](benchmarks/mathcraft_ocr/README.md)

MathCraft OCR: [benchmark results](https://github.com/SakuraMathcraft/MathCraft-Models/tree/main/benchmarks) · [reproduce the benchmarks](benchmarks/mathcraft_ocr/README.md)
---

## Download and Get Started

1. **Install the desktop app.** Choose the package for your system from [Releases](https://github.com/SakuraMathcraft/LaTeXSnipper/releases/latest).
2. **Prepare recognition.** On first launch, use Dependency Management to install the required layers and a CPU or GPU backend for MathCraft OCR. Initial model setup requires downloading weights. If using only an external model, configure and test its connection in Settings instead.
2. **Prepare recognition.** Install the recognition environment required by the model you want to use.
3. **Recognize and edit.** Use Capture Recognize, Image, PDF, or Handwriting, then review, copy, or export the result.

| Platform | Download | Before using recognition |
|---|---|---|
| Windows | `LaTeXSnipperSetup-<version>.exe` | Python runtime included; no separate system Python installation needed |
| Linux (Debian/Ubuntu) | `.deb` for your architecture | Python `>=3.10,<3.14` with venv/pip; Wayland may restrict screenshots and global shortcuts |
| macOS | `.dmg` or `.app.zip` for your architecture | Python `>=3.10,<3.14` with venv/pip; grant Screen Recording permission for screenshots |
> [!IMPORTANT]
> On first launch, use **Dependency Management** to install the required layers and a CPU or GPU backend for MathCraft OCR. Initial model setup requires downloading weights. If using only an external model, configure and test its connection in **Settings** instead.

| Platform | Download | Before using recognition |
| ------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Windows** | `LaTeXSnipperSetup-<version>.exe` | Python runtime included; no separate system Python installation needed |
| **Linux (Debian/Ubuntu)** | `.deb` for your architecture | Python `>=3.10,<3.14` with venv/pip; Wayland may restrict screenshots and global shortcuts |
| **macOS** | `.dmg` or `.app.zip` for your architecture | Python `>=3.10,<3.14` with venv/pip; grant Screen Recording permission for screenshots |

> [!NOTE]
> Linux/macOS use system Python to create the managed dependency environment; Windows uses its bundled Python 3.11 template. The `.deb` declares `python3` and `python3-venv` dependencies. On macOS, install a supported Python version if one is not available.

Linux/macOS use system Python to create the managed dependency environment; Windows uses its bundled Python 3.11 template. The `.deb` declares `python3` and `python3-venv` dependencies. On macOS, install a supported Python version if one is not available.
> [!TIP]
> For permissions, model downloads, environment paths, and troubleshooting, see the [FAQ](docs/faq.md), [user data locations](docs/user_data_storage.md), and [full user manual (Chinese)](user_manual/user_manual.md).

For permissions, model downloads, environment paths, and troubleshooting, see the [FAQ](docs/faq.md), [user data locations](docs/user_data_storage.md), and [full user manual (Chinese)](user_manual/user_manual.md).
---

## Demos

Expand All @@ -60,54 +72,71 @@ For permissions, model downloads, environment paths, and troubleshooting, see th

![PDF recognition demo](docs/demos/pdf-recognition.gif)

---

## Microsoft Office Plugin

Insert and edit formulas directly in Windows desktop Word and PowerPoint:
> [!NOTE]
> The Office plugin is designed for **Windows desktop Microsoft Word and PowerPoint**, where you can insert and edit formulas directly.

- Word OLE/OMML and PowerPoint OLE/PNG insertion, with editable LaTeX source.
- Formula editing, updates, and Word automatic numbering and references.
- Local formula rendering and screenshot OCR through the desktop Automation API.
* Word OLE/OMML and PowerPoint OLE/PNG insertion, with editable LaTeX source.
* Formula editing, updates, and Word automatic numbering and references.
* Local formula rendering and screenshot OCR through the desktop Automation API.

Download `OfficePluginSetup-<version>.exe` separately from [Releases](https://github.com/SakuraMathcraft/LaTeXSnipper/releases/latest). Supports 32-bit and 64-bit Office 2019/2021/2024, LTSC 2021/2024, and Microsoft 365 Apps on Windows.

[Installation requirements and features](office_plugin/README.md) · [Formula workflows](docs/office_plugin_formula_workflows.md)

---

## Automation API

Use MathCraft or your configured external model from scripts, batch jobs, editor integrations, or authorized remote devices.

- **Desktop shortcuts:** connect Snipaste, AutoHotkey, AutoKey, Hammerspoon, or ShareX to an image-recognition workflow.
- **Batch and editor workflows:** submit images with Python/curl and insert results into your tools.
- **Mobile access:** connect Shortcuts or Tasker to your running desktop app through a secure tunnel.
* **Desktop shortcuts:** connect Snipaste, AutoHotkey, AutoKey, Hammerspoon, or ShareX to an image-recognition workflow.
* **Batch and editor workflows:** submit images with Python/curl and insert results into your tools.
* **Mobile access:** connect Shortcuts or Tasker to your running desktop app through a secure tunnel.

The API is **disabled by default**. Local clients use the address and token in `automation-api.json`. Remote access requires explicit opt-in, a separate key, and HTTPS or an encrypted tunnel; do not expose it over plain public HTTP. Remote external-model access is separately controlled and may incur provider charges.
> [!CAUTION]
> The API is **disabled by default**. Local clients use the address and token in `automation-api.json`. Remote access requires explicit opt-in, a separate key, and HTTPS or an encrypted tunnel; **do not expose it over plain public HTTP**. Remote external-model access is separately controlled and may incur provider charges.

[API reference and connection setup](docs/automation_api.md) · [Ready-to-adapt client examples](examples/automation/)

---

## Export

Built-in exports cover LaTeX, Markdown math, MathML, HTML, Word OMML, and SVG code. Install the optional **Pandoc** layer in Dependency Management for document exports such as Word, PowerPoint, EPUB, PDF, and Typst. PDF export also requires a LaTeX PDF engine.
Built-in exports cover **LaTeX, Markdown math, MathML, HTML, Word OMML, and SVG code**.

> [!NOTE]
> Install the optional **Pandoc** layer in Dependency Management for document exports such as Word, PowerPoint, EPUB, PDF, and Typst. PDF export also requires a LaTeX PDF engine.

See the [user manual](user_manual/user_manual.md) for the full format list and requirements.

---

## Supporters

Thanks to everyone who helps with development, testing, documentation, and community support.

| Supporter | Contribution |
|---|---|
| [strangelion](https://github.com/strangelion) | Contributor |
| [Galileo927](https://github.com/Galileo927) | Contributor |
| [ljygo](https://github.com/ljygo) | Sponsor |
| [Yokie-D](https://github.com/Yokie-D) | Sponsor |
| Supporter | Contribution |
| --------------------------------------------- | ------------ |
| [strangelion](https://github.com/strangelion) | Contributor |
| [Galileo927](https://github.com/Galileo927) | Contributor |
| [ljygo](https://github.com/ljygo) | Sponsor |
| [Yokie-D](https://github.com/Yokie-D) | Sponsor |

---

## Support the Project

LaTeXSnipper is a free, open-source, ad-free personal project with no in-app purchases. If it helps your work, consider starring the repository, sharing it, [reporting an issue](https://github.com/SakuraMathcraft/LaTeXSnipper/issues), or sponsoring maintenance.
LaTeXSnipper is a **free, open-source, ad-free personal project with no in-app purchases**. If it helps your work, consider starring the repository, sharing it, [reporting an issue](https://github.com/SakuraMathcraft/LaTeXSnipper/issues), or sponsoring maintenance.

| Alipay | WeChat Pay | Community chat (Chinese) |
| :-------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------: |
| <img width="300" alt="Alipay donation QR code" src="https://github.com/user-attachments/assets/1efa46b7-07cb-4a3e-821d-f23b7a36ab34" /> | <img width="300" alt="WeChat Pay donation QR code" src="https://github.com/user-attachments/assets/19065b1d-ac40-478e-8318-fabb75488c5c" /> | <img width="300" alt="LaTeXSnipper community chat QR code" src="https://github.com/user-attachments/assets/bd034db2-e828-47d8-a38a-7f1845b7ca8f" /> |

| Alipay | WeChat Pay | Community chat (Chinese) |
|:---:|:---:|:---:|
| <img width="300" alt="Alipay donation QR code" src="https://github.com/user-attachments/assets/1efa46b7-07cb-4a3e-821d-f23b7a36ab34" /> | <img width="300" alt="WeChat Pay donation QR code" src="https://github.com/user-attachments/assets/19065b1d-ac40-478e-8318-fabb75488c5c" /> | <img width="300" alt="LaTeXSnipper community chat QR code" src="https://github.com/user-attachments/assets/91c30d59-a4a7-4118-b24b-dada0fe002bf" /> |
---

## License

Expand Down