glow/README.md

216 lines
6 KiB
Markdown
Raw Normal View History

2019-12-20 21:47:47 +00:00
# Glow
2019-11-09 22:12:54 +00:00
Render markdown on the CLI, with _pizzazz_!
2020-03-05 03:36:08 +00:00
<p align="center">
<img src="https://stuff.charm.sh/glow-github.gif" alt="Glow Logo">
<a href="https://github.com/charmbracelet/glow/releases"><img src="https://img.shields.io/github/release/charmbracelet/glow.svg" alt="Latest Release"></a>
<a href="https://pkg.go.dev/github.com/charmbracelet/glow?tab=doc"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc"></a>
<a href="https://github.com/charmbracelet/glow/actions"><img src="https://github.com/charmbracelet/glow/workflows/build/badge.svg" alt="Build Status"></a>
2020-05-05 05:51:26 +00:00
<a href="http://goreportcard.com/report/github.com/charmbracelet/glow"><img src="http://goreportcard.com/badge/charmbracelet/glow" alt="Go ReportCard"></a>
2020-03-05 03:36:08 +00:00
</p>
2020-07-29 17:21:56 +00:00
<p align="center">
<img src="https://stuff.charm.sh/glow2-ui-github.gif" width="600" alt="Glow UI Demo">
</p>
2020-07-29 16:49:36 +00:00
## What is it?
Glow is a terminal based markdown reader designed from the ground up to bring
2020-07-29 17:21:56 +00:00
out the beauty—and power—of the CLI.
2020-07-29 16:49:36 +00:00
Use it to discover markdown files, read documentation directly on the command
line and stash markdown files to your own private collection so you can read
2020-08-27 17:36:08 +00:00
them anywhere. Glow will find local markdown files in subdirectories or a local
Git repository.
By the way, all data stashed is encrypted end-to-end: only you can decrypt it.
More on that below.
2019-12-19 02:36:30 +00:00
2019-12-16 11:04:55 +00:00
## Installation
2019-12-19 02:36:30 +00:00
Use your fave package manager:
```bash
# macOS or Linux
2020-01-12 15:54:36 +00:00
brew install glow
# macOS (with MacPorts)
sudo port install glow
2019-12-19 02:36:30 +00:00
# Arch Linux (btw)
2019-12-20 21:47:47 +00:00
yay -S glow
2019-12-23 19:44:56 +00:00
# Void Linux
xbps-install -S glow
# Nix
nix-env -iA nixpkgs.glow
2019-12-23 19:44:56 +00:00
# FreeBSD
pkg install glow
# Solus
eopkg install glow
# Windows (with Scoop)
scoop install glow
2019-12-19 02:36:30 +00:00
```
Or download a binary from the [releases][releases] page. MacOS, Linux, Windows,
FreeBSD, and OpenBSD binaries are available, as well as Debian, RPM, and Alpine
2020-10-14 02:57:57 +00:00
packages. ARM builds are also available for Linux, FreeBSD, and OpenBSD.
2019-12-22 01:37:01 +00:00
2020-10-17 12:30:03 +00:00
Or just build it yourself (requires Go 1.13+):
2019-12-19 02:36:30 +00:00
```bash
2020-10-17 12:30:03 +00:00
git clone https://github.com/charmbracelet/glow.git
cd glow
go build
2019-12-16 17:52:10 +00:00
```
2019-12-16 11:04:55 +00:00
2019-12-22 01:37:01 +00:00
[releases]: https://github.com/charmbracelet/glow/releases
2019-12-19 02:36:30 +00:00
## The TUI
2019-11-09 22:12:54 +00:00
2020-10-18 16:11:45 +00:00
Simply run `glow` without arguments to start the textual user interface and
2020-10-20 12:01:05 +00:00
browse local and stashed markdown. Glow will find local markdown files in the
2020-10-12 12:02:32 +00:00
current directory and below or, if youre in a Git repository, Glow will search
the repo.
Markdown files can be read with Glow's high-performance pager. Most of the
2020-10-20 12:01:05 +00:00
keystrokes you know from `less` are the same, but you can press `?` to list
the hotkeys.
### Stashing
Glow works with the Charm Cloud to allow you to store any markdown files in
your own private collection. You can stash a local document from the Glow TUI by
pressing `s`.
You can also stash from the CLI:
```bash
glow stash README.md
```
Then, when you run `glow` without arguments will you can browse through your
stashed documents. This is a great way to keep track of things that you need to
reference often.
Stashing is private, its contents will not be exposed publicly, and it's
encrypted end-to-end. More on encryption below.
## The CLI
In addition to a TUI, Glow has a CLI for working with Markdown. To format a
document use a markdown source as the primary argument:
2019-11-09 22:12:54 +00:00
2019-12-19 02:36:30 +00:00
```bash
2019-12-13 19:44:32 +00:00
# Read from file
2019-12-20 21:47:47 +00:00
glow README.md
2019-12-13 19:36:25 +00:00
2019-12-13 19:44:32 +00:00
# Read from stdin
2019-12-20 21:47:47 +00:00
glow -
2019-11-22 03:51:44 +00:00
# Fetch README from GitHub / GitLab
2019-12-20 21:47:47 +00:00
glow github.com/charmbracelet/glow
2019-11-25 04:03:26 +00:00
2019-12-13 19:45:25 +00:00
# Fetch markdown from HTTP
2019-12-20 21:47:47 +00:00
glow https://host.tld/file.md
2019-11-22 03:51:44 +00:00
```
2020-07-29 16:49:36 +00:00
### Stashing
You can also stash documents from the CLI:
2020-07-29 16:49:36 +00:00
2020-08-27 17:50:46 +00:00
```bash
glow stash README.md
```
2020-07-29 16:49:36 +00:00
2020-08-27 17:50:46 +00:00
Then, when you run `glow` without arguments will you can browse through your
stashed documents. This is a great way to keep track of things that you need to
reference often.
2020-07-29 16:49:36 +00:00
### Word Wrapping
2019-12-13 02:25:02 +00:00
2019-12-19 02:36:30 +00:00
The `-w` flag lets you set a maximum width at which the output will be wrapped:
2019-12-13 19:36:25 +00:00
2019-12-19 02:36:30 +00:00
```bash
2019-12-20 21:47:47 +00:00
glow -w 60
2019-12-13 02:25:02 +00:00
```
2019-12-31 10:22:52 +00:00
### Paging
2020-08-27 17:50:46 +00:00
CLI output can be displayed in your preferred pager with the `-p` flag. This defaults
to the ANSI-aware `less -r` if `$PAGER` is not explicitly set.
2019-12-31 10:22:52 +00:00
### Styles
2019-12-13 02:25:02 +00:00
2020-01-14 01:20:21 +00:00
You can choose a style with the `-s` flag. When no flag is provided `glow` tries
to detect your terminal's current background color and automatically picks
either the `dark` or the `light` style for you.
2019-12-13 19:36:25 +00:00
2019-12-19 02:36:30 +00:00
```bash
2019-12-20 21:47:47 +00:00
glow -s [dark|light]
2019-12-13 02:25:02 +00:00
```
Alternatively you can also supply a custom JSON stylesheet:
2019-12-13 19:36:25 +00:00
2019-12-19 02:36:30 +00:00
```bash
2019-12-20 21:47:47 +00:00
glow -s mystyle.json
2019-11-26 20:03:46 +00:00
```
2019-12-19 02:36:30 +00:00
For additional usage details see:
```bash
2019-12-20 21:47:47 +00:00
glow --help
2019-12-19 02:36:30 +00:00
```
Check out the [Glamour Style Section](https://github.com/charmbracelet/glamour/blob/master/styles/gallery/README.md)
to find more styles. Or [make your own](https://github.com/charmbracelet/glamour/tree/master/styles)!
## The Config File
If you find yourself supplying the same flags to `glow` all the time, it's
probably a good idea to create a config file. Run `glow config`, which will open
it in your favorite $EDITOR. Alternatively you can manually put a file named
`glow.yml` in the default config path of you platform. If you're not sure where
that is, please refer to `glow --help`.
Here's an example config:
```yaml
# style name or JSON path (default "auto")
style: "light"
# show local files only; no network (TUI-mode only)
local: true
2020-10-23 06:46:59 +00:00
# word-wrap at width
width: 80
```
## 🔒 Encryption: How It Works
Encryption works by issuing symmetric keys (basically a generated password) and
encrypting it with the local SSH public key generated by the open-source
[charm][charmlib] library. That encrypted key is then sent up to our server.
We cant read it since we dont have your private key. When you want to decrypt
something or view your stash, that key is downloaded from our server and
decrypted locally using the SSH private key. When you link accounts, the
symmetric key is encrypted for each new public key. This happens on your
machine and not our server, so we never see any unencrypted data.
[charmlib]: https://github.com/charmbracelet/charm
2019-12-19 02:36:30 +00:00
## License
2019-11-09 22:12:54 +00:00
2019-12-20 21:47:47 +00:00
[MIT](https://github.com/charmbracelet/glow/raw/master/LICENSE)
2020-04-27 15:48:11 +00:00
2020-04-27 15:50:31 +00:00
Part of [Charm](https://charm.sh).
2020-10-20 14:16:30 +00:00
<a href="https://charm.sh/"><img alt="the Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>
2020-04-27 15:50:31 +00:00
2020-08-27 17:50:46 +00:00
Charm热爱开源! / Charm loves open source!
2020-10-20 14:16:30 +00:00