From 2e567fae8b84820b588bf29bd8430bea13c66279 Mon Sep 17 00:00:00 2001
From: Ronmi Ren <ronmi.ren@gmail.com>
Date: Sun, 12 Jan 2025 22:50:02 +0800
Subject: [PATCH] update readme

---
 README.md | 50 +++++++++++++++++++++++++-------------------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index 22e78a7..5c74c68 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,31 @@
 A simple static page service for Forgejo/Gitea.
 
-### UNIX philosophy: simple and flexible
+### Repo setup
 
-It serves static page at `http://ip:port/user/repo/path`, which can be further maniplated (SSL, caching, URL rewriting, etc.) by reverse proxies with ease.
+Everything in branch `static-pages` (if you have not changed it by assigning `-b` flag) will be served as-is.
 
-# Usage
+There are two mode you can use: serve mode and webhook mode. 
 
-### Service setup
+### Serve mode
+
+Serve mode starts an HTTP server listens on specified port. When you visit `http://ip:port/user/repo/path/to/file`, it ask forgejo server for `path/to/file` in branch `static-pages` of repository `user/repo` via api, then forward the response to client.
+
+In other words, anything you push to branch `static-pages` will be provided as-is.
+
+This mode is good for simple setup, like, you have small number of viewers, or you use other powerful cache/proceting service like Cloudflare.
+
+### Webhook mode
+
+Webhook mode is a tool which helps you to download latest content via git. You'll have to setup a webhook in forgejo server in order to notify it when to download new content.
+
+To serve downloaded pages, you'll have to use a web server like Nginx.
+
+### Example
 
 ```
-$ forgejo-pages serve -h
-Start the static page server.
+forgejo-pages serve -k my-secret-token -s https://git.example.com -a :8080 -b static-pages
 
-Usage:
-  forgejo-pages serve [flags]
-
-Flags:
-  -a, --bind string     bind address (default ":8080")
-  -b, --branch string   branch to use (default "static-pages")
-  -h, --help            help for serve
-  -s, --server string   Forgejo server address
-  -k, --token string    Forgejo api token
-
-Global Flags:
-      --config string   config file (default is $HOME/.forgejo-pages.toml)
+forgejo-pages listen -u myuser -k my-secret-token -s https://git.example.com -a :8080 -b static-pages -d ./data
 ```
 
 Flags can be assigned through environmental variables like `PAGES_BIND`, `PAGES_BRANCH`, or config file
@@ -34,18 +36,16 @@ server="https://git.example.com"
 token="my-secret-token"
 ```
 
-Take care about permissions of the API token.
+Take care about permissions of the API token. For serve mode, repositories the key cannot read will return error. For webhook mode, it will failed to download (clone/pull) new content.
 
-### With docker
+### Use docker
 
 ```
-docker run -p 8080:8080 ronmi/forgejo-pages serve -s https://git.example.com -k my-secret-token
+docker run -p 8080:8080 --user 1000:1000 ronmi/forgejo-pages serve -s https://git.example.com -k my-secret-token
+
+docker run -p 8080:8080 --user 1000:1000 -v `pwd`/data:/data ronmi/forgejo-pages listen -u myuser -k my-secret-token -s https://git.example.com -a :8080 -b static-pages -d /data
 ```
 
-### Repo setup
-
-Everything in branch `static-pages` (if you have not changed it by assigning `-b` flag) will be served as-is.
-
 # FAQ
 
 ### Can I use user.example.com/repo/path format?