diff options
| -rw-r--r-- | README.md | 93 | ||||
| -rw-r--r-- | doc/getting-started.md | 168 | ||||
| -rw-r--r-- | doc/references.md | 12 |
3 files changed, 209 insertions, 64 deletions
@@ -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: - - - -## 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/ |