amfora/README.md

170 lines
6.8 KiB
Markdown
Raw Normal View History

2020-06-18 23:54:48 +03:00
# Amfora
2020-06-19 02:13:40 +03:00
<img src="logo.png" alt="amphora logo" width="30%">
2020-06-24 20:39:49 +03:00
<h6>Image modified from: amphora by Alvaro Cabrera from the Noun Project</h6>
2020-06-19 02:10:45 +03:00
2020-06-19 00:23:54 +03:00
[![go reportcard](https://goreportcard.com/badge/github.com/makeworld-the-better-one/amfora)](https://goreportcard.com/report/github.com/makeworld-the-better-one/amfora)
[![license GPLv3](https://img.shields.io/github/license/makeworld-the-better-one/amfora)](https://www.gnu.org/licenses/gpl-3.0.en.html)
2020-06-19 02:13:40 +03:00
<a href="https://raw.githubusercontent.com/makeworld-the-better-one/amfora/master/demo-large.gif">
2020-06-19 02:10:45 +03:00
<img src="demo-large.gif" alt="Demo GIF" width="80%">
2020-06-19 02:13:40 +03:00
</a>
2020-06-19 02:10:45 +03:00
###### Recording of v1.0.0
2021-11-01 19:11:52 +03:00
Amfora aims to be the best looking [Gemini](https://geminiquickst.art/) client with the most features... all in the terminal. It does not support Gopher or other non-Web protocols - check out [Bombadillo](http://bombadillo.colorfield.space/) for that.
2020-06-19 00:23:54 +03:00
It also aims to be completely cross platform, with full Windows support. If you're on Windows, I would not recommend using the default terminal software. Use [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701) instead, and make sure it [works with UTF-8](https://akr.am/blog/posts/using-utf-8-in-the-windows-terminal). Note that some of the application colors might not display correctly on Windows, but all functionality will still work.
2020-06-18 23:54:48 +03:00
2020-12-15 22:35:43 +03:00
It fully passes Sean Conman's client torture test, as well as the Egsam one.
2020-06-18 23:54:48 +03:00
2020-06-19 02:25:08 +03:00
## Installation
### Binary
2020-12-15 22:35:43 +03:00
Download a binary from the [releases](https://github.com/makeworld-the-better-one/amfora/releases) page. On Unix-based systems you will have to make the file executable with `chmod +x <filename>`. You can rename the file to just `amfora` for easy access, and move it to `/usr/local/bin/`.
2020-06-27 23:41:13 +03:00
On Windows, make sure you click "Advanced > Run anyway" after double-clicking, or something like that.
Unix systems can install the desktop entry file to get Amfora to appear when they search for applications:
```bash
curl -sSL https://raw.githubusercontent.com/makeworld-the-better-one/amfora/master/amfora.desktop -o ~/.local/share/applications/amfora.desktop
update-desktop-database ~/.local/share/applications
```
2020-06-19 02:25:08 +03:00
2020-12-15 22:35:43 +03:00
Make sure to click "Watch" in the top right, then "Custom" > "Releases" to get notified about new releases!
2021-05-01 19:45:21 +03:00
### Linux
<a href="https://repology.org/project/amfora/versions">
<img src="https://repology.org/badge/vertical-allrepos/amfora.svg" alt="Packaging status" align="right">
</a>
2021-04-07 01:07:25 +03:00
Amfora is packaged in many Linux distros. It's also on [Scoop](https://scoop.sh/) for Windows users.
### macOS (Homebrew)
2020-08-04 18:14:32 +03:00
If you use [Homebrew](https://brew.sh/), you can install Amfora with:
2020-08-04 18:14:32 +03:00
```
2020-09-15 20:54:32 +03:00
brew install amfora
2020-08-04 18:14:32 +03:00
```
You can update it with:
```
brew upgrade amfora
```
### macOS (MacPorts)
On macOS, Amfora can also be installed through [MacPorts](https://www.macports.org):
```
sudo port install amfora
```
You can update it with:
```
sudo port selfupdate
sudo port upgrade amfora
```
**NOTE:** this installation source is community-maintained. More information [here](https://ports.macports.org/port/amfora/).
2021-05-01 19:45:21 +03:00
### Termux
2021-04-07 00:52:28 +03:00
If you're using [Termux](https://termux.com/) on Android you can't just run Amfora like normal. After installing Amfora, run `pkg install proot`. Then run `termux-chroot` before running the Amfora binary. You can exit out of the chroot after closing Amfora. See [here](https://stackoverflow.com/q/38959067/7361270) for why this is needed.
### From Source
2020-12-01 18:52:06 +03:00
2020-12-15 22:35:43 +03:00
This section is for advanced users who want to install the latest (possibly unstable) version of Amfora.
2020-12-01 18:52:06 +03:00
<details>
<summary>Click to expand</summary>
2020-09-21 00:33:45 +03:00
**Requirements:**
- Go 1.15 or later
2020-09-21 00:33:45 +03:00
- GNU Make
2020-09-21 00:33:45 +03:00
Please note the Makefile does not intend to support Windows, and so there may be issues.
2020-09-02 20:02:40 +03:00
```shell
2020-09-02 18:05:14 +03:00
git clone https://github.com/makeworld-the-better-one/amfora
cd amfora
2020-09-02 21:06:38 +03:00
# git checkout v1.2.3 # Optionally pin to a specific version instead of the latest commit
2020-09-21 00:33:45 +03:00
make # Might be gmake on macOS
sudo make install # If you want to install the binary for all users
```
2020-09-02 18:05:14 +03:00
Because you installed with the Makefile, running `amfora -v` will tell you exactly what commit the binary was built from.
Arch Linux users can also install the latest commit of Amfora from the AUR. It has the package name `amfora-git`, and is maintained by @lovetocode999
```
yay -S amfora-git
```
2020-09-21 00:33:45 +03:00
MacOS users can also use [Homebrew](https://brew.sh/) to install the latest commit of Amfora:
```
brew install --HEAD amfora
```
You can update it with:
```
brew upgrade --fetch-HEAD amfora
```
2020-12-01 18:52:06 +03:00
</details>
2020-06-18 23:54:48 +03:00
## Features / Roadmap
2020-06-21 00:17:34 +03:00
Features in *italics* are in the master branch, but not in the latest release.
2020-06-18 23:54:48 +03:00
- [x] URL browsing with TOFU and error handling
- [x] Tabbed browsing
- [x] Support ANSI color codes on pages, even for Windows
- [x] Styled page content (headings, links)
- [x] Basic forward/backward history, for each tab
- [x] Input (Status Code 10 & 11)
2020-06-24 20:39:49 +03:00
- [x] Multiple charset support (over 55)
- [x] Built-in search (uses geminispace.info by default)
2020-06-24 20:39:49 +03:00
- [x] Bookmarks
- [x] Download pages and arbitrary data
2020-07-29 03:18:38 +03:00
- [x] Theming
2020-11-19 08:34:02 +03:00
- Check out the [user contributed themes](https://github.com/makeworld-the-better-one/amfora/tree/master/contrib/themes)!
2020-09-02 02:55:06 +03:00
- [x] Proxying
2020-09-01 21:55:52 +03:00
- Schemes like Gopher or HTTP can be proxied through a Gemini server
2020-11-05 05:31:08 +03:00
- [x] Client certificate support
- [ ] Full client certificate UX within the client
- Create transient and permanent certs within the client, per domain
- Manage and browse them
- Similar to [Kristall](https://github.com/MasterQ32/kristall)
- https://lists.orbitalfox.eu/archives/gemini/2020/001400.html
2020-12-21 01:26:39 +03:00
- [x] Subscriptions
2020-12-07 23:18:47 +03:00
- Subscribing to RSS, Atom, and [JSON Feeds](https://jsonfeed.org/) are all supported
- So is subscribing to a page, to know when it changes
2021-02-17 23:37:36 +03:00
- [x] Open non-text files in another application
2021-02-17 23:31:06 +03:00
- [x] Ability to stream content instead of downloading it first
2020-07-01 20:39:13 +03:00
- [ ] Stream support
- [ ] Table of contents for pages
- [ ] Search in pages with <kbd>Ctrl-F</kbd>
2020-12-01 18:52:06 +03:00
- [ ] Persistent history
2020-06-18 23:54:48 +03:00
2020-12-01 18:52:06 +03:00
## Usage & Configuration
Please see [the wiki](https://github.com/makeworld-the-better-one/amfora/wiki) for an introduction on how to use Amfora and configure it.
2020-11-05 06:18:43 +03:00
2020-06-18 23:54:48 +03:00
## Libraries
Amfora ❤️ open source!
2021-04-07 19:52:22 +03:00
- [cview](https://code.rocketnine.space/tslocum/cview) for the TUI
2020-06-18 23:54:48 +03:00
- It's a fork of [tview](https://github.com/rivo/tview) with PRs merged and active support
- It uses [tcell](https://github.com/gdamore/tcell) for low level terminal operations
- [Viper](https://github.com/spf13/viper) for configuration and TOFU storing
- [go-gemini](https://github.com/makeworld-the-better-one/go-gemini), my forked and updated Gemini client/server library
- [progressbar](https://github.com/schollz/progressbar)
2020-07-11 03:05:34 +03:00
- [go-humanize](https://github.com/dustin/go-humanize)
- [gofeed](https://github.com/mmcdole/gofeed)
2021-12-08 05:31:57 +03:00
- [clipboard](https://github.com/atotto/clipboard)
- [termenv](https://github.com/muesli/termenv)
2020-06-18 23:54:48 +03:00
## License
This project is licensed under the GPL v3.0. See the [LICENSE](./LICENSE) file for details.