1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
# 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)
- [Usage](#usage)
+ [Configuration](#configuration)
+ [Generating the HTML files](#generating-the-html-files)
+ [Hosting the HTML files](#hosting-the-html-files)
- [Advanced configuration](#advanced-configuration)
## 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/cmd/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
|
