flare

README

* Flare

Render asciidoc or org on the CLI, with /glitz/ and /pizzazz/!

** What is it?
:PROPERTIES:
:CUSTOM_ID: what-is-it
:END:

Flare is a terminal based org / asciidoc reader inspired by [[https://github.com/charmbracelet/glow][glow]]

Use it to discover org or asciidoc files and read directly from
the terminal. Flare will find local org and asciidoc files in
subdirectories or a local Git repository.

** Installation

*** Go
:PROPERTIES:
:CUSTOM_ID: go
:END:
With =go=:

*** Build (requires Go 1.21+)
:PROPERTIES:
:CUSTOM_ID: build-requires-go-1.21
:END:
#+begin_src sh
git clone https://codeberg.org/hoanga/flare.git
cd flare
go build
# install (optional)
go install .
#+end_src

** The TUI
:PROPERTIES:
:CUSTOM_ID: the-tui
:END:
Simply run =flare= without arguments to start the textual user interface
and browse local documents. flare will find local org or asciidoc files
in the current directory and below or, if you're in a Git repository,
flare will search the repo.

Supported document files can be read with flare's high-performance pager. 
Most of the keystrokes you know from =less= are the same, but you can 
press =?= to list the hotkeys.

** The CLI
:PROPERTIES:
:CUSTOM_ID: the-cli
:END:
In addition to a TUI, flare has a CLI for working with supported formats.
To format a document use an org source as the primary argument:

#+begin_src sh
# Read from file
flare README.adoc

# Fetch org from HTTP
flare https://host.org-social.org/test/social.org
#+end_src

*** Word Wrapping
:PROPERTIES:
:CUSTOM_ID: word-wrapping
:END:
The =-w= flag lets you set a maximum width at which the output will be
wrapped:

#+begin_src sh
flare -w 60
#+end_src

*** Paging
:PROPERTIES:
:CUSTOM_ID: paging
:END:
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.

*** Styles
:PROPERTIES:
:CUSTOM_ID: styles
:END:
You can choose a style with the =-s= flag. When no flag is provided
=flare= tries to detect your terminal's current background color and
automatically picks either the =dark= or the =light= style for you.

#+begin_src sh
flare -s [dark|light]
#+end_src

Alternatively you can also supply a custom JSON stylesheet:

#+begin_src sh
flare -s mystyle.json
#+end_src

For additional usage details see:

#+begin_src sh
flare --help
#+end_src

Check out the
[[https://codeberg.org/hoanga/glamour/blob/master/styles/gallery/README.md][Glamour Style Section]]
to find more styles. Or
[[https://codeberg.org/hoanga/glamour/tree/master/styles][make your own]]!

** The Config File
:PROPERTIES:
:CUSTOM_ID: the-config-file
:END:
If you find yourself supplying the same flags to =flare= all the time,
it's probably a good idea to create a config file. Run =flare config=,
which will open it in your favorite $EDITOR. Alternatively you can
manually put a file named =flare.yml= in the default config path of you
platform. If you're not sure where that is, please refer to
=flare --help=.

Here's an example config:

#+begin_src yaml
# style name or JSON path (default "auto")
style: "light"
# mouse wheel support (TUI-mode only)
mouse: true
# use pager to display org
pager: true
# at which column should we word wrap?
width: 80
# show all files, including hidden and ignored.
all: false
# show line numbers (TUI-mode only)
showLineNumbers: false
# preserve newlines in the output
preserveNewLines: false
#+end_src

** License
:PROPERTIES:
:CUSTOM_ID: license
:END:
[[https://codeberg.org/hoanga/flare/raw/master/LICENSE][MIT]]

** Notes

An LLM (Claude) was used for the initial versions of this code

** Screenshots

[[./flare-example1.png]]
[[./flare-example2.png]]

--------------

** Thanks to

 - [[https://charm.sh][Charm]]
 - [[https://github.com/charmbracelet/glow][glow]]

Documentation

Overview

Package main provides the entry point for the Flare CLI application.

Package utils provides utility functions.