Update documentation

Signed-off-by: Nicolas Paul <n@nc0.fr>

3 files changed, 209 insertions, 64 deletions

diff --git a/README.md b/README.md
index 1641632..77529dc 100644
--- a/README.md
+++ b/README.md
@@ -1,76 +1,47 @@
-# staticgovanityurls
+# SVGU
 
-`staticgovanityurls` (Static Go Vanity URLs) is a simple script that generates
-documents to index Go modules on custom domain names.
+SVGU (short for *Static, Vanity, Go URL*) is a flexible and easy to use
+tool for creating vanity URLs for your Go projects.
+It allows publishing a Go module under a custom domain name, without the need
+to use your code forge's domain name.
 
-## Usage
+For example, if you have a project hosted on GitHub, you can use SVGU to
+publish it under a custom domain name, such as `myproject.com/foo` instead of
+`github.com/myproject/foo`.
 
-Using the script is dead-simple! All you need is a valid configuration file and 
-a copy of the compiled executable. If you have Go installed on the host, you 
-can install the script by running:
+## How it works
 
-```bash
-$ go install go.nc0.fr/staticgovanityurls@latest
-```
+SVGU requires a configuration file, usually named `DOMAINS.star`, which
+describes the modules to export.
 
-Once the binary is installed – and available in $PATH, you will need to write a 
-configuration file. 
-Here is a sample one:
+The configuration file is a [Starlark](https://starlark.net) script, which
+allows for a lot of flexibility.
+Starlark is a subset of Python for configuration files, and is used by the
+[Bazel](https://bazel.build) build system and others.
+It is a simple language, and you don't need to know Python to use it.
 
-```yaml
-hostname: "go.example.com"
-paths: 
-    - prefix: "foo" 
-      repository: "https://github.com/example/foo.git"
-      vcs: "git" 
-      dir: "https://github.com/example/foo/tree/master{/dir}"
-      file: "https://github.com/example/foo/blob/master{/dir}/{file}#L{line}"
-    - prefix: "bar" 
-      repository: "https://svn.example.com/~baz/bar.svn"
-      vcs: "svn" 
-      dir: "https://svn.example.com/~baz/bar.svn{/dir}"
-      file: "https://svn.example.com/~baz/bar.svn{/dir}/{file}#{line}"
-```
+See the [reference documentation](doc/references.md) for more information.
 
-When you are ready, you can generate HTML documents by executing:
+Once the configuration file is ready, you can run SVGU to generate the
+necessary files, and then publish them on your web server.
 
-```bash
-$ staticgovanityurls -i=vanity.yaml -o=dist
+```shell
+$ svgu
 ```
 
-> The `-i` flag is used to specify the input file, while `-o` is used to
-> define the output directory.
-
-Inside the `dist` directory, you should find a set of files as follows:
-
-![Directory listing](doc/example-files.png)
-
-## Configuration
+This will generate a `dst` directory containing the files to publish.
 
-The configuration file is a YAML document that contains the following fields:
+## Documentation
 
-| Field      | Type   | Description                     |
-| ---------- | ------ | ------------------------------- |
-| `hostname` | string | The hostname of the vanity URL. |
-| `paths`    | array  | A list of paths to index.       |
-
-Each path is a map that contains the following fields:
-
-| Field        | Type   | Description                                                                                                                                       |
-| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `prefix`     | string | The prefix of the vanity URL.                                                                                                                     |
-| `repository` | string | The URL of the repository.                                                                                                                        |
-| `vcs`        | string | The version control system used: `git`, `svn`, `bzr`, `hg` or `fossil`.                                                                           |
-| `dir`        | string | URL to a document listing the files inside a directory of the module. It supports substitutions from the `go-source` meta tag.[^go-source]        |
-| `file`       | string | URL to a document listing the content – lines – inside a file of the module. It supports substitutions from the `go-source` meta tag[^go-source]. |
-
-[^go-source]: https://github.com/golang/gddo/wiki/Source-Code-Links
+- [Getting started](doc/getting-started.md)
+- [Reference documentation](doc/references.md)
+- [Bug tracker](https://todo.sr.ht/~n1c00o/svgu)
+- [Mailing list](https://lists.sr.ht/~n1c00o/svgu)
+- [Source code](https://git.sr.ht/~n1c00o/svgu)
+- [Project page](https://sr.ht/~n1c00o/svgu)
 
 ## License
 
-The project is governed by a BSD-style license that can be found in the 
-[LICENSE](LICENSE) file.
-
-The Gopher illustrations used are under the [CC0](https://github.com/egonelbre/gophers/blob/master/LICENSE-CC0)
-license.
-
+The SVGU project is governed by a [BSD-style license](LICENSE).
+The documentation is licensed under the [Creative Commons Attribution 4.0
+International License](https://creativecommons.org/licenses/by/4.0/).
diff --git a/doc/getting-started.md b/doc/getting-started.md
new file mode 100644
index 0000000..3e37bfd
--- /dev/null
+++ b/doc/getting-started.md
@@ -0,0 +1,168 @@
+# Getting started
+
+This document will help you get started with SVGU.
+
+## Table of contents
+
+- [Installation](#installation)
+  + [From source](#compiling-from-source)
+  + [Pre-built binaries](#pre-built-binaries)
+  + [Docker](#docker)
+
+## Installation
+
+First, you need to install SVGU. There are several ways to do this.
+
+### Compiling from source
+
+SVGU is a Go program, and can be installed quickly using `go install`:
+
+```shell
+# Change "latest" to the Git ref you want to install.
+$ go install go.nc0.fr/svgu@latest
+```
+
+> Note: SVGU requires Go 1.16 or later.
+
+### Pre-built binaries
+
+TODO(nc0): Add pre-built binaries and pkg for various platforms.
+
+### Docker
+
+TODO(nc0): Add Docker image.
+
+## Usage
+
+SVGU is a command-line tool that, given a configuration file, will generate
+a set of HTML 5 documents ready to be served by any web server.
+
+### Configuration
+
+The configuration file is a [Starlark][starlark] script that registers the
+various modules to publish under a domain.
+
+Starlark is a dialect of Python, and is very easy to learn. The reference
+documentation is available [here][starlark].
+
+In addition to the standard Starlark specification, SVGU provides a set of
+utility functions to make it easier to write configuration files.
+The documentation for these functions is available [here](references.md).
+
+To get started, you need to create a file named `DOMAINS.star` in the directory
+of your choice. This file will contain the configuration for your website.
+
+> Note: The name of the file is not important, by default SVGU will look for
+> a file named `DOMAINS.star` in the current directory. You can specify a
+> different file using the `-c` flag.
+
+In this file, you need to create an index (a set of modules on a domain) and
+registers various modules to it. For example, let's say you want to publish
+the module `foo` on the domain `example.com`. You would write the following:
+
+```starlark
+# DOMAINS.star
+index(domain = "example.com")
+
+module(
+    name = "foo",
+    vcs = "git",
+    repo = "https://github.com/example/foo.git",
+    dir = "https://github.com/example/foo.git/tree/master{/dir}",
+    file = "https://github.com/example/foo.git/blog/master{/dir}/{file}#L{line}",
+)
+```
+
+This may look a bit complicated, but it's actually quite simple. Let's break
+it down:
+
+- `index(domain = "example.com")` creates an index—a set of modules—on the
+  domain `example.com`. The domain is used to generate the URLs for the
+  modules, e.g. `example.com/foo`.
+- `module(name = "foo", ...)` registers a module named `foo` on the index.
+  The `name` argument is the name of the module, and is used to generate
+  the URLs for the module, e.g. `example.com/foo`.
+- `vcs = "git"` tells SVGU that the module is hosted on a Git repository.
+- `repo = "..."` is the URL of the Git repository.
+- `dir = "..."` and `file = "..."` are URL templates for
+  [pkg.go.dev](https://pkg.go.dev). They are used to allow automatic
+  documentation. You can read more about them in the
+  [reference](references.md#module).
+
+You can add as many modules as you want to an index. For example, let's say
+you want to add the module `bar` hosted on a Mercurial repository:
+
+```starlark
+module(
+    name = "bar",
+    vcs = "hg",
+    repo = "https://example.com/bar",
+    dir = "https://example.com/bar/file/tip{/dir}",
+    file = "https://example.com/bar/file/tip{/dir}/{file}#L{line}",
+)
+```
+
+### Generating the HTML files
+
+When you're done, you can run SVGU to generate the HTML files:
+
+```shell
+$ svgu
+```
+
+This will generate a directory named `out` containing the HTML files. You can
+then serve this directory using any web server.
+If you used another name for the configuration file, you can specify it using
+the `-c` flag.
+You can also change the output directory using the `-o` flag.
+And lastly, the `-v` flag can be used to print more information.
+
+### Hosting the HTML files
+
+Once you have the generated HTML documents inside the output directory
+*(by default it is `dst`)*, you can upload them to your web server.
+
+The target web server does not need to be configured in any special way,
+we only require that it supports URL rewriting (as most web servers do)
+to remove the `.html` extension from the URLs.
+This is sometimes called [clean URLs](https://en.wikipedia.org/wiki/Clean_URL)
+or "Pretty URLs".
+
+Here is a non-exhaustive list of web servers that support URL rewriting:
+
+- [Apache HTTPD](https://httpd.apache.org/docs/current/rewrite/remapping.html)
+- [Caddy](https://caddyserver.com/docs/caddyfile/directives/rewrite)
+- Cloudflare Pages does it automatically
+- [NGINX](https://www.nginx.com/blog/creating-nginx-rewrite-rules/)
+- [GitHub Pages](https://pages.github.com/) does it by default
+- ...
+
+### Advanced configuration
+
+As you can see, the configuration file is very simple. However, it is also
+a bit boilerplate-heavy, especially with the template URLs for `dir` and
+`file`.
+
+To avoid this, SVGU provides a set of utility libraries that can be imported
+via the `load()` function. For example, the previous configuration can be
+shortened to:
+
+```starlark
+load("@svgu/git.star", "git")
+
+index(domain = "example.com")
+
+git.github(
+  name = "foo",
+  user = "example",
+  repo = "foo",
+  branch = "master",
+)
+
+...
+```
+
+You can read more about the utility libraries in the [reference](references.md).
+Those can help when writing long configuration files.
+
+[starlark]: https://github.com/bazelbuild/starlark
diff --git a/doc/references.md b/doc/references.md
index 88fd53a..e0e6b79 100644
--- a/doc/references.md
+++ b/doc/references.md
@@ -9,14 +9,14 @@ The sources for the environment are located inside the
 
 ## Starlark
 
-[Starlark](https://starlark.net) is a dialect of Python designed for use as a
+[Starlark][starlark-link] is a dialect of Python designed for use as a
 configuration language. It is simple, safe, and expressive.
 Originally called Skylark, Starlark is commonly used with
-[Bazel](https://bazel.build)-like build systems, but it is not tied to any
+[Bazel][bazel-link]-like build systems, but it is not tied to any
 particular tool or project.
 
 SVGU's Starlark environment is based on the
-[Starlark Go](https://go.starlark.net) implementation open sourced by Google.
+[Starlark Go][starlark-go] implementation open sourced by Google.
 
 ## Table of Contents
 
@@ -568,3 +568,9 @@ module(
 [gerrit-link]: https://www.gerritcodereview.com/
 
 [go-source-tag]: https://github.com/golang/gddo/wiki/Source-Code-Links
+
+[starlark-link]: https://github.com/bazelbuild/starlark
+
+[starlark-go]: https://github.com/google/starlark-go
+
+[bazel-link]: https://bazel.build/