You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+234Lines changed: 234 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,3 +15,237 @@ Henceforth:
15
15
16
16
> If `site` doesn't work, use `./site` instead (or add `.` to your $PATH)
17
17
18
+
<br>
19
+
20
+
### Contributions & Issues
21
+
22
+
If you see any issues with the website, or have any trouble running the build system yourself, please [file an issue](https://github.com/automerge/website/issues).
23
+
24
+
<br><br>
25
+
26
+
# Documentation
27
+
28
+
*[Overview](#overview)
29
+
*[Pages](#pages)
30
+
*[Frontmatter](#frontmatter)
31
+
*[Templates](#templates)
32
+
*[Macros](#macros)
33
+
*[Includes](#includes)
34
+
*[Other Features](#other-features)
35
+
*[Assets](#assets)
36
+
*[Fonts](#fonts)
37
+
*[Redirects](#redirects)
38
+
*[Broken Links](#broken-links)
39
+
*[System](#system)
40
+
41
+
<br><br>
42
+
43
+
# Overview
44
+
45
+
Here's the folder structure:
46
+
47
+
*`content` — html and markdown files for every page, plus a few lightweight assets; see [pages](#pages)
48
+
*`demo` — source files for the interactive demo on the home page.
49
+
*`fonts` — uncompressed source files for fonts used on the site; see [fonts](#fonts)
50
+
*`public` — automatically generated when building the site
51
+
*`system` — the build system source code; see [system](#system)
52
+
*`template` — html files that define different types of page on the site; see [templates](#templates)
53
+
54
+
This site is powered by our own custom build system, which we can adapt and extend as our needs change.
55
+
56
+
The build system takes HTML and Markdown files in the `content` folder, parses and transforms them with rules defined in `system`, combines the result with various templates in `template`, and finally saves the fully-assembled page to `public`.
57
+
58
+
In short, the `content` folder should feel like an FTP server. You put stuff in there, and it shows up on the website. The file path becomes the URL. There's more, of course — macros and templates and other behaviour that we'll get to in a second. But all that fanciness is *opt-in*. If you stick to plain HTML and simple assets, `/content` acts just like FTP.
59
+
60
+
<br><br>
61
+
62
+
# Pages
63
+
64
+
We're going to talk a lot about *pages* — so what's a page? It's an HTML or Markdown file that lives in the `content` folder, with some *frontmatter* explaining what the page is and how it should be processed.
65
+
66
+
If you make an HTML file `/content/pens/index.html`, the build script copies it over to `/public/pens/index.html`, and it becomes a web page with the URL `/pens/index.html`.
67
+
68
+
If you make a Markdown file `/content/rams/index.md`, the build system will convert it to HTML, copy it to `public`, and it'll end up with the URL `/rams/index.html`.
69
+
70
+
#### Clean URLs
71
+
72
+
Many web servers have a nice feature: if a page is named `index.html`, you can omit that part of the URL. So the above pages can also be accessed at `/pens` and `/rams`. Those are clean URLs.
73
+
74
+
To make the most of these clean URLs, the build system has one trick: pages are renamed from `name.html` to `/name/index.html`, so the URL can be `/name`.
75
+
76
+
Thus, a page with the URL `/eraser/head` will be generated by *exactly one* of these files:
77
+
78
+
*`/content/eraser/head.md`
79
+
*`/content/eraser/head.html`
80
+
*`/content/eraser/head/index.md`
81
+
*`/content/eraser/head/index.html`
82
+
83
+
Use whichever file naming you like. It's fine to mix and match. Though for pages with static assets, it's recommended to use one of the latter two forms so you have a natural place to put those assets. And if there's ever a conflict (where two files would have the same URL), you'll see a helpful error message.
84
+
85
+
<br>
86
+
87
+
### Frontmatter
88
+
89
+
At the top of every page is the **frontmatter** section — properties that control how the page is processed by the build system. The frontmatter section begins and ends with `---`, and uses a `key: value # comment` syntax that looks like YAML but is much simpler.
90
+
91
+
Here's an example of what frontmatter looks like:
92
+
93
+
```yml
94
+
---
95
+
title: Automerge
96
+
styles: /index/index.css, /index/demo.css
97
+
scripts: /index/dithering.js
98
+
template: landing
99
+
---
100
+
```
101
+
102
+
#### Frontmatter is optional
103
+
104
+
All the fanciness of the build system is *opt-in*. Frontmatter is the primary way for a page to opt-in to special processing.
105
+
106
+
* For an HTML file with no frontmatter, no processing is applied (including the aforementioned [clean-URL renaming](#clean-urls)).
107
+
* All markdown files in `/content` get processing special whether they have frontmatter or not.
108
+
109
+
#### Template
110
+
111
+
The most crucial piece of frontmatter is `template`, which specifies what kind of page this is. The build system will inject the page's content into the matching template HTML file from `/template`. See the [Templates](#templates) section for more.
112
+
113
+
#### Publish
114
+
115
+
Another important piece of frontmatter is `publish`. It's `true` by default, which means the page will be included when building the website. You can set it to `draft`, which means the page won't be included on automerge.org, but will be included in local dev builds. Or you can set it to `false` to completely exclude the page from all builds.
116
+
117
+
If a non-draft page links to a draft, you'll see a helpful warning.
118
+
119
+
For most [CLI commands](#system), you can specify `--no-draft` if you don't want drafts to be included. But, for `site build`, drafts are excluded by default, and you must use `--draft` to include them.
120
+
121
+
#### Date
122
+
123
+
If a page is given a `date`, it'll be included in RSS feeds. The date must be in `YYYY-MM-DD` format.
124
+
125
+
#### Others
126
+
127
+
*`title` will be used for <title> and for RSS.
128
+
*`description` will be used for OG and RSS. Can include inline markdown.
129
+
*`image` for the rich preview whenever someone shares a link to the page.
130
+
*`styles` and `scripts`, which accept comma-separated lists of relative or absolute paths.
131
+
*`clean: false` to skip `name.html -> name/index.html` rewriting.
132
+
*`index: false` — Page will not be included in RSS feeds or the sitemap.
133
+
134
+
<br>
135
+
136
+
### Templates
137
+
138
+
The `/template` folder contains a handful of HTML files that give pages their structure and styling.
139
+
140
+
Pages use the [`template` frontmatter](#template) to specify which of these template HTML files to use. If omitted, `default` is used.
141
+
142
+
Templates can have frontmatter, too, though this is a more advanced topic that depends on the inner workings of the build system.
143
+
144
+
<br>
145
+
146
+
### Macros
147
+
148
+
Pages & templates can contain **macros**, which look like: `{{ rain-dogs }}`.
149
+
150
+
Macros mark locations that the build system should *do something*.
151
+
152
+
The most basic macro is `{{ content }}`, which marks where pages will be injected into templates.
153
+
154
+
If there's no special behaviour defined for a macro, the default behaviour is to copy a value from the frontmatter. For instance, if the page frontmatter includes `band: Zs` and the template has `{{band}} are so damn good!`, the final page will have the text `Zs are so damn good!`. [Accurate](https://zstheband.bandcamp.com/track/b-is-for-burning-2).
155
+
156
+
If you see a macro and you aren't sure what it does, take a look at `/system/macros.ts` — that's where all the macro expansion logic lives.
157
+
158
+
<br>
159
+
160
+
### Includes
161
+
162
+
There's a folder of reusable snippets at `/template/includes/`. You can add HTML or MD files here, and then include them in your pages with the `{{include:___}}` macro.
163
+
164
+
For instance, the Automerge logo lives in `/template/includes/logo.html`, and can be included like so: `{{ include: logo }}`.
165
+
166
+
<br><br>
167
+
168
+
# Other Features
169
+
170
+
<br>
171
+
172
+
### Assets
173
+
174
+
Git is *fine* for version control of text. It's *awful* for images and videos — it remembers ever version of every asset that's ever been committed, and they slow down clones, diff, and other actions. Before adding images, videos, and other non-text assets to the repo, please do the following:
175
+
176
+
1.**Resize** — if an image is only going to display at 1000px wide (at most), it should be no more than 2000px wide, and ideally closer to 1200px. (A tiny bit of extra detail is often enough to give the illusion of a crisp 2x retina image).
177
+
2.**Format** — line art and screenshots should be PNG or WebP, photos should be WebP or JPG.
178
+
3.**Optimize** — Use [ImageOptim](https://imageoptim.com/mac) or [Squoosh](https://squoosh.app) or whatever other tools you have available. Try to keep big photos down around 100-300kb, and screenshots around 10kb-100kb.
179
+
180
+
<br>
181
+
182
+
### Fonts
183
+
184
+
In typical web development, you'd put a `woff2` font file alongside your other assets, and then load it in your stylesheet. But fonts often contain a *ton* of wasted data — ligatures and alternates and glyphs for characters that are never used.
185
+
186
+
Instead, to add fonts to our website, you place `ttf` or `otf` files in the `/fonts` folder. The build system can then:
187
+
188
+
1. Scan every page of the site, and collect every unique character of text.
189
+
2. Create a **subset** of data in the `ttf` / `otf` files with just the characters we use.
190
+
3. Create optimized `woff2` files of those subset fonts, and save them to `/content/static/fonts/`.
191
+
192
+
The build system will redo step 1 every time it runs. It will only redo steps 2 & 3 if it notices that the set of unique characters has changed.
193
+
194
+
So, when you add, remove, or change any of the fonts in the `/fonts` folder, you need to force the build system to redo steps 2 & 3. To do that, just delete the `/content/static/fonts/chars.txt` file.
195
+
196
+
#### Caveats & Cautions
197
+
198
+
This automatic font subsetting requires two non-NPM binary dependencies: harfbuzz and woff2.
199
+
200
+
* On Mac, you can `brew install harfbuzz woff2`
201
+
* Not sure about Linux / Win — it is a goal to fully support these platforms, but that work hasn't been done yet.
202
+
* It's fine if these deps are missing. The build system will still run, but when the set of characters changes it will log a single warning and skip regenerating the fonts.
203
+
* Any characters that are missing will still be displayed on the site, they'll just appear in a fallback font.
204
+
* TODO / Wishlist: These deps can be added to the Github Actions flow, ensuring we always have the correct font subsets when the site is deployed.
205
+
206
+
<br>
207
+
208
+
### Redirects
209
+
210
+
In the `Redirects.txt` file, you'll find a list of redirect rules. One rule per line, space-separated.
211
+
212
+
```
213
+
/source /destination
214
+
/old/busted /new/hotness
215
+
216
+
Bare text is a comment 👋
217
+
218
+
The redirect source MUST start with a slash. The destination can be any URL.
219
+
/secret https://feelingisreality.com
220
+
221
+
You can redirect other kinds of files, too, not just HTML/Markdown pages.
222
+
We don't control the server, so we can't do a 301 or 302. Instead, the build system
223
+
will hardlink the file at the new path to the old path, so that both paths will work.
224
+
/old/path.pdf /new/path.pdf
225
+
```
226
+
227
+
* Add a redirect whenever you [move or rename](https://www.w3.org/Provider/Style/URI) an existing page or asset (ie: PDF) that someone might have bookmarked.
228
+
* You can also use a redirect to create an alias so that multiple URLs will point to the same thing — but [don't go overboard](https://www.w3.org/Provider/Style/URI).
229
+
* These redirects are excluded from the Sitemap.
230
+
231
+
<br>
232
+
233
+
### Broken Links
234
+
235
+
The build system will automatically check internal links for validity. If you try to link to a page that doesn't exist, you'll see a warning in the terminal.
236
+
237
+
In the future, we'd like to add automatic checking for *external* links too, with some sort of assistance in adding a Wayback Machine fallback if links go dead. How best to do this is an open question — suggestions welcome!
238
+
239
+
<br><br>
240
+
241
+
# System
242
+
243
+
The website includes the `site` CLI tool.
244
+
245
+
You can run `site help` to list all the available commands.
246
+
247
+
> If `site` doesn't work, use `./site` instead (or better yet, add `.` to your $PATH)
248
+
249
+
`site` is a little shell script at the root of the repo. It executes `system/app.ts` using the fastest available Node-compatible runtime (bun, deno, or node).
250
+
251
+
`app.ts` is the main entrypoint to the build system. If you want to learn how it works, start reading from there. It's all extensively commented, and a lot of care was taken to make it easy to understand and hack on.
0 commit comments