www

www reads directories and repos in the browser: Markdown as pages, code as code, history beside both.

It is for anyone who keeps notes, docs and code in plain files and wants to read them as linked pages. It runs on your machine. Nothing needs a build step, and nothing needs a push first.

A repo on GitHub, GitLab or Codeberg reads the same way, once www has fetched it.

It is fast. A page takes one to three milliseconds and a server starts in about 40 ms. make test fails any page that takes over 5 ms.

Usage

www [-p] [--foreground] [--no-open] [-a ADDR] [--debug] [--no-bug]
    [--cache=SIZE] [--disk=SIZE] [--] [DIR]
www [-p] [--foreground] [--no-open] --share[=HOST] [--secret] [--debug]
    [--no-bug] [--cache=SIZE] [--disk=SIZE] [--] [DIR]
www --restart [-f] [--no-open] [--debug] [--no-bug]
    [-a ADDR | --share[=HOST]] [--] [DIR]
www -l [-a ADDR | --share[=HOST]] [--] [DIR]
www --kill [-a ADDR | --share[=HOST]]
www --commit=REV [--] [DIR]
www --public --disk=SIZE (-a ADDR | --share[=HOST]) [--debug]
    [--cache=SIZE]
www -h | --help
www -V | --version

Run www in a directory. It prints the tree’s URL and opens the browser.

It also writes a lockfile named after the endpoint, eg 127.31.1.1-8080.lock. Delete the lockfile to stop serving the tree. Trees on one address share one server, which exits when its last lock is gone.

www                         serve this directory and open it
www -p ~/notes              serve ~/notes, and again after a reboot
www --share=192.168.1.5     serve this directory to the LAN
www -l                      list every served tree as keyval
www --restart               move every server to the current binary
www --public --disk=6G -a 127.0.0.1:8080
                            serve online repos to the web, behind a proxy

Add ?log to any page’s URL for its history.

To read a repo from GitHub, open http://127.31.1.2/github.com/junegunn/fzf/.

Install

www needs git.

make install links build/www into ~/.local/bin and serves on port 8080.

make install-deb builds and installs two Debian packages: www and its syntax tree helper. The package’s binary may bind port 80, so URLs carry no port.

Documentation

• Options and environment: every option, the keyval output and the variables that set defaults
• Servers and locks: how trees join a server, the index at /, addresses, restarts and serving after reboot
• Pages: URLs, how docs render, links, live reload and the look
• Code pages: highlighting, line links, scope boxes, the syntax tree and gron
• Search and controls: the search box, keys, the copy buttons and when controls fade
• History: histories, commits, stardates, the timeline and old versions of a tree
• Online repos: reading a forge’s repos on the second address, or serving them to the web
• Sharing: serving a tree to other machines
• Safety: what www refuses to serve, follow or run
• Speed: what www caches and how it is timed
• Log: what www writes to the journal
• Debugging: the bug button and the build stamp
• Install: the Debian package, port 80 and locks in git
• Development: make run, the working name and the usage check
• Testing: Go tests, the black-box suite and the heavy runs

Licence

MIT, see LICENSE.

The embedded fonts are subsets of STIX Two Text and Iosevka, under the SIL Open Font License: see assets/fonts/STIXTwoText-OFL.txt and assets/fonts/Iosevka-OFL.txt.

The binary links in three Go modules under the MIT licence: goldmark by Yusuke Inuzuka, chroma by Alec Thomas and regexp2 by Doug Clark. regexp2 ports parts of Microsoft’s dotnet/corefx. The package’s copyright file carries their notices.