Add usage docs

2021-12-31 11:30:30 -05:00 · 2021-12-31 11:30:30 -05:00 · 01c7bbe7d7
commit 01c7bbe7d7
parent 9656abc970
1 changed files with 40 additions and 6 deletions
--- a/README.md
+++ b/README.md
@ -7,9 +7,43 @@ SPDX-License-Identifier: CC0-1.0
 # go-webring
 Simple webring implementation

-## TODO
- [ ] Implement some kind of rate-limiting or caching; the list of ring members
-      is re-read on each request and one could abuse this to DOS the server.
-  - It does save admins from having to restart the server when adding new
-    members, though, so I would like to keep the current functionality.
-    However, some sort of DOS mitigation would still be good Just In Case™.
+## Usage
+
+``` text
+$ ./go-webring -h
+Usage of ./go-webring
+  -i, --index string     Path to home page template (default "index.html")
+  -l, --listen string    Host and port go-webring will listen on (default "127.0.0.1:2857")
+  -m, --members string   Path to list of webring members (default "list.txt")
+```
+
+See the included `list.txt` and `index.md` for examples of a webring setup. To
+run `go-webring` with those examples, first generate `index.html` from
+`index.md` like so:
+
+``` shell
+$ pandoc -s index.md -o index.html
+```
+
+In *your** home page template, place the string `{{ . }}` wherever you want the
+table of members inserted. It's a regular HTML table so you can style it with
+CSS in the template's `<head>` or in a separate `.css` file.
+
+Given the example `list.txt`, the following is what `go-webring` would insert,
+so it's up to you to add the starting `<table>` and `<th>` tags as in the
+example `index.md`.
+
+``` html
+<tr>
+  <td>member1</td>
+  <td><a href="https://example.com">example.com</a><td>
+</tr>
+<tr>
+  <td>member2</td>
+  <td><a href="https://sometilde.com/~member2">sometilde.com/~member2</a><td>
+</tr>
+```
+
+You don't *have* to create your webring home page in Markdown, that's just what
+I found easiest. As long as your HTML template includes `{{ . }}`, the table
+will show up.