Using Closure-style Traits to Simplify a Rust API

2024-12-04T00:00:00+00:00

I recently published a Rust</a> library called nucleo-picker</code></a> which enables command-line applications to incorporate an interface for making a selection from a number of provided options. The selection is done through an interactive query, with a search algorithm used to filter and rank the given possibilities. A popular choice, and the one internal to nucleo-picker</code>1</label>Not my implementation, but rather from Pascal Kuthe’snucleo</code></a> crate., is to use the Smith–Waterman algorithm</a> from DNA sequence alignment since it is relatively simple to implement, performant even in the presence of a large number of matches, and not too sensitive to typos and other user input errors.

In our case, since we are implementing a library, we do not make any choices concerning rendering: instead, the library user must define how their types should be represented within the picker. In the end, I decided on the following closure-style trait with generic associated types.

pub</span> trait</span> Render</span><T> {</span>
</span></span></span>    type</span> Str</span><</span>'a</span>></span>:</span> AsRef</span><</span>str</span>></span></span>
</span></span></span>    where</span>
</span></span></span>        T:</span> 'a</span>;</span>
</span></span></span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> Self</span>::</span></span></span>Str<</span>'a</span>></span></span></span></span>;</span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
I would like to discuss my thought process behind this choice, and mainly why this API differs from the much more popular skim</a> picker library.
Instead of just explaining the benefits of such a choice, let’s work our way through some alternative approaches and see how this solution arises.</p>
</a>No generics</h2>
The first possibility, and certainly the simplest possible choice, is simply to have a concrete type within the picker that the item must be rendered as.
For instance, one might require that all items are sent to the picker as a String</code>, or some other internal representation.
Internally, for performance reasons, this can be quite ideal: since a matcher engine must perform a large number of score computations every time the query string changes, having an optimized internal representation can greatly improve performance.</p>
However, there are quite a few issues with this approach.</p>
</a>Overhead to keep track of items</h3>
The first issue is that the user needs to keep track of the items by themselves.
There can be quite a bit of implementation overhead to doing this, especially if for performance you want multi-threading: the user must maintain an internal global item queue (such as an append-only vector</a>) and track the association between the items and the rendered format.
This is something we would like to deal with on behalf of the user.</p>
</a>Conversion overhead and API commitment</h3>
If you have a custom internal type which requires pre-processing to generate (such as a Vec<char></code>), the user must convert to your provided type.
You can provide adapters for your type, such as From<String></code>; however, the user must still import your type, understand the subtleties, and track down the relevant adapter.
Moreover, this is an additional API commitment if your internal representation changes, since you must continue to support the previous conversion methods.</p>
</a>Extra memory overhead with lossy representation</h3>
In many situations, internally one does not actually want to store the rendered value, but rather a representation which is optimized for matching.
For example, it is often quite ideal to begin with a string slice, iterate over graphemes</a>, and then normalize the grapheme</a> to avoid issues with non-canonical representation.
In particular, it may be insufficient to only store the internal representation, and the picker may require two representations: the first, which is a user-friendly rendered format (such as String</code>), and the second, which is an internal representation only used for matching.
This unnecessarily incurs additional memory overhead.</p>
</a>A trait for picker items</h2>
We’ve now decided that we want to keep track of the items on behalf of the user and maintain our own internal representation, so the picker is now generic over an item type T</code>.
In order for the user to explain how to render the item T</code>, perhaps the first solution that many people will reach for is to require that T</code> implements a trait such as</p>
trait</span> Item</span> {</span>
</span></span></span>    fn</span> </span>text</span></span>(</span>&</span>self</span></span>)</span></span></span></span> -></span> Cow<</span>'_</span>, str</span>></span></span></span></span>;</span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
This is the approach taken by skim</a>.
Then, the picker is generic over any type T</code> which implements Item</code>, and then uses the Item</code> implementation to generate the internal representation, and also to represent the item within the picker view (if the internal representation is lossy).</p>
</a>Implementation on foreign types</h3>
The first concern, which is more of an inconvenience rather than a serious problem, is that an Item</code> trait increases the number of wrapper types if a user wants to have a picker item which is not local to the crate.
This is a relatively common concern for the picker: for example, if you wanted to implement a find</code> clone with a picker interface on the matching items, you might import the ignore</a> crate, and then the natural choice for an item is a DirEntry</code>.</p>
</a>Difficulty in default implementation</h3>
In order to alleviate the user responsibility, one could in principle preemptively implement Item</code> for as many foreign types as possible.
For instance (and again, this is done by skim</a>), one might have an implementation such as</p>
impl</span></span><</span>T:</span> AsRef</span><</span>str</span>></span></span>></span></span></span> Item for</span></span> T</span> </span>{</span>
</span></span></span>    fn</span> </span>text</span></span>(</span>&</span>self</span></span>)</span></span></span></span> -></span> Cow<</span>'_</span>, str</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        Cow::</span></span>Borrowed(</span>self</span>.</span>as_ref</span>(</span></span>)</span></span></span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
A downside of this approach is that it will result in conflicting implementations if the user’s type already implements AsRef<str></code> but they wish for the rendered value to be different than the default str</code> implementation.</p>
Moreover, to avoid conflicting implementations, one cannot have a second implementation, such as</p>
impl</span></span><</span>P:</span> AsRef</span><</span>Path></span></span>></span></span></span> Item for</span></span> P</span> </span>{</span>
</span></span></span>    fn</span> </span>text</span></span>(</span>&</span>self</span></span>)</span></span></span></span> -></span> Cow<</span>'_</span>, str</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        self</span>.</span>as_ref</span>(</span></span>)</span></span>.</span>to_string_lossy</span>(</span></span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
since in principle a type could be AsRef<str> + AsRef<Path></code>; for example, this is the case for String</code>.
Therefore, one must make such a choice concerning the generic implementation, which may be inconvenient for a downstream user who would benefit from a different default implementation.</p>
Again using newtypes, it is possible to work around this problem: we could implement a custom wrapper type PathItem</code> and implement Item</code> for it:</p>
struct</span> </span>PathItem</span><</span>P></span></span></span></span> </span>{</span>
</span></span></span>    inner</span>:</span> P
</span></span></span></span>}</span></span></span>
</span>
</span>impl</span></span><</span>P:</span> AsRef</span><</span>Path></span></span>></span></span></span> PathItem</span><</span>P></span></span> </span>{</span>
</span></span></span>    fn</span> </span>new</span></span>(</span>inner</span>:</span> P</span>)</span></span></span></span> -></span> Self</span></span> </span>{</span>
</span></span></span></span></span>        Self</span> {</span> inner </span>}</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span>
</span>impl</span></span><</span>P:</span> AsRef</span><</span>Path></span></span>></span></span></span> Item for</span></span> PathItem</span><</span>P></span></span> </span>{</span>
</span></span></span>    fn</span> </span>text</span></span>(</span>&</span>self</span></span>)</span></span></span></span> -></span> Cow<</span>'_</span>, str</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        self</span>.</span>inner.</span>as_ref</span>(</span></span>)</span></span>.</span>to_string_lossy</span>(</span></span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
But then the user must wrap their internal type P</code> with PathItem</code> before passing it to the Picker</code>, and then unwrap the item when it is returned.</p>
</a>Inflexibility with stateful rendering patterns</h3>
The final concern, which is more serious, is that a library user may want rendering to also depend on additional dynamic state.
For example, the picker item might be a HashMap</code>, and the library user might wish to only render a subset of the keys, but still retain all of the HashMap</code> data when the item is picked.
Implementing this with an Item</code> then requires modifying the item type T</code> to contain the required rendering state, which could either result in substantial overhead or lifetime headaches.</p>
In the HashMap</code> example, one would have to do something like</p>
struct</span> </span>SubsetHashMap</span> </span>{</span>
</span></span></span>    map</span>:</span> BTreeMap<</span>String</span>, String</span>></span></span>,
</span></span></span>    allowed_fields</span>:</span> Arc<</span>HashSet<</span>String</span>></span></span>></span></span>,
</span></span></span></span>}</span></span></span>
</span>
</span>impl</span> </span>Item for</span></span> SubsetHashMap</span> </span>{</span>
</span></span></span>    fn</span> </span>text</span></span>(</span>&</span>self</span></span>)</span></span></span></span> -></span> Cow<</span>'_</span>, str</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        Cow::</span></span>Owned(</span>self</span>.</span>map
</span></span></span></span></span></span>            .</span>iter</span>(</span></span>)</span></span>
</span></span></span></span></span></span>            .</span>filter</span>(</span>|</span></span></span>(</span></span>k</span>,</span> _</span>)</span></span>|</span></span> </span>self</span>.</span>allowed_fields.</span>contains</span>(</span>k.</span>as_str</span>(</span></span>)</span></span></span>)</span></span></span></span>)</span></span>
</span></span></span></span></span></span>            .</span>map</span>(</span>|</span></span></span>(</span></span>_,</span> v</span></span>)</span></span>|</span></span> </span>v</span></span>)</span></span>
</span></span></span></span></span></span>            .</span>join</span>(</span>"</span>, "</span></span></span>)</span></span>
</span></span></span></span></span></span>            .</span>into</span>(</span></span>)</span></span></span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
but now we have the extra (unnecessary) reference counting overhead, along with a rather in-elegant SubsetHashMap</code>.</p>
</a>A closure for rendering</h2>
After understanding the issues with the Item</code> trait, it seems that we should take a different perspective on the implementation: instead of asking for the item T</code> to describe how it should be rendered, we should instead ask the user to specify a second</em> type R</code> which knows how to render T</code>.
In other words, R</code> is a rendering function</em>, so a natural choice for such a type is a closure</em>.
In our case, the natural trait bound is something like</p>
for</span><</span>'a</span>></span> Fn</span>(</span>&</span>'a</span> T</span>)</span></span> -></span> Cow<</span>'a</span>, str</span>></span></span></span>;</span>
</span></code></pre>
Now, we ask the library user to pass a rendering function directly to the picker when it is instantiated, rather than define rendering per-item.</p>
struct</span> </span>Picker</span><</span>T, R></span></span></span></span> </span>{</span>
</span></span></span>    renderer</span>:</span> R,
</span></span></span>    _marker</span>:</span> PhantomData<</span>T></span></span>, //</span> just a placeholder to make this example compile
</span></span></span></span></span>}</span></span></span>
</span>
</span>impl</span></span><</span>T, R></span></span></span> Picker</span><</span>T, R></span></span>
</span></span></span>where</span>
</span></span>    R:</span> for</span><</span>'a</span>></span></span> Fn(</span>&</span>'a</span> T)</span> -> Cow<</span>'a</span>, str</span>></span></span>,
</span></span></span>{</span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> Cow<</span>'a</span>, str</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        //</span> now we can internally render items for display
</span></span></span></span></span></span>        (</span>self</span>.</span>renderer</span>)</span></span>(</span>item</span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
This is quite close to an optimal solution and it addresses the key issues above.</p>

Implementation on foreign types requires minimal boilerplate, since we just need to write the appropriate function.</li>
The closure itself can own the relevant state by using move</code>.</li>
There is minimal memory overhead, since all of the required state is held inside the closure, which is only instantiated once.</li>
</ol>
This implementation basically de-sugars to our original Render</code> trait with the concrete Cow<'a, str></code> return type.
However, there is still one key issue with ergonomics that we would like to overcome.</p>
</a>Inflexible return type</h3>
In the above examples, we mandated a Cow<'_, str></code> return type, which is generally speaking quite sensible.
However, we might wish to allow the user even more flexibility and decide what the return type should be, as long as we can extract the desired data from it.
For instance, we would like the closure to be able to return any type which is AsRef<str></code>.
Let’s try to implement this by doing something a bit silly.</p>
struct</span> </span>Picker</span><</span>T, R></span></span></span></span> </span>{</span>
</span></span></span>    renderer</span>:</span> R,
</span></span></span>    _marker</span>:</span> PhantomData<</span>T></span></span>,
</span></span></span></span>}</span></span></span>
</span>
</span>impl</span></span><</span>T, R, S></span></span></span> Picker</span><</span>T, R></span></span>
</span></span></span>where</span>
</span></span>    S:</span> AsRef</span><</span>str</span>></span></span>,
</span></span>    R:</span> for</span><</span>'a</span>></span></span> Fn(</span>&</span>'a</span> T)</span> -> S,
</span></span></span>{</span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> S</span> </span>{</span>
</span></span></span></span></span>        //</span> now we can internally render items for display
</span></span></span></span></span></span>        (</span>self</span>.</span>renderer</span>)</span></span>(</span>item</span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
Well, let’s try it out:</p>
Picker::</span></span>new(</span>|</span></span></span>s</span>:</span> &</span>String|</span></span> </span>AsRef</span>:</span>:</span><</span>str</span>></span></span>::</span></span>as_ref(</span>s</span>)</span></span></span></span>)</span></span>;</span>
</span></code></pre>
Unfortunately, that doesn’t work:</p>
error: lifetime may not live long enough
</span>  --> src/lib.rs:59:31
</span>   |
</span>59 |     Picker::new(|s: &String| AsRef::<str>::as_ref(s));
</span>   |                     -      - ^^^^^^^^^^^^^^^^^^^^^^^ returning this value requires that `'1` must outlive `'2`
</span>   |                     |      |
</span>   |                     |      return type of closure is &'2 str
</span>   |                     let's call the lifetime of this reference `'1`
</span></code></pre>
The problem is that the type signature of the closure R</code> should also specify S</code> outlives 'a</code>, but since 'a</code> is a parameter which is only local to R</code>, we cannot capture it in the generic return type of R</code>.</p>
In fact, this (invalid) type signature has a more fundamental issue: the type parameter S</code> should not be constrained by R</code>, but rather should be an associated type</a>.
Just like the for <'a></code> lifetime bound, the type parameter S</code> should only be visible within the renderer and we should not be bounding at the Picker implementation level.
This is quite natural, since the return type of the closure should be decided by the specific implementation of the closure itself!</p>
Unfortunately, generic return types are currently2</label>Well, at least as far as I am aware, and in Rust 1.82.</small> not supported in closures.
The solution is to use a trait which imitates such a closure.</p>
</a>The solution: closure-style trait with generic associated types</h2>
First, let’s desugar the original closure type as an explicit trait:</p>
trait</span> Render</span><T> {</span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> Cow<</span>'a</span>, str</span>></span></span></span></span>;</span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
And then let’s add a generic associated type</a> to allow the user to decide on a return value which may optionally borrow from the item itself.</p>
pub</span> trait</span> Render</span><T> {</span>
</span></span></span>    type</span> Str</span><</span>'a</span>></span>:</span> AsRef</span><</span>str</span>></span></span>
</span></span></span>    where</span>
</span></span></span>        T:</span> 'a</span>;</span>
</span></span></span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> Self</span>::</span></span></span>Str<</span>'a</span>></span></span></span></span>;</span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
The where T: 'a</code> is a non-local requirement</a> since this bound is implied by the signature of render.</p>
Finally, we have the corresponding picker implementation:</p>
struct</span> </span>Picker</span><</span>T, R></span></span></span></span> </span>{</span>
</span></span></span>    renderer</span>:</span> R,
</span></span></span>    _marker</span>:</span> PhantomData<</span>T></span></span>,
</span></span></span></span>}</span></span></span>
</span>
</span>impl</span></span><</span>T, R:</span> Render<</span>T></span></span>></span></span></span> Picker</span><</span>T, R></span></span> </span>{</span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> <</span>R as</span> Render<</span>T></span></span>></span></span>::</span></span>Str<</span>'a</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        //</span> now we can internally render items for display
</span></span></span></span></span></span>        self</span>.</span>renderer.</span>render</span>(</span>item</span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
Note that the return type of Picker::render</code> cannot actually be &'a str</code>, since it is possible that the render</code> implementation could return a type which requires ownership (such as a String</code>), and then calling as_ref()</code> will return a reference to local variable which is immediately dropped.</p>
Now, for instance, if we want to render a value in terms of its Display</code> implementation, we can implement a renderer for it:</p>
pub</span> struct</span> </span>DisplayRenderer</span></span>;</span>
</span>
</span>impl</span></span><</span>T:</span> ToString</span>></span></span></span> Render<</span>T></span></span> for</span></span> DisplayRenderer</span> </span>{</span>
</span></span></span>    type</span> Str</span><</span>'a</span>></span>
</span></span></span>        =</span> String</span>
</span></span></span>    where</span>
</span></span></span>        T:</span> 'a</span>;</span>
</span></span></span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> Self</span>::</span></span></span>Str<</span>'a</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        item.</span>to_string</span>(</span></span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
And in situations when the output might borrow from the item, this is permitted using the associated lifetime:</p>
pub</span> struct</span> </span>PathRenderer</span></span>;</span>
</span>
</span>impl</span></span><</span>T:</span> AsRef</span><</span>Path></span></span>></span></span></span> Render<</span>T></span></span> for</span></span> PathRenderer</span> </span>{</span>
</span></span></span>    type</span> Str</span><</span>'a</span>></span>
</span></span></span>        =</span> Cow<</span>'a</span>, str</span>></span></span>
</span></span></span>    where</span>
</span></span></span>        T:</span> 'a</span>;</span>
</span></span></span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> Self</span>::</span></span></span>Str<</span>'a</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        item.</span>as_ref</span>(</span></span>)</span></span>.</span>to_string_lossy</span>(</span></span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
The main downside of this solution is that it is quite a bit more verbose than the closure syntax.
In particular, we lose out on closure features such as automatic variable capturing.</p>
However, we still have a final trick: we can implement Render<T></code> for closure types!</p>
impl</span></span><</span>T, R:</span> for <</span>'a</span>></span> Fn</span>(</span>&</span>'a</span> T)</span> -></span> Cow<</span>'a</span>, str</span>></span></span>></span></span></span> Render<</span>T></span></span> for</span></span> R</span> </span>{</span>
</span></span></span>    type</span> Str</span><</span>'a</span>></span>
</span></span></span>        =</span> Cow<</span>'a</span>, str</span>></span></span>
</span></span></span>    where</span>
</span></span></span>        T:</span> 'a</span>;</span>
</span></span></span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> T</span>)</span></span></span></span> -></span> Self</span>::</span></span></span>Str<</span>'a</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        self</span>(</span>item</span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
Now whenever a Render<T></code> implementation is expected, the caller can also pass an appropriate closure.</p>
</a>Comparison with other solutions</h3>
To conclude, let’s briefly go over the previous concerns with the other solutions in relation to the implementation in this section.
Some of the details in this section will go into some other implementation choices specific to nucleo-picker</code>.</p>
</a>Overhead to keep track of items</h4>
Since this implementation is generic over the item type, we can take ownership of the item internally, keep track of the association between items and the match context, and then return (a reference to) the original item to the user when complete.</p>
</a>Conversion overhead</h4>
Since we are not exposing any types into which the user should convert their data, there is no additional development overhead.</p>
</a>Extra memory overhead with lossy representation</h4>
In principle, we still have memory overhead if we want an internal representation.
In order to avoid the overhead from additionally storing the rendered representation, in nucleo-picker</code>, we assume that the Render</code> implementation is relatively efficient and simply call it again if the internal representation happens to be lossy (which is only the case in the presence of non-ASCII Unicode characters).
This is reasonable since we only need to call render</code> to generate the items which would actually be visible on the screen, which means that there is not too much pressure for optimized render performance.</p>
If render performance is exceptionally bad3</label>A generous back-of-the-envelope calculation says, if we want 60 frames per second, and the terminal has 100 lines, then the render call should take on average 0.1 ms, which is an eternity from the perspective of your computer.</small>, unfortunately in this situation the library user will probably have to implement a custom wrapper type which internally caches the rendered representation.</p>
pub</span> struct</span> </span>CachedItem</span><</span>D></span></span></span></span> </span>{</span>
</span></span></span>    data</span>:</span> D,
</span></span></span>    ///</span> the pre-computed rendered version of `data`
</span></span></span></span>    rendered</span>:</span> String,
</span></span></span></span>}</span></span></span>
</span>
</span>pub</span> struct</span> </span>CachedItemRenderer</span></span>;</span>
</span>
</span>impl</span></span><</span>D></span></span></span> Render<</span>CachedItem<</span>D></span></span>></span></span> for</span></span> CachedItemRenderer</span> </span>{</span>
</span></span></span>    type</span> Str</span><</span>'a</span>></span>
</span></span></span>        =</span> &</span>'a</span> str</span>
</span></span></span>    where</span>
</span></span></span>        D:</span> 'a</span>;</span>
</span></span></span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> Item<</span>D></span></span></span>)</span></span></span></span> -></span> Self</span>::</span></span></span>Str<</span>'a</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        &</span>item.</span>rendered
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
However, since Render</code> is only called a relatively low number of times per frame, in practice this should rarely be an issue.</p>
</a>Implementation on foreign types</h4>
Implementation on some foreign type T</code> is now easy simply by implementing the relevant Render<T></code> implementation.
Of course, there is still boilerplate required to deal with the foreign type.
However, the key difference here is that the boilerplate is restricted to the Render</code> implementation</em>: when you implement a newtype wrapper, the boilerplate corrupts every downstream method call with my_struct.0.method()</code> and introduces additional conversions to and from the relevant types.
After you implement Render<T></code>, you can proceed to forget about any types you needed to introduce to handle rendering.</p>
</a>Difficulty in default implementation</h4>
Default implementation is simple just by defining a new Render</code> trait, and does not require the user to wrap their own types in a wrapper.
Changing the render behaviour does not require modifying T</code>, and just needs a new Render</code> implementation.
Since Render</code> is otherwise entirely independent, one could in principle even depend on Render</code> implementations from entirely different crates.</p>
</a>Inflexibility with stateful rendering patterns</h4>
Since the Render</code> implementation can internally contain (dynamic) state for rendering, stateful rendering patterns are simple to implement.
The example from the earlier section would become:</p>
struct</span> </span>SubsetRenderer</span> </span>{</span>
</span></span></span>    alllowed_fields</span>:</span> HashSet<</span>String</span>></span></span>,
</span></span></span></span>}</span></span></span>
</span>
</span>impl</span> </span>Render<</span>BTreeMap<</span>String</span>, String</span>></span></span>></span></span> for</span></span> SubsetRenderer</span> </span>{</span>
</span></span></span>    type</span> Str</span><</span>'a</span>></span> =</span> String</span>;</span>
</span></span></span>
</span></span></span>    fn</span> </span>render</span></span><</span>'a</span>></span></span>(</span>&</span>self</span>, item</span>:</span> &</span>'a</span> BTreeMap<</span>String</span>, String</span>></span></span></span>)</span></span></span></span> -></span> Self</span>::</span></span></span>Str<</span>'a</span>></span></span></span> </span>{</span>
</span></span></span></span></span>        item.</span>iter</span>(</span></span>)</span></span>
</span></span></span></span></span>            .</span>filter</span>(</span>|</span></span></span>(</span></span>k</span>,</span> _</span>)</span></span>|</span></span> </span>self</span>.</span>allowed_fields.</span>contains</span>(</span>k.</span>as_str</span>(</span></span>)</span></span></span>)</span></span></span></span>)</span></span>
</span></span></span></span></span>            .</span>map</span>(</span>|</span></span></span>(</span></span>_,</span> v</span></span>)</span></span>|</span></span> </span>v</span></span>)</span></span>
</span></span></span></span></span>            .</span>join</span>(</span>"</span>, "</span></span></span>)</span></span>
</span></span></span></span></span>            .</span>into</span>(</span></span>)</span></span>
</span></span></span></span></span>    </span>}</span></span></span>
</span></span></span></span>}</span></span></span>
</span></code></pre>
</a>Inflexible return type</h4>
The return type is fully flexible and can be chosen by the user depending on the requirements for rendering the specific type.
The lifetime in the associated type ensures that the rendered value can borrow from the item, if such an optimization is relevant to the Render</code> implementation.</p>

Oath Dice and Combat Odds

2022-04-03T00:00:00+00:00

</a>The Oath combat system</h2>
Oath</a> is a great board game, which is in some sense a game about history, and in others a game about empires. If you’re not already familiar with the game, I’d highly recommend that you give it a try.
In this article, I will discuss some of the odds in the oath combat system. I will be relatively light on mathematical details: for a full derivation of the formulas, you can see my writeup</a>.
In the combat heuristics</a> section, I will discuss some good rules for estimating your odds in-game.1</label>Thank you to users @steveowen</a> and @Samuel Vriezen</a> for comments on BGG which motivated this section. In particular, the unit loss estimate</a> section gives a quick procedure you can follow to work out how many units you would expect to have left, after combat.
If you instead want to see some pre-computed unit loss tables, here are the links:

Unit difference</a></li>
Unit loss with 3 defenders</a></li>
Unit loss with 5 defenders</a></li>
Unit loss with 8 defenders</a></li> </ul>
If you use Mathematica</a>, I’ve also implemented all the distributions in this Mathematica notebook</a>.
With that out of the way, let’s see some more detail!
</a>Combat heuristics</h3>
The main insight from the odds are the zero-loss curves. Looking at the unit difference tables</a>, we can see the various defence dice / attack dice pairings which result in the attacker not having to sacrifice any units 50% of the time:

`1</var> vs. 2</var></li>`
`2</var> vs. 3</var></li>`
`3</var> vs. 4</var></li>`
`4</var> vs. 6</var></li>`
`5</var> vs. 7</var></li>`
`6</var> vs. 9</var></li>`
`7</var> vs. 12</var></li>`
`8</var> vs. 15</var></li>`
etc.</li> </ul>
Fitting a quadratic to this curve and rounding slightly, we can estimate that, when there are `n</var> defending dice, you should have 2+(n^{2-n)/4</var> attacking units in order to beat the defending dice roll 50% of the time. Now if you have a different number of attacking units, since there are 3 attacking outcomes worth 0.5, and 3 attacking outcomes worth either 1 or 2 (with unit sacrifice), for every extra attacking dice you have, you expect to get an extra 0.75 attacking power in your roll.}`
</a>Unit loss estimate</h3>
Combining these observations gives the following procedure to estimate the number of attacking units you will have remaining after combat:

Determine the number of defending dice, `n</var>, and compute the attack balance point k=2+(n^{2-n)/4</var> (for example, if there are 8 defending dice, the attack balance point is 16)</li>}`
Determine your attacking dice count, `a</var>, and compute the power adjustment 1+(k-a)·3/4</var> (for example, if you have 12 attacking dice, the power adjustment is 4)</li>`
Add the defending unit count and add the power adjustment (for example, if there are 8 defending units, the final result is 12)</li> </ol> Now, 50% of the time, you should expect to lose at most 12 units. Let’s compare this to the table computing the unit loss with 8 defenders</a>: this table states that for 8 defending dice, 8 defenders, and 13 attacking dice, you would lose 11 units 50% of the time. This estimate isn’t perfect, but it is relatively easy to compute in-game!
If you’re in a hurry and don’t want to do too much mental math, simply doing (1) will give you a good idea for the number of units you’d want to not have to sacrifice any units 50% of the time. If you want, you can also just memorize the zero-loss curve table to get a more precise estimate.
If you instead want the estimate with ≈80% certainty (instead of 50%), you can perform the same estimate by computing the attack balance point with `5 - 3n/4 + n^{2/2</var>, rounded down. And for ≈90% certainty, use 5 - 0.9 n + 0.6 n^{2</var>, rounded down. This number gets very large, very fast!}}`
Also, if you have a card which means you do not sacrifice units when you roll skulls, simply adjust the `3/4</var> factor to 11/12</var>.`
</a>Precise combat odds</h2>
</a>Combat mechanics</h3>
Combat is an important part of Oath, and the combat system is relatively straightforward, while also being feature-rich with somewhat deceptive odds. Cole Wehrle (the designer of Oath) has written about the development process</a> of the combat system.
During combat, there are two sets of dice: attacking, and defending. The sides of the dice are shown in red and blue respectively in the image below.

Oath attack and defence dice faces. © Leder Games</figcaption> </figure> The attacker has a power of the number of solid swords roll, along with half of the outlined swords (rounded down), and must sacrifice 1 unit for each skull.
The defending distribution is given by taking multiplying the number of shields by 2 for every ×2 dice roll.
</a>Computing the distributions</h3>
The full details for the probability computations can be found in this writeup</a>.
The general idea as as follows. A convenient strategy to compute probabilities involving binomial expansions is to use generating functions</a>. While this particular application does not require any sophisticated theory, the approach is conceptually nice.
For example, let’s compute the attack odds by tracking the number of skulls and swords rolled. Consider the polynomial `(3x^{½+2x+x^{2y)^{n</var>, where the coefficients are chosen as such since there are 3</var> dice with a hollow sword, 2 dice with a solid sword, and 1 dice with 2 solid swords (contributing the x^{2</var>) and 1 skull (contributing the y</var>). We count the hollow swords as ½, which we can round later.}}}}`
Then, extracting the coefficient of the term `x^{zy^{k</var> gives the number of ways to roll exactly z</var> attack points (without rounding) with k</var> skulls. Why does this work? When we compute the power of the polynomial raised to the n</var>^{th power, the resulting polynomial (without collecting terms) contains all possible choices of n</var> dice rolls,}}}`
Finally, we need to do some rounding: conveniently, it is alright to round the total, rather than the number of hollow sword rolls, since they are equivalent.
For the defence odds, suppose we are rolling n</var> dice where n=2^{m·l</var> with l</var> odd. Then the only way to roll exactly n</var> is to have k</var> dice show ×2 (for some k</var> between 0</var> and m</var>), and then roll 2^{m-k·l</var> using only shields with the remaining dice. The number of ways to roll k</var> ×2 dice is n</var> choose k</var>, and the number of ways to roll 2^{m-k·l</var> using only shields is the coefficient of x^{2^{m-k·l</var> in the polynomial (2+2x+x^{2)^{n-k</var>.}}}}}}}
</a>Summary of odds</h2>
In each entry, the rows correspond to the number of attacking dice, and the columns correspond to the number of defending dice. The three numbers are in each entry are the 50^{th, 90^{th, and 99^{th percentiles, respectively.}}}
In order to use the unit difference table</a>, choose the row with the number of attacking dice and the column with the number of defending dice. Then, for example, the second entry is is the number of units you will need to sacrifice 90% of the time in order to (strictly) overcome the defence roll power.
Other factors, such as the number of skulls rolled, as well as the defensive unit power, will influence the outcome as well. In order to estimate how many units you will lose, you need to

Look up the corresponding value in the table for your attack and defence dice counts, as well as your desired percentile.</li>
Add a number equal to ⅙ of your dice roll (this is the average loss from rolling skulls).</li>
Add the defensive unit power.</li> </ol>
The resulting number is approximately a lower bound on the number of units you will have left over after the combat. Note this does not account for the case where you roll well beyond the defensive strength, but still need to sacrifice units because of skulls. To get an idea of what these numbers look like for certain defensive unit counts, I’ve included 3 additional tables at the end of this article.
Certain cards, such as Rangers and Kindred Warriors, also allow the attacker to roll without sacrificing units from double sword dice rolls.
Some cards which allow ignoring skulls. © Leder Games</figcaption> </figure>
Since there are many possible combinations, I recommend using the `combatSummary</code> function in the` `Mathematica notebook</a>, which will report the cumulative distribution of the number of attacking units that survive.2</label>Eventually, I may write an online Javascript tool to do this computation.`
</a>Unit difference percentiles</h3> This is the distribution of the defence roll minus the attack roll. Negative numbers favour the attacker, and positive numbers favour the defender. </th> 1</th> 2</th> 3</th> 4</th> 5</th> 6</th> 7</th> 8</th> 9</th> 10</th> 11</th> 12</th></tr></thead> 1</th> 1, 2, 3</td> 2, 4, 5</td> 3, 5, 9</td> 4, 8, 13</td> 6, 12, 21</td> 7, 17, 33</td> 9, 24, 48</td> 12, 32, 65</td> 15, 41, 97</td> 19, 56, 129</td> 24, 71, 192</td> 29, 89, 256</td></tr> 2</th> 0, 1, 2</td> 1, 3, 4</td> 2, 4, 8</td> 3, 8, 12</td> 5, 11, 20</td> 6, 16, 32</td> 8, 23, 47</td> 12, 31, 64</td> 15, 40, 96</td> 18, 55, 128</td> 23, 70, 191</td> 28, 88, 255</td></tr> 3</th> -1, 1, 2</td> 0, 2, 4</td> 1, 4, 7</td> 2, 7, 12</td> 4, 10, 19</td> 6, 15, 31</td> 8, 22, 46</td> 11, 30, 63</td> 14, 39, 95</td> 17, 54, 127</td> 22, 69, 190</td> 27, 87, 254</td></tr> 4</th> -2, 0, 1</td> -1, 1, 3</td> 0, 3, 6</td> 1, 6, 11</td> 3, 9, 19</td> 5, 14, 30</td> 7, 21, 45</td> 10, 29, 62</td> 13, 38, 94</td> 16, 53, 126</td> 21, 68, 189</td> 26, 87, 253</td></tr> 5</th> -3, -1, 0</td> -2, 0, 2</td> -1, 2, 5</td> 1, 5, 10</td> 2, 8, 18</td> 4, 13, 29</td> 6, 20, 45</td> 9, 28, 61</td> 12, 37, 93</td> 15, 52, 125</td> 20, 67, 188</td> 25, 86, 252</td></tr> 6</th> -4, -2, 0</td> -3, 0, 1</td> -2, 1, 4</td> 0, 4, 9</td> 1, 7, 17</td> 3, 12, 28</td> 5, 19, 44</td> 8, 27, 61</td> 11, 36, 92</td> 15, 51, 124</td> 19, 65, 187</td> 25, 85, 251</td></tr> 7</th> -4, -2, -1</td> -4, -1, 1</td> -3, 0, 4</td> -1, 3, 8</td> 0, 7, 16</td> 2, 11, 27</td> 4, 18, 43</td> 7, 26, 60</td> 10, 35, 91</td> 14, 50, 123</td> 18, 64, 186</td> 24, 84, 250</td></tr> 8</th> -5, -3, -2</td> -4, -2, 0</td> -3, 0, 3</td> -2, 2, 8</td> -1, 6, 15</td> 1, 10, 26</td> 3, 17, 42</td> 6, 25, 59</td> 9, 34, 90</td> 13, 49, 123</td> 17, 63, 185</td> 23, 84, 249</td></tr> 9</th> -6, -4, -3</td> -5, -3, -1</td> -4, -1, 2</td> -3, 1, 7</td> -2, 5, 14</td> 0, 9, 25</td> 2, 16, 41</td> 5, 24, 58</td> 8, 33, 89</td> 12, 48, 122</td> 16, 62, 184</td> 22, 83, 248</td></tr> 10</th> -7, -5, -3</td> -6, -4, -2</td> -5, -2, 1</td> -4, 0, 6</td> -2, 4, 13</td> -1, 8, 24</td> 1, 15, 40</td> 4, 23, 57</td> 7, 33, 88</td> 11, 47, 121</td> 15, 61, 183</td> 21, 82, 247</td></tr> 11</th> -8, -6, -4</td> -7, -5, -3</td> -6, -3, 0</td> -5, 0, 5</td> -3, 3, 12</td> -2, 8, 23</td> 1, 14, 39</td> 3, 22, 56</td> 6, 32, 87</td> 10, 46, 120</td> 14, 60, 182</td> 20, 81, 246</td></tr> 12</th> -9, -7, -5</td> -8, -5, -3</td> -7, -4, -1</td> -6, -1, 4</td> -4, 2, 11</td> -2, 7, 22</td> 0, 13, 38</td> 2, 21, 55</td> 5, 31, 86</td> 9, 45, 119</td> 14, 59, 181</td> 19, 80, 245</td></tr> 13</th> -10, -7, -6</td> -9, -6, -4</td> -8, -5, -1</td> -7, -2, 3</td> -5, 1, 11</td> -3, 6, 22</td> -1, 12, 37</td> 1, 20, 55</td> 5, 30, 86</td> 8, 44, 118</td> 13, 58, 180</td> 18, 79, 244</td></tr> 14</th> -11, -8, -6</td> -10, -7, -5</td> -9, -5, -2</td> -8, -3, 2</td> -6, 0, 10</td> -4, 5, 21</td> -2, 11, 36</td> 1, 19, 54</td> 4, 29, 85</td> 7, 43, 117</td> 12, 57, 179</td> 17, 78, 243</td></tr> 15</th> -12, -9, -7</td> -11, -8, -6</td> -10, -6, -3</td> -8, -4, 2</td> -7, -1, 9</td> -5, 4, 20</td> -3, 10, 35</td> 0, 18, 53</td> 3, 28, 84</td> 6, 42, 116</td> 11, 56, 178</td> 16, 78, 242</td></tr> 16</th> -13, -10, -8</td> -12, -9, -6</td> -11, -7, -4</td> -9, -5, 1</td> -8, -1, 8</td> -6, 3, 19</td> -4, 9, 34</td> -1, 17, 52</td> 2, 27, 83</td> 5, 41, 115</td> 10, 55, 177</td> 15, 77, 241</td></tr> 17</th> -14, -11, -9</td> -13, -10, -7</td> -12, -8, -5</td> -10, -6, 0</td> -9, -2, 7</td> -7, 2, 18</td> -5, 8, 33</td> -2, 16, 51</td> 1, 26, 82</td> 5, 40, 115</td> 9, 54, 176</td> 15, 76, 240</td></tr> 18</th> -14, -12, -9</td> -14, -10, -8</td> -13, -9, -6</td> -11, -7, -1</td> -10, -3, 6</td> -8, 1, 17</td> -6, 8, 32</td> -3, 15, 50</td> 0, 25, 81</td> 4, 39, 114</td> 8, 53, 175</td> 14, 75, 239</td></tr> 19</th> -15, -12, -10</td> -15, -11, -9</td> -13, -10, -6</td> -12, -7, -2</td> -11, -4, 5</td> -9, 0, 16</td> -7, 7, 31</td> -4, 15, 49</td> -1, 24, 80</td> 3, 38, 113</td> 7, 53, 174</td> 13, 74, 238</td></tr> 20</th> -16, -13, -11</td> -15, -12, -10</td> -14, -11, -7</td> -13, -8, -3</td> -11, -5, 4</td> -10, 0, 15</td> -8, 6, 30</td> -5, 14, 48</td> -2, 24, 79</td> 2, 37, 112</td> 6, 52, 173</td> 12, 73, 237</td></tr> 21</th> -17, -14, -12</td> -16, -13, -10</td> -15, -11, -8</td> -14, -9, -4</td> -12, -6, 3</td> -11, -1, 14</td> -8, 5, 30</td> -6, 13, 47</td> -3, 23, 78</td> 1, 36, 111</td> 5, 51, 172</td> 11, 72, 236</td></tr> 22</th> -18, -15, -13</td> -17, -14, -11</td> -16, -12, -9</td> -15, -10, -4</td> -13, -7, 2</td> -11, -2, 13</td> -9, 4, 29</td> -7, 12, 47</td> -4, 22, 77</td> 0, 35, 110</td> 4, 50, 171</td> 10, 71, 235</td></tr> 23</th> -19, -16, -13</td> -18, -15, -12</td> -17, -13, -10</td> -16, -11, -5</td> -14, -8, 2</td> -12, -3, 12</td> -10, 3, 28</td> -8, 11, 46</td> -5, 21, 76</td> -1, 34, 109</td> 4, 49, 170</td> 9, 70, 234</td></tr> 24</th> -20, -17, -14</td> -19, -16, -13</td> -18, -14, -11</td> -17, -12, -6</td> -15, -9, 1</td> -13, -4, 12</td> -11, 2, 27</td> -9, 10, 45</td> -5, 20, 75</td> -2, 33, 108</td> 3, 48, 169</td> 8, 70, 234</td></tr> 25</th> -21, -18, -15</td> -20, -16, -14</td> -19, -15, -11</td> -18, -13, -7</td> -16, -9, 0</td> -14, -5, 11</td> -12, 1, 26</td> -9, 9, 44</td> -6, 19, 75</td> -3, 32, 107</td> 2, 47, 168</td> 7, 69, 233</td></tr></tbody></table> </a>Unit loss with 3 defenders</h3> This is a table of the attacking unit loss given that there are 3 defenders. </th> 1</th> 2</th> 3</th> 4</th> 5</th> 6</th> 7</th> 8</th> 9</th> 10</th> 11</th> 12</th></tr></thead> 1</th> 4, 5, 6</td> 5, 7, 8</td> 6, 9, 12</td> 7, 11, 16</td> 9, 15, 24</td> 11, 20, 36</td> 13, 27, 51</td> 15, 35, 68</td> 19, 44, 100</td> 23, 59, 132</td> 27, 75, 195</td> 32, 92, 259</td></tr> 2</th> 3, 5, 5</td> 4, 6, 7</td> 5, 8, 11</td> 7, 11, 15</td> 8, 15, 23</td> 10, 19, 35</td> 12, 26, 51</td> 15, 34, 67</td> 18, 43, 99</td> 22, 58, 131</td> 26, 74, 194</td> 31, 91, 258</td></tr> 3</th> 3, 4, 5</td> 4, 5, 7</td> 5, 7, 10</td> 6, 10, 15</td> 7, 14, 22</td> 9, 18, 34</td> 11, 26, 50</td> 14, 34, 66</td> 18, 42, 98</td> 21, 58, 130</td> 26, 73, 194</td> 30, 90, 258</td></tr> 4</th> 2, 3, 4</td> 3, 5, 6</td> 4, 6, 9</td> 5, 9, 14</td> 7, 13, 22</td> 9, 17, 33</td> 10, 25, 49</td> 13, 33, 66</td> 17, 41, 97</td> 20, 57, 129</td> 25, 72, 193</td> 30, 90, 257</td></tr> 5</th> 1, 3, 3</td> 2, 4, 5</td> 3, 6, 9</td> 4, 8, 13</td> 6, 12, 21</td> 8, 17, 33</td> 10, 24, 48</td> 12, 32, 65</td> 16, 41, 97</td> 19, 56, 129</td> 24, 72, 192</td> 29, 89, 256</td></tr> 6</th> 1, 2, 3</td> 2, 3, 4</td> 3, 5, 8</td> 4, 8, 13</td> 5, 11, 20</td> 7, 16, 32</td> 9, 23, 48</td> 12, 31, 64</td> 15, 40, 96</td> 19, 55, 128</td> 23, 71, 191</td> 28, 88, 255</td></tr> 7</th> 1, 2, 4</td> 2, 3, 4</td> 2, 4, 7</td> 3, 7, 12</td> 4, 11, 20</td> 6, 15, 31</td> 8, 22, 47</td> 11, 30, 63</td> 14, 39, 95</td> 18, 54, 127</td> 23, 70, 190</td> 27, 88, 255</td></tr> 8</th> 1, 3, 4</td> 1, 3, 4</td> 2, 4, 7</td> 3, 6, 11</td> 4, 10, 19</td> 5, 14, 30</td> 7, 22, 46</td> 10, 30, 63</td> 14, 38, 94</td> 17, 54, 127</td> 22, 69, 190</td> 27, 87, 254</td></tr> 9</th> 1, 3, 4</td> 1, 3, 4</td> 2, 4, 6</td> 2, 5, 10</td> 3, 9, 18</td> 5, 14, 30</td> 7, 21, 45</td> 9, 29, 62</td> 13, 38, 94</td> 16, 53, 126</td> 21, 68, 189</td> 26, 86, 253</td></tr> 10</th> 2, 3, 5</td> 2, 3, 5</td> 2, 4, 5</td> 2, 5, 10</td> 3, 8, 17</td> 4, 13, 29</td> 6, 20, 45</td> 9, 28, 61</td> 12, 37, 93</td> 16, 52, 125</td> 20, 68, 188</td> 25, 86, 252</td></tr> 11</th> 2, 3, 5</td> 2, 3, 5</td> 2, 4, 5</td> 2, 4, 9</td> 3, 8, 17</td> 4, 12, 28</td> 5, 19, 44</td> 8, 27, 60</td> 11, 36, 92</td> 15, 51, 124</td> 19, 67, 187</td> 25, 85, 251</td></tr> 12</th> 2, 4, 5</td> 2, 4, 5</td> 2, 4, 5</td> 2, 4, 8</td> 3, 7, 16</td> 3, 11, 27</td> 5, 18, 43</td> 7, 27, 60</td> 11, 35, 91</td> 14, 51, 124</td> 19, 66, 186</td> 24, 84, 251</td></tr> 13</th> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 8</td> 3, 6, 15</td> 3, 11, 27</td> 4, 18, 42</td> 7, 26, 59</td> 10, 35, 91</td> 13, 50, 123</td> 18, 65, 186</td> 23, 83, 250</td></tr> 14</th> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 7</td> 3, 6, 14</td> 3, 10, 26</td> 4, 17, 42</td> 6, 25, 58</td> 9, 34, 90</td> 13, 49, 122</td> 17, 64, 185</td> 22, 83, 249</td></tr> 15</th> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 6</td> 2, 5, 7</td> 3, 6, 14</td> 3, 9, 25</td> 4, 16, 41</td> 5, 24, 58</td> 8, 33, 89</td> 12, 48, 121</td> 16, 63, 184</td> 22, 82, 248</td></tr> 16</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 13</td> 3, 8, 24</td> 4, 15, 40</td> 5, 23, 57</td> 8, 32, 88</td> 11, 47, 121</td> 16, 63, 183</td> 21, 81, 248</td></tr> 17</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 6, 12</td> 3, 8, 24</td> 4, 15, 39</td> 5, 23, 56</td> 7, 32, 88</td> 10, 47, 120</td> 15, 62, 183</td> 20, 81, 247</td></tr> 18</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 6, 12</td> 3, 7, 23</td> 4, 14, 39</td> 5, 22, 55</td> 6, 31, 87</td> 10, 46, 119</td> 14, 61, 182</td> 19, 80, 246</td></tr> 19</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 6, 11</td> 3, 7, 22</td> 4, 13, 38</td> 5, 21, 55</td> 6, 30, 86</td> 9, 45, 118</td> 13, 60, 181</td> 19, 79, 245</td></tr> 20</th> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 10</td> 4, 7, 21</td> 4, 12, 37</td> 5, 20, 54</td> 6, 29, 85</td> 8, 44, 118</td> 13, 59, 180</td> 18, 78, 244</td></tr> 21</th> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 10</td> 4, 7, 21</td> 4, 12, 36</td> 5, 20, 53</td> 6, 29, 85</td> 8, 44, 117</td> 12, 59, 179</td> 17, 78, 244</td></tr> 22</th> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 10</td> 4, 7, 20</td> 4, 11, 35</td> 5, 19, 52</td> 5, 28, 84</td> 7, 43, 116</td> 11, 58, 179</td> 16, 77, 243</td></tr> 23</th> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 10</td> 4, 7, 19</td> 4, 10, 35</td> 5, 18, 52</td> 5, 27, 83</td> 7, 42, 115</td> 10, 57, 178</td> 16, 76, 242</td></tr> 24</th> 4, 6, 9</td> 4, 6, 9</td> 4, 6, 9</td> 4, 6, 9</td> 4, 7, 9</td> 4, 7, 18</td> 4, 9, 34</td> 5, 17, 51</td> 6, 27, 82</td> 7, 41, 115</td> 10, 56, 177</td> 15, 76, 241</td></tr> 25</th> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 18</td> 4, 9, 33</td> 5, 17, 50</td> 6, 26, 82</td> 7, 41, 114</td> 9, 56, 176</td> 14, 75, 241</td></tr></tbody></table> </a>Unit loss with 5 defenders</h3> This is a table of the attacking unit loss given that there are 5 defenders. </th> 1</th> 2</th> 3</th> 4</th> 5</th> 6</th> 7</th> 8</th> 9</th> 10</th> 11</th> 12</th></tr></thead> 1</th> 6, 7, 8</td> 7, 9, 10</td> 8, 11, 14</td> 9, 13, 18</td> 11, 17, 26</td> 13, 22, 38</td> 15, 29, 53</td> 17, 37, 70</td> 21, 46, 102</td> 25, 61, 134</td> 29, 77, 197</td> 34, 94, 261</td></tr> 2</th> 5, 7, 7</td> 6, 8, 9</td> 7, 10, 13</td> 9, 13, 17</td> 10, 17, 25</td> 12, 21, 37</td> 14, 28, 53</td> 17, 36, 69</td> 20, 45, 101</td> 24, 60, 133</td> 28, 76, 196</td> 33, 93, 260</td></tr> 3</th> 5, 6, 7</td> 6, 7, 9</td> 7, 9, 12</td> 8, 12, 17</td> 9, 16, 24</td> 11, 20, 36</td> 13, 28, 52</td> 16, 36, 68</td> 20, 44, 100</td> 23, 60, 132</td> 28, 75, 196</td> 32, 92, 260</td></tr> 4</th> 4, 5, 6</td> 5, 7, 8</td> 6, 8, 11</td> 7, 11, 16</td> 9, 15, 24</td> 11, 19, 35</td> 12, 27, 51</td> 15, 35, 68</td> 19, 43, 99</td> 22, 59, 131</td> 27, 74, 195</td> 32, 92, 259</td></tr> 5</th> 3, 4, 5</td> 4, 6, 7</td> 5, 8, 11</td> 6, 10, 15</td> 8, 14, 23</td> 10, 19, 35</td> 12, 26, 50</td> 14, 34, 67</td> 18, 43, 99</td> 21, 58, 131</td> 26, 74, 194</td> 31, 91, 258</td></tr> 6</th> 2, 4, 5</td> 3, 5, 6</td> 4, 7, 10</td> 6, 10, 15</td> 7, 13, 22</td> 9, 18, 34</td> 11, 25, 50</td> 14, 33, 66</td> 17, 42, 98</td> 21, 57, 130</td> 25, 73, 193</td> 30, 90, 257</td></tr> 7</th> 2, 3, 4</td> 3, 4, 6</td> 4, 6, 9</td> 5, 9, 14</td> 6, 13, 22</td> 8, 17, 33</td> 10, 24, 49</td> 13, 32, 65</td> 16, 41, 97</td> 20, 56, 129</td> 25, 72, 192</td> 29, 90, 257</td></tr> 8</th> 2, 3, 4</td> 2, 4, 5</td> 3, 5, 9</td> 4, 8, 13</td> 6, 12, 21</td> 7, 16, 32</td> 9, 24, 48</td> 12, 32, 65</td> 16, 40, 96</td> 19, 56, 129</td> 24, 71, 192</td> 29, 89, 256</td></tr> 9</th> 2, 3, 4</td> 2, 4, 5</td> 3, 5, 8</td> 4, 7, 12</td> 5, 11, 20</td> 7, 16, 32</td> 9, 23, 47</td> 11, 31, 64</td> 15, 40, 96</td> 18, 55, 128</td> 23, 70, 191</td> 28, 88, 255</td></tr> 10</th> 2, 3, 5</td> 2, 3, 5</td> 2, 4, 7</td> 3, 7, 12</td> 4, 10, 19</td> 6, 15, 31</td> 8, 22, 47</td> 11, 30, 63</td> 14, 39, 95</td> 18, 54, 127</td> 22, 70, 190</td> 27, 88, 254</td></tr> 11</th> 2, 3, 5</td> 2, 3, 5</td> 2, 4, 6</td> 3, 6, 11</td> 4, 10, 19</td> 5, 14, 30</td> 7, 21, 46</td> 10, 29, 62</td> 13, 38, 94</td> 17, 53, 126</td> 21, 69, 189</td> 27, 87, 253</td></tr> 12</th> 2, 4, 5</td> 2, 4, 5</td> 2, 4, 6</td> 3, 5, 10</td> 3, 9, 18</td> 5, 13, 29</td> 6, 20, 45</td> 9, 29, 62</td> 13, 37, 93</td> 16, 53, 126</td> 21, 68, 188</td> 26, 86, 253</td></tr> 13</th> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 6</td> 3, 5, 10</td> 3, 8, 17</td> 4, 13, 29</td> 6, 20, 44</td> 8, 28, 61</td> 12, 37, 93</td> 15, 52, 125</td> 20, 67, 188</td> 25, 85, 252</td></tr> 14</th> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 6</td> 3, 5, 9</td> 3, 7, 16</td> 4, 12, 28</td> 5, 19, 44</td> 8, 27, 60</td> 11, 36, 92</td> 15, 51, 124</td> 19, 66, 187</td> 24, 85, 251</td></tr> 15</th> 2, 4, 6</td> 2, 4, 6</td> 2, 4, 6</td> 3, 5, 8</td> 3, 7, 16</td> 4, 11, 27</td> 5, 18, 43</td> 7, 26, 60</td> 10, 35, 91</td> 14, 50, 123</td> 18, 65, 186</td> 24, 84, 250</td></tr> 16</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 8</td> 3, 6, 15</td> 4, 10, 26</td> 5, 17, 42</td> 6, 25, 59</td> 9, 34, 90</td> 13, 49, 123</td> 18, 65, 185</td> 23, 83, 250</td></tr> 17</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 8</td> 3, 6, 14</td> 4, 10, 26</td> 4, 17, 41</td> 6, 25, 58</td> 9, 34, 90</td> 12, 49, 122</td> 17, 64, 185</td> 22, 83, 249</td></tr> 18</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 8</td> 3, 6, 14</td> 4, 9, 25</td> 4, 16, 41</td> 6, 24, 57</td> 8, 33, 89</td> 12, 48, 121</td> 16, 63, 184</td> 21, 82, 248</td></tr> 19</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 8</td> 3, 6, 13</td> 4, 8, 24</td> 4, 15, 40</td> 5, 23, 57</td> 7, 32, 88</td> 11, 47, 120</td> 15, 62, 183</td> 21, 81, 247</td></tr> 20</th> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 12</td> 4, 8, 23</td> 4, 14, 39</td> 5, 22, 56</td> 7, 31, 87</td> 10, 46, 120</td> 15, 61, 182</td> 20, 80, 246</td></tr> 21</th> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 4, 6, 11</td> 4, 7, 23</td> 4, 14, 38</td> 5, 22, 55</td> 6, 31, 87</td> 9, 46, 119</td> 14, 61, 181</td> 19, 80, 246</td></tr> 22</th> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 11</td> 4, 7, 22</td> 4, 13, 37</td> 5, 21, 54</td> 6, 30, 86</td> 9, 45, 118</td> 13, 60, 181</td> 18, 79, 245</td></tr> 23</th> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 10</td> 4, 7, 21</td> 4, 12, 37</td> 5, 20, 54</td> 6, 29, 85</td> 8, 44, 117</td> 12, 59, 180</td> 18, 78, 244</td></tr> 24</th> 4, 6, 9</td> 4, 6, 9</td> 4, 6, 9</td> 4, 6, 9</td> 4, 7, 10</td> 4, 7, 20</td> 5, 11, 36</td> 5, 19, 53</td> 6, 29, 84</td> 8, 43, 117</td> 12, 58, 179</td> 17, 78, 243</td></tr> 25</th> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 10</td> 4, 7, 20</td> 5, 11, 35</td> 5, 19, 52</td> 6, 28, 84</td> 7, 43, 116</td> 11, 58, 178</td> 16, 77, 243</td></tr></tbody></table> </a>Unit loss with 8 defenders</h3> This is a table of the attacking unit loss given that there are 8 defenders. </th> 1</th> 2</th> 3</th> 4</th> 5</th> 6</th> 7</th> 8</th> 9</th> 10</th> 11</th> 12</th></tr></thead> 1</th> 9, 10, 11</td> 10, 12, 13</td> 11, 14, 17</td> 12, 16, 21</td> 14, 20, 29</td> 16, 25, 41</td> 18, 32, 56</td> 20, 40, 73</td> 24, 49, 105</td> 28, 64, 137</td> 32, 80, 200</td> 37, 97, 264</td></tr> 2</th> 8, 10, 10</td> 9, 11, 12</td> 10, 13, 16</td> 12, 16, 20</td> 13, 20, 28</td> 15, 24, 40</td> 17, 31, 56</td> 20, 39, 72</td> 23, 48, 104</td> 27, 63, 136</td> 31, 79, 199</td> 36, 96, 263</td></tr> 3</th> 8, 9, 10</td> 9, 10, 12</td> 10, 12, 15</td> 11, 15, 20</td> 12, 19, 27</td> 14, 23, 39</td> 16, 31, 55</td> 19, 39, 71</td> 23, 47, 103</td> 26, 63, 135</td> 31, 78, 199</td> 35, 95, 263</td></tr> 4</th> 7, 8, 9</td> 8, 10, 11</td> 9, 11, 14</td> 10, 14, 19</td> 12, 18, 27</td> 14, 22, 38</td> 15, 30, 54</td> 18, 38, 71</td> 22, 46, 102</td> 25, 62, 134</td> 30, 77, 198</td> 35, 95, 262</td></tr> 5</th> 6, 7, 8</td> 7, 9, 10</td> 8, 11, 14</td> 9, 13, 18</td> 11, 17, 26</td> 13, 22, 38</td> 15, 29, 53</td> 17, 37, 70</td> 21, 46, 102</td> 24, 61, 134</td> 29, 77, 197</td> 34, 94, 261</td></tr> 6</th> 5, 7, 8</td> 6, 8, 9</td> 7, 10, 13</td> 9, 13, 18</td> 10, 16, 25</td> 12, 21, 37</td> 14, 28, 53</td> 17, 36, 69</td> 20, 45, 101</td> 24, 60, 133</td> 28, 76, 196</td> 33, 93, 260</td></tr> 7</th> 5, 6, 7</td> 6, 7, 9</td> 7, 9, 12</td> 8, 12, 17</td> 9, 16, 25</td> 11, 20, 36</td> 13, 27, 52</td> 16, 35, 68</td> 19, 44, 100</td> 23, 59, 132</td> 28, 75, 195</td> 32, 93, 260</td></tr> 8</th> 4, 5, 6</td> 5, 7, 8</td> 6, 8, 12</td> 7, 11, 16</td> 9, 15, 24</td> 10, 19, 35</td> 12, 27, 51</td> 15, 35, 68</td> 19, 43, 99</td> 22, 59, 132</td> 27, 74, 195</td> 32, 92, 259</td></tr> 9</th> 3, 5, 6</td> 4, 6, 7</td> 5, 8, 11</td> 6, 10, 15</td> 8, 14, 23</td> 10, 19, 35</td> 12, 26, 50</td> 14, 34, 67</td> 18, 43, 99</td> 21, 58, 131</td> 26, 73, 194</td> 31, 91, 258</td></tr> 10</th> 3, 4, 5</td> 3, 5, 7</td> 4, 7, 10</td> 6, 10, 15</td> 7, 13, 22</td> 9, 18, 34</td> 11, 25, 50</td> 14, 33, 66</td> 17, 42, 98</td> 21, 57, 130</td> 25, 73, 193</td> 30, 91, 257</td></tr> 11</th> 2, 4, 5</td> 3, 5, 6</td> 4, 6, 9</td> 5, 9, 14</td> 6, 13, 22</td> 8, 17, 33</td> 10, 24, 49</td> 13, 32, 65</td> 16, 41, 97</td> 20, 56, 129</td> 24, 72, 192</td> 30, 90, 256</td></tr> 12</th> 2, 4, 5</td> 3, 4, 6</td> 3, 6, 9</td> 4, 8, 13</td> 6, 12, 21</td> 7, 16, 32</td> 9, 23, 48</td> 12, 32, 65</td> 16, 40, 96</td> 19, 56, 129</td> 24, 71, 191</td> 29, 89, 256</td></tr> 13</th> 2, 4, 6</td> 3, 4, 6</td> 3, 5, 8</td> 4, 7, 13</td> 5, 11, 20</td> 7, 16, 32</td> 9, 23, 47</td> 11, 31, 64</td> 15, 40, 96</td> 18, 55, 128</td> 23, 70, 191</td> 28, 88, 255</td></tr> 14</th> 2, 4, 6</td> 2, 4, 6</td> 3, 5, 7</td> 4, 7, 12</td> 4, 10, 19</td> 6, 15, 31</td> 8, 22, 47</td> 11, 30, 63</td> 14, 39, 95</td> 18, 54, 127</td> 22, 69, 190</td> 27, 88, 254</td></tr> 15</th> 2, 4, 6</td> 2, 4, 6</td> 3, 5, 7</td> 3, 6, 11</td> 4, 10, 19</td> 5, 14, 30</td> 7, 21, 46</td> 10, 29, 63</td> 13, 38, 94</td> 17, 53, 126</td> 21, 68, 189</td> 27, 87, 253</td></tr> 16</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 6, 10</td> 4, 9, 18</td> 5, 13, 29</td> 7, 20, 45</td> 9, 28, 62</td> 12, 37, 93</td> 16, 52, 126</td> 21, 68, 188</td> 26, 86, 253</td></tr> 17</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 6, 10</td> 4, 8, 17</td> 5, 13, 29</td> 6, 20, 44</td> 9, 28, 61</td> 12, 37, 93</td> 15, 52, 125</td> 20, 67, 188</td> 25, 86, 252</td></tr> 18</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 6, 9</td> 4, 8, 17</td> 4, 12, 28</td> 6, 19, 44</td> 8, 27, 60</td> 11, 36, 92</td> 15, 51, 124</td> 19, 66, 187</td> 24, 85, 251</td></tr> 19</th> 3, 5, 7</td> 3, 5, 7</td> 3, 5, 7</td> 3, 6, 9</td> 4, 7, 16</td> 4, 11, 27</td> 5, 18, 43</td> 7, 26, 60</td> 10, 35, 91</td> 14, 50, 123</td> 18, 65, 186</td> 24, 84, 250</td></tr> 20</th> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 9</td> 4, 7, 15</td> 4, 10, 26</td> 5, 17, 42</td> 7, 25, 59</td> 9, 34, 90</td> 13, 49, 123</td> 18, 64, 185</td> 23, 83, 249</td></tr> 21</th> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 8</td> 3, 6, 9</td> 4, 7, 14</td> 4, 10, 26</td> 5, 17, 41</td> 6, 25, 58</td> 9, 34, 90</td> 12, 49, 122</td> 17, 64, 184</td> 22, 83, 249</td></tr> 22</th> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 9</td> 4, 7, 14</td> 4, 9, 25</td> 5, 16, 40</td> 6, 24, 57</td> 8, 33, 89</td> 12, 48, 121</td> 16, 63, 184</td> 21, 82, 248</td></tr> 23</th> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 8</td> 4, 6, 9</td> 4, 7, 13</td> 4, 9, 24</td> 5, 15, 40</td> 6, 23, 57</td> 8, 32, 88</td> 11, 47, 120</td> 15, 62, 183</td> 21, 81, 247</td></tr> 24</th> 4, 6, 9</td> 4, 6, 9</td> 4, 6, 9</td> 4, 6, 9</td> 4, 7, 12</td> 4, 8, 23</td> 5, 14, 39</td> 6, 22, 56</td> 7, 32, 87</td> 10, 46, 120</td> 15, 61, 182</td> 20, 81, 246</td></tr> 25</th> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 9</td> 4, 7, 12</td> 4, 8, 23</td> 5, 13, 38</td> 6, 22, 55</td> 7, 31, 87</td> 9, 46, 119</td> 14, 61, 181</td> 19, 80, 246</td></tr></tbody></table> How to Build a Personal Webpage from Scratch 2022-02-16T00:00:00+00:00 </a>An overview of static webpage development</h2> </a>What is a static webpage?</h3> Modern webpages are (primarily) composed of three types of files: HTML, CSS, and JavaScript. Basically, HTML specifies the content,</li> CSS defines the style, and</li> JavaScript allows dynamic behaviour.</li> </ul> Webpages also consist of additional resources, such as images or documents. When you visit a webpage, your web browser requests the documents from a server. Static</a> and dynamic</a> webpages differ in how the files are prepared before they are sent to the visitor. A static webpage is essentially a collection of files sitting on the server, which are sent directly to the webpage visitor, whereas a (server-side1</label>This is in contrast to a client-side dynamic webpage which uses JavaScript, but only in your web browser.) dynamic webpage typically consists of a database as well as code to generate the files on the fly2</label>This code can either run in your browser, or the page rendering itself can happen on the server. when they are requested by the visitor. For example, this website is a static webpage. On the other hand, any webpage which allows you to log-in and have user-specific state is a dynamic webpage. The majority of web pages on the internet are dynamic webpages. When building a static webpage, you can simply prepare the entire webpage as a directory containing files. In fact, you can make a webpage (using your own device as the server) simply by writing a bit of HTML with no CSS or JavaScript: create a file named index.html</code> with the contents <html><body>content</body></html> </code></pre> and, when you double-click on the file, it should open in your browser and show a (rather minimal) page displaying the line “content”. Dynamic webpages are built in a similar way, except rather than generating the pages in advance, the files sent to the visitor are generated as they are requested. A dynamic webpage will typically have a database</a> used to store the site information, and a web server which uses the database to generate content when requested by the user. This allows substantially more flexibility in content delivery (e.g. webpage state, customization for the viewer, etc.) since the content delivered to the webpage can depend on arbitrary variables whose values are unknown when creating the site. This also allows procedural generation of content, which avoids repetitive code. The main downside is that, since the pages need to be generated for each visitor, dynamic websites are typically more resource intensive and slower to render. </a>Why static webpages?</h3> However, for a personal blog or site used primarily to distribute information, rather than collect it, dynamic content generation is not necessary! Here is a short list of reasons why you should prefer simple static webpages (if you do not already know that you require a dynamic webpage): Longevity. A static webpage is just a collection of files, which you should also have saved on your computer. So even in the worst case scenario—say your web server disappears—you still have the files for your webpage and you can just put them up somewhere else. Static webpages are also easier to maintain: if you have a dynamic webpage, you need to keep the required tools up to date otherwise everything will cease to work.</li> Portability. If you decide that you want to host your webpage somewhere else, this is straightforward to do. Static webpages are also simple enough that you can host them yourself on a low-power device!</li> Security. Since static webpages are substantially simpler, they have a smaller attack surface and are more secure. There is no underlying server serving requests, or processing user input. Even in hosted situations, there can be problems with the underlying content management system. For example, many Wordpress sites were compromised</a> through an exploit which targeted the plugin system.</li> </ul> </a>Template processing</h3> One downside of manually preparing a webpage is that there is often a large amount of repetition: for example, each article</a> on this webpage has different content but many shared layout features. In order to simplify this process, a common technique is to use a template processor</a>. This is a program which takes files written in a templating language (such as Jinja</a> or Tera</a>), combined with content files written in a markup language (such as Markdown</a>) and converts them into HTML, CSS, and JavaScript files. You first prepare the templates, then write the content files, and then use the template processor to generate the webpage files. </a>Static website components</h3> There are three main components to static website generation: Templating. You should choose a templating engine and then prepare the website template. I am personally a fan of Zola</a>; some other common options are Jekyll</a> and Hugo</a>.</li> Content. The most important part of a webpage is the content! Beyond that, it’s nice if your webpage also looks decent. You need to write base HTML files and CSS style sheets, as well as the webpage content.</li> Deployment. While it is possible (and not too difficult) to host your own static site server, it is typically easiest to use static site hosting. I use Cloudflare Pages</a>. You might also be interested in GitHub Pages</a> or Netlify</a>.</li> </ol> Of course, templating is mainly a convenience feature, and not strictly necessary when making a small website. I’ll discuss the other two components in the following sections, along with some additional topics in the final section</a>. </a>A note on editing text</h3> HTML is a markup language</a>, which means that the text represents content, rather than being the content visually. Other well-known markup languages include LaTeX</a> and Markdown</a>. Therefore when writing content for your webpage, it is important to use an editor which accurately represents the contents of the file you are editing. This is in contrast to software such as Microsoft Word, in which the content that you enter on the page is different than the underlying representation. Some popular graphical text editors include Atom</a> and Sublime Text</a>. If you do not want to install anything, Notepad</a> is a built-in text editor on Windows. Similarly, TextEdit</a> is built-in on macOS. If you prefer a command-line interface, you could consider Neovim</a> or Emacs</a>. One subtlety is that not all text is the same. Underneath, text is just binary data, so rules are required to convert the binary data into the textual representation: this process is known as character encoding</a>. The most common type of encoding used on webpages is UTF-8</a>, which is the transfer format for the Unicode</a> standard. ASCII</a> is also a well-known encoding, but only supports a very restricted number of characters. Certain older software, such as TeX</a>, defaults to files encoded in ASCII:3</label>If you \usepackage[utf8]{inputenc}</code>, you can use Unicode directly in the .tex file. for example, to input directional quotation marks “”</code> (which are Left Double Quotation Mark</a> and Right Double Quotation Mark</a> respectively), one would use ``</code> and ''</code>. However, unless you are forced otherwise, you should try to write all your content in Unicode. </a>Crash course in HTML and CSS</h2> I’m going to assume you know some basics of HTML and CSS. There are lots of tutorials online; here is a nice one</a>. I’d recommend you read the articles on HTML basics</a> and CSS basics</a>. In this section, I’ll give a complete (albeit streamlined) description of setting up a basic functional webpage. We are going to create 4 files: . ├── 404.html ├── index.html ├── style.css └── writing └── index.html </code></pre> </a>Getting started</h3> Let’s start with a rather minimal HTML file. Call it index.html</code> in your (currently empty) website folder. <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width"> <title>Example Webpage</title> <meta name="description" content="An example webpage."> <meta name="author" content="Alex Rutar"> </head> <body> <header> Example Webpage </header> <nav> <a href="writing/index.html">Writing</a> <a href="index.html">About</a> </nav> <article> <h1>Welcome to my webpage</h1> <p>This is some content!</p> </article> </body> </html> </code></pre> This isn’t the most bare-bones possible HTML file, but it is a good modern starting point for all HTML content on your site. Here’s an explanation of some of the tags: <head>...</head></code> and <body>...</body></code>: these are the two main sections of your HTML file. <head></code> contains the metadata, and <body></code> contains the content that will show up on your screen when you visit the webpage.</li> <meta charset="utf-8"></code>: declare that the content is encoded in UTF-8</a>.4</label>You also need to make sure the file you are editing has the correct encoding!</li> <meta name="viewport" content="width=device-width"></code> ensures that, if this page is opened on a browser with a small screen, it will not be incredibly zoomed out. This is the bare minimum required so your page looks passable on a phone. You can read a bit about this here</a>.</li> <title></code>, <meta name = "description" ...></code>, <meta name="author" ...></code>: title, a short page description, and author.</li> <nav>...</nav></code>: website navigation</li> <article>...</article></code>: the ‘content’ of the page, i.e. your actual article or blog post but without the navigation, header, footer, etc.</li> </ul> Now if you open the file index.html</code> with your web browser (you can probably just double-click it) you should get a page with two links at the top: About, and Writing. Unfortunately the Writing link does nothing: we need to create that page. Create a new directory called writing</code> and in that directory create a file called index.html</code>. Then, fill it with pretty much the same contents as index.html</code>, but replace the <nav>...</nav></code> with the contents <nav> <a href="index.html">Writing</a> <a href="../index.html">About</a> </nav> </code></pre> and replace the <article>...</article></code> with something slightly different, say <article> <h1>Some things I've written</h1> <p>Nothing here yet...</p> </article> </code></pre> You can also change the title and description in this new page, as well. Now, if you click on the navigation links, you have two working pages! </a>Styling the page</h3> We have a functional webpage, but it would be nice to make everything look a bit better. Create a file style.css</code>, and add the line <link rel="stylesheet" type="text/css" href="style.css"> </code></pre> to the <head></code> of index.html</code> and <link rel="stylesheet" type="text/css" href="../style.css"> </code></pre> to the <head></code> of writing/index.html</code>. This tells the browser to look for a file named style.css</code> in the same directory as index.html</code> and in the directory containing the file writing/index.html</code>, which contains styling information. While it is possible to define styles inline in the HTML, this is bad practice since it is harder to maintain (as a general rule, HTML defines semantics, whereas CSS defines style). Also, you should add some more content to the <article></code> section: perhaps a few more headers <h2>...</h2></code> and links <a href="...some url...">my link</a></code>. This will make the styling changes more clear as you make them. Let’s begin with some basic styling. First, add body { margin: 0 auto; max-width: 700px; min-width: 0; padding: 0 10px 25px; font-family: "Helvetica", "Arial", sans-serif; } </code></pre> to the file style.css</code>. This centres the text body, prevents it from being too wide on large screens, ensures there is a bit of a space on the boundary when the screen is small, and finally sets a new font (rather than the usual default Times New Roman). The min-width: 0</code> is useful to prevent large elements from (accidentally) making the page very wide on screens narrower than 700 pixels. We can also adjust the spacing so that the text is laid out a bit more nicely: h2 { margin-top: 1em; padding-top: 1em; } nav a { margin-left: 20px; } </code></pre> And adjust the colour of the text itself to something a bit more pleasant: body { color: #444; } h1, h2, strong { color: #222; } </code></pre> Then touch up the font sizes: header { margin: 0px; font-size: 23px; } article { font-size: 16px; } nav { font-size: 18px; letter-spacing: 1px; } h1 { font-size: 26px; } h2 { font-size: 23px; } </code></pre> Finally, let’s add a bit of character by styling the links: a { color: #ffa64d; } </code></pre> Our webpage looks a bit cleaner now! </a>Grid layout</h3> However, we need to address some more serious layout problems: currently, the navigation is way too small, and the header does not stand out at all. To fix this, we are going to use a relatively new CSS technique known as CSS Grid</a>.5</label>A nice reference for CSS Grid can be found here</a>. Essentially, CSS Grid allows us to specify layout in a parent element, and then place the children inside this layout. First, let’s specify the general layout of our grid. We want three sections: a header in the top left (for our title), a navigation bar in the top right, and then a main area containing all the content of the site. We will target the <body></code> element to set up this grid: body { display: grid; row-gap: 5px; grid-template-columns: auto auto; grid-template-rows: 60px auto; grid-template-areas: "header nav" "ct ct" } </code></pre> Let’s break down what this is doing. display: grid</code>: this element is specifying a grid layout for its children.</li> row-gap: 5px</code>: have some space between the rows</li> grid-template-columns: auto auto</code>: we have two columns, and we want to determine their widths automatically</li> grid-template-rows: 60px auto</code>: we have two rows, where the first row (containing the header and navigation bar) has a height of 60 pixels, and the second row is sized automatically based on the content</li> grid-template-areas: ...</code>: assign names to the areas. We have header</code> in the top left, nav</code> in the top right, and ct</code> everywhere else (spanning both columns). Note that the names can be whatever you would like (there is no special meaning assigned to using header</code> and nav</code>).</li> </ul> Now, let’s assign our child elements to the areas in this grid, and do a bit of styling. header { grid-area: header; justify-self: left; align-self: end; } nav { grid-area: nav; justify-self: right; align-self: end; } nav a { text-align: right; } article { grid-area: ct; border-top: 2px solid gray; } </code></pre> Here is a quick explanation of what this does. First, we want the header to be justified to the left and the navigation bar to be justified to the right. Note that align-self: end</code> means that, within the grid row, we want to be placed as late as possible. This is important since the row has height 60 pixels, and without this argument, our header and navigation bar would be placed adjacent to the top of the screen!6</label>In general, align refers to vertical placement and justify refers to horizontal placement. Finally, we add a border above the <article></code> element with border-top: 2px solid gray</code> to visually separate our header and navigation bar from the rest of the content. </a>Responsive design</h3> Our layout looks decent on a computer, but now we might have some problems on small screens! The main problem is that if the screen is narrow, our header and navigation bar will start folding over itself. To fix this, we can use media queries</a>. This is CSS which is applied only when the query is satisfied: in this situation, we want these rules when the screen is narrow (less than 430 pixels wide). Here, we only change the styling a bit: place the header on top of the navigation bar by changing the grid layout in the body</li> centre the header and navigation bar</li> remove the asymmetric styling on the navigation links</li> </ul> This is done with the following CSS. @media screen and (max-width: 430px) { body { grid-template-columns: auto; grid-template-rows: minmax(40px, auto) minmax(30px, auto) auto auto; grid-template-areas: "header" "nav" "ct" } header, nav { text-align: center; justify-self: center; } nav a { margin: 0 10px; } } </code></pre> The minmax(40px, auto)</code> means that we want to row to be at least 40 pixels tall, except that we should make it taller if the elements inside require it. We also adjust the header and navigation bar to be nicely centred, since they are now placed on top of each other (rather than side by side). Now, our webpage also looks respectable even when viewed on exceptionally tiny phone screens. </a>Dealing with links</h3> Throughout this article, the links have been written in the form href="style.css"</code>. This specifies a relative link: the file path is taken relative to the directory that the file in which the link sits. The syntax href="../"</code> specifies that we are referring to a file in the directory containing the current directory. However, when deploying the webpage to a server, you will want to write the links in the form href="/style.css"</code>, which will give a link to the root of your website. This tells the browser to take the base URL (for example https://example.rutar.org</a>) and append the link. However, when browsing files on your device, the base URL is the root of your filesystem, i.e. /</code>, so /style.css</code> will (attempt to) link to the root of your filesystem directory, which was not what we wanted! Moreover, there is a convention for linking directly to files HTML files: files with the name index.html</code> are given special treatment. Suppose your directory structure looks like the following: . ├── index.html └── writing └── index.html </code></pre> Now, you can reference the file index.html</code> with href="/"</code> and the file writing/index.html</code> with href="/writing/"</code>. This is the standard way to include files in your project repository. To summarize, here are the changes we need to make: in both HTML files, change href="style.css"</code> to href="/style.css"</code></li> in writing/index.html</code>, change href="index.html"</code> to href="/writing/"</code> and href="../index.html"</code> to href="/"</code></li> in index.html</code>, change href="index/writing.html"</code> to href="/writing/"</code> and href="index.html"</code> to href="/"</code></li> </ul> Our links will no longer work properly when browsing the files locally, but when our webpage is online, the links will now work properly. We also want to deal with the case where the user tries to browse to a link which does not exist. For example, on this site, if you navigate to a URL like https://rutar.org/does-not-exist</a>, you will be shown a page explaining what happened. For this to happen automatically, we simply need to create a file 404.html</code> at the root of our directory, with some content explaining that the page is missing. The 404 is a HTTP response status code</a>, where the server tells the client that the page you are looking for is missing. Often, the server will default to showing the contents of the /404.html</code> file. Here</a> is an example of this file. This file also has proper naming of links, as discussed above. </a>Finishing up</h3> You can view the complete website at https://example.rutar.org</a>. The files themselves can be found on GitHub</a>. You can ignore the additional files: those will be explained in later sections. Here are some direct links to the files which we have prepared above: 404.html</a></li> index.html</a></li> style.css</a></li> writing/index.html</a></li> </ul> In my opinion, the best way to learn more about HTML and CSS is to take a website which you like and use the View Source or Inspect Element functionality in your browser. The MDN Web Docs</a> are an incredibly rich resource which contain almost everything you might want to know about web development. Whenever I need to look anything up, that’s where I start. If your browser is Safari on macOS, you can enable some nice development features with the Safari developer tools</a> option. For example, this allows you to emulate different browsers, and enter a responsive design mode which allows you to manually modify the screen size and view how your webpage will change. Firefox also has similar functionality built into the Firefox developer tools</a>, and the Google Chrome browser in Chrome DevTools</a>. </a>Deployment with GitHub and Cloudflare</h2> Now that we have created our personal webpage, we want to make it publicly available! In order to do this, we will use GitHub</a> to host our files, and then integrate Cloudflare Pages with our GitHub account to take the hosted files and deploy them to our domain. GitHub is a hosting provider for git</a>, which is software for tracking and saving changes to a set of files. In fact, I would recommend that you learn how to use git locally, and then integrate it with GitHub. However, the tutorial for setting this up is beyond the scope this article! If you are interested in this, you can find some pointers to get started on the git webpage</a> and on GitHub</a>. For site deployment, I will cover two main options: using GitHub Pages</a>, or using Cloudflare Pages</a>. Both options are free. Generally speaking, Cloudflare Pages is a more comprehensive web hosting solution than GitHub Pages, whereas GitHub Pages is specialized for GitHub repositories. Here are some benefits of using Cloudflare Pages over GitHub Pages: Easier custom domain setup. Since Cloudflare is also a domain registrar and DNS provider, they will manage many of the details for you which makes setup substantially simpler.</li> Support for multiple sites. GitHub Pages restricts you account to 1 site per account, whereas Cloudflare Pages lets you have as many sites as you would like.</li> Repository privacy. Unless you pay, GitHub Pages requires your repository to be public</a>. It is possible, but somewhat complicated, to work around this requirement. Cloudflare Pages lets you link public or private repositories.</li> </ol> Cloudflare probably also has better server performance, but for a small static webpage, the difference is minimal. On the other hand, the main reason to prefer GitHub Pages over Cloudflare Pages is decreased complexity: as we will see below, GitHub Pages is very easy to set up, especially since we already need to host our webpage code on GitHub. The Cloudflare webpage is also rather developer-oriented, so the dashboard can be a bit confusing to use at first. With GitHub Pages, your default URL will be your-username.github.io</code> , where your-username</code> is the username you use to sign up for GitHub Pages. With Cloudflare Pages, your URL will be project-name.pages.dev</code>, where project-name</code> is something you can choose individually for each webpage. </a>Creating the repository on GitHub</h3> First, you need to create a new repository. I would recommend that you follow the instructions here</a>. Here are a couple notes: If you are using Cloudflare Pages, you can name the repository anything you would like (you do not need to choose hello-world</code>). If you are using GitHub Pages, you must name the repository your-username.github.io</code>.</li> Optionally, you can choose the Add README option, which you can later modify to provide information on your webpage. This file will be used to display information on your repository page.</li> You can also choose to either make your webpage public or private. A public repository means that anybody can view (but not edit) your GitHub repository, whereas only you—or anybody you give permission—will be able to see the repository if it is private. If you are using GitHub Pages, your repository must be public.</li> </ol> Once you’ve finished creating the new repository, you need to add files that we created earlier! To do this, click on the Add File option, beside the Code drop-down menu in green. If you choose the Upload files option, the file will be placed directly into the folder. To upload files to a subfolder, you need to click on the subfolder first and then choose the Add File option. Somewhat inconveniently, this requires the folder to already exist.</li> If you choose the Create new file option, you can specify the filename directly and copy-paste the contents into the built-in browser. In order to put the file in a subfolder, simply provide a filename containing a backslash. For example, to add the HTML file for the Writing tab, enter the name writing/index.html.</li> </ol> Once you have added the file(s), click the Commit new file option at the bottom. It is simplest to choose the default option (Commit directly to the —— branch). When you’ve finished, the repository should look something like this</a>. If you have decided to use GitHub Pages, your page should automatically deploy after a few minutes! To see the status of the build, go to the Actions tab. You can also see the current status in the Environments section of the sidebar on the right hand side. </a>Deploying on Cloudflare</h3> In this section, I will recommend that you follow the instructions in the Cloudflare Pages documentation</a> for complete detail. The general idea is to navigate to the Pages tab, select Create a project, and follow the instructions. You need to link your GitHub account so that Cloudflare can automatically read the code and update your webpage whenever the code changes. Here are a couple notes: The Project name that you choose will be used to create the default domain. For example, I named my project webpage-example</code> and my default Cloudflare–provided URL is https://webpage-example.pages.dev</a>.</li> Under the Build command, simply write exit 0</code>. Leave the Framework option and the Build output directory as their default values.</li> </ol> Once you’ve finished, click Save and Deploy, wait for the build to finish—this will take a few minutes, even though there is nothing to build—and then your webpage will be publicly available! </a>Adding and modifying content</h3> Now, to make edits to your webpage or add new files, simply edit existing files or add new files to the GitHub repository. Once the changes are committed to the repository, Cloudflare Pages (or Github Pages) will automatically update your webpage! Note that there will be a delay—approximately two minutes—from when you commit the change, until the changes are available. </a>A note on git and commits</h3> Underlying GitHub is the git version control software. Essentially, a commit is a complete copy of the state of all the files that git is tracking, at a given point in time.7</label>Internally, git only saves the differences, or this would take a large amount of storage space! Because of this, git saves your entire history, which makes it relatively straightforward to undo changes and view the state of your site in the past. Git is also useful to version control other important files! It is also possible to have multiple versions of your content using git branches</a>. For example, it is even possible to preview a development branch</a> automatically using Cloudflare Pages. However, doing anything complicated in the GitHub browser is either tedious or impossible. Because of this, I would recommend using git locally, modifying files on your computer, and then synchronizing the changes with your GitHub account. There are also many options to test changes locally before committing them to your GitHub repository. For example, you can use the built-in Python web server</a>, or a more robust option</a>. This way, you can test changes to your site without interfering with your webpage, until you are confident the changes are doing what you expect! </a>Further topics</h2> </a>Custom domains</h3> If you followed the instructions above, your URL looks like your-username.github.io</code> or project-name.pages.dev</code>. However, it is also possible to host your website under a custom URL. Beyond the aesthetic benefits of having a distinctive URL, there are a few additional benefits: Domain name perpetuity. Domain name registration is regulated by ICANN</a>, and domain name ownership is protected under certain rules</a>. Even if your registrar goes out of business, the domain name is still legally yours. On the other hand, while GitHub and Cloudflare Pages are likely to remain in business for at least a few years, on long timeframes—say multiple decades—there is risk that these sites will cease to exist. Having your own domain guarantees that your site is always available at the same address on the web.</li> Email routing. It is also possible to use your domain name to route emails. For example, you can contact me at [email protected]">[email protected]</a>. Again, this is useful since it is a perpetual email address associated with your name, and you do not need to worry about losing your address if your provider goes out of business.</li> </ul> There are a few parts to setting up a custom domain. First, you need to register a domain name, and then you need to set up DNS</a> to associate your domain name with the address where your webpage is hosted. In terms of domain registrars, I would recommend one of the following: Cloudflare Registrar</a></li> AWS Route 53</a></li> Gandi</a></li> </ul> I would definitely be careful with other hosts—certain popular domain registrars engage in shady practices</a> such as registering domains that you look up on their site so that they can make you pay more money for them! Domain name pricing is also problematic, since many registrars will allow you to register a new domain for a low cost but then charge high renewal fees! In this tutorial we will use Cloudflare. Conveniently, Cloudflare manages DNS and name registration simultaneously, which makes it very easy to set up a new domain. Moreover, if your site is already hosted on Cloudflare, adding the correct DNS records to make your site available can be performed semi-automatically. </a>Domain name registration</h4> In order to register a new domain, carefully follow the instructions in the documentation</a>. It is important to provide accurate information here, since as discussed before, domain name ownership gives you certain legal rights, and providing correct information is required to maintain this. Note that this information will not be displayed online since Cloudflare uses WHOIS redaction</a>8</label>WHOIS</a> is a protocol which enables lookup of domain ownership records. You can see the records for my domain here</a>.. </a>Setting up DNS</h4> Essentially, DNS</a> provides a standardized way to convert web addresses, e.g. https://rutar.org</a>, into IP Addresses</a>. As a mildly crude analogy, one can think of DNS as a mapping from house addresses to GPS coordinates. Conveniently, since we are also using Cloudflare for DNS, the domain is automatically linked to the DNS page. To see your DNS record page, navigate to the Websites tab, select your domain name, then navigate to the DNS tab. </a>Adding a record for our webpage</h4> Finally, adding the record for our webpage is straightforward: navigate to the project configuration page (in the Pages tab) and select the Custom domains tab. Input your custom domain name and select Continue. For a bit more detail, see the documentation</a>. Once you’ve done this, you might have to wait a couple minutes for the DNS to propagate (sometimes, you need to refresh your own WIFI connection) and then your site will be available at your domain! </a>Adding a favicon</h3> A favicon</a> is a small image loaded by the browser and displayed on the website tab. There is a lot of different advice on how to appropriately set favicons, and unfortunately a lot of it is very outdated. These days, modern browsers support SVG</a> favicons and this format is the simplest and most robust way to add a favicon to your webpage: it is lightweight and scales properly. There are lots of tools available to create SVG favicons—I used this site</a>. You can also just download an icon from a place like font awesome</a>. If you want to create a custom icon, you can use an online SVG editor</a>. To add the favicon to our webpage, first copy the icon file, say icon.svg</code>, to the root of your project directory. Then add the following line to the <head></code> of each page on your site: <link rel="icon" href="/icon.svg" type="image/svg+xml"> </code></pre> This tells the browser that there’s an icon located at /icon.svg</code>, and that it’s an SVG file. If you wish to support more devices, I’d recommend that you read this favicon article</a>. The next most important file to create would be a favicon.ico</code> file: this will display the favicon even on outdated browsers. Image favicons are somewhat more flexible than SVG favicons, since it is easy to convert most visual files to an ICO file.9</label>For example, you might consider this site</a> to generate favicon files from existing images. Thanks to a reader for this nice suggestion! </a>Site security</h3> In order to prevent malicious parties from hijacking your web traffic and impersonating your site, it is important that all HTTP connections are encrypted with HTTPS</a>. There are many opinions</a> on why HTTPS is important. With Cloudflare Pages and GitHub Pages, this is automatically managed on your behalf: if you navigate to your site, you should a small lock symbol somewhere near the address bar. If you click on this lock symbol, your browser will show some information about the connection. However, beyond serving your content over HTTPS, there are some other site security features you can implement with a minimal amount of effort. </a>Basic security headers</h4> HTTP headers</a> are used to to pass additional (often meta) information with the body of the HTTP request. One usage of HTTP headers is to make guarantees about the content and prevent your site from being misused, or the content from being hijacked. In order to add headers to your site hosted on Cloudflare, you simply need to add a file called _headers</code> to your project directory. The syntax for the headers document is of the form [url] [name]: [value] </code></pre> You can read more about the _headers</code> file on the Cloudflare documentation</a>. For now, populate the file with the following contents: /* X-Frame-Options: DENY X-Content-Type-Options: nosniff Referrer-Policy: same-origin </code></pre> This adds the following headers to any HTTP request set to a URL matching the /</code> pattern (that is, every URL on your site): X-Frame-Options</a>: This prevents your site from being embedded on other websites.</li> X-Content-Type-Options</a>: Don’t let the browser guess what type of content you are linking. This requires that you properly label the content type in linked content, e.g. type="text/css"</code> from the CSS link</a>.</li> Referrer-Policy</a>: Control what information is passed along when a visitor clicks on links in your site. The value same-origin</code> means that, if a visitor to your webpage navigates clicks on a URL that is not on your site, no information is passed along.</li> </ul> </a>Content security policy</h4> A content security policy (CSP)</a> is a way for your site to declare what type of content it is serving. This can be used to guarantee that the content on your site is sent exactly as you intended, along with some other features. For our example site, since all the content is served from the same domain (self</code>), and the only non-HTML content we are serving are CSS pages and images (for example, the favicon), our CSP can be pretty restrictive. Here’s what we will use: Content-Security-Policy: default-src 'none'; img-src 'self'; style-src 'self'; upgrade-insecure-requests; form-action 'none'; base-uri 'none'; frame-ancestors 'none' </code></pre> Here is an explanation of the various components. default-src 'none'</code>: by default, we are serving no content other than HTML.</li> img-src 'self'</code> and style-src 'self'</code>: include CSS and images, but only from the same domain.</li> upgrade-insecure-requests</code>: redirect http://</code> to https://</code>.</li> form-action 'none'</code>: do not send HTTP forms anywhere.</li> base-uri: none</code>: the document base URL is just /</code>.</li> frame-ancestors 'none'</code>: similar to the X-Frame-Options: DENY</code> from before, since it prevents your site from being embedded elsewhere.</li> </ul> To see more details on creating a content security policy, the MDN page</a> has a nice explanation. Note that if you want to include JavaScript (or other content), especially content loaded from a different domain, modifying your CSP will require a bit more work. </a>HSTS Preload</h4> Essentially, HTTP Strict Transport Security (HSTS)</a> provides a list of sites that are hard-coded to be using HTTPS. This list is used by your browser to guarantee to prevent connecting to a site on the list without using HTTPS. If you are committed to using HTTPS, you can register your site for HSTS Preload. In order to implement this, you need to register your site at the URL https://hstspreload.org</a>. Most of the steps are already done: the only thing that remains to be done is to add the Strict-Transport-Security</code> header as follows: Strict-Transport-Security: max-age=31536000; preload; includeSubDomains </code></pre> You can also view the status of your domain by using the search bar at the top of the page. Another option is to enable this on Cloudflare directly: follow the instructions here</a>. You must set the Max Age setting to 12 months, and I would also recommend selecting all the other options. </a>Complete header file</h4> Here are the contents of the _headers</code> file, assuming you have implemented all of the recommendations above. / X-Frame-Options: DENY X-Content-Type-Options: nosniff Referrer-Policy: same-origin Content-Security-Policy: default-src 'none'; img-src 'self'; style-src 'self'; upgrade-insecure-requests; form-action 'none'; base-uri 'none'; frame-ancestors 'none' Strict-Transport-Security: max-age=31536000; preload; includeSubDomains </code></pre> You can also see the file here</a>. There are many ways to verify that the headers are loaded properly on your site. The Mozilla observatory</a> page is a nice resource, along with https://webbkoll.dataskydd.net/en/</a> for giving more detailed information and recommendations. Vim Session Management: An Introduction to Fish 2022-02-01T00:00:00+00:00 </a>Objectives</h2> Fish shell</a> is a user-friendly command line shell and scripting langauge. However, the project is relatively new, so it can be somewhat challenging to find concise information on how to use the scripting language. In this article, we will develop a basic session management tool for (Neo)Vim. The intention of this tool is to be a wrapper around Tim Pope’s obsession.vim</a> plugin, with the following features: Easy session initialization</a>: list sessions and open them</li> Active session management</a>: we only want to allow a single instance of vim to be using a session file</li> Autocompletions</a>: get relevant results when you hit TAB</code></kbd></li> </ol> Perhaps you simply find the session management tool useful: you can find the program in the Git repository</a>. This implements all the features below, along with a couple extra useful commands, completions, and help messages. </a>Prerequisites</h3> I will assume that you have the tools fd</a> and fzf</a> installed and accessible in your shell. If you don’t, you can simply omit the components that use fzf</code>, and rewrite the parts using fd</code> to use find</code> instead. I will also assume you know a bit about (Neo)Vim, including plugin installation. </a>Session initialization and management</h2> In this section, we will write the core functionality of our program: save and open session files. First, let’s create a global variable to represent where we want to save the session files. Add the line set -x VS_SESSION_DIR "~/.local/share/vim/sessions" </code></pre> to your config.fish</code>, or wherever you prefer to define environment variables. You can set the folder to be anything you want. Now exec fish</code> to load this variable. To ensure that this variable is loaded, you can run envs | grep ^VS_SESSION_DIR</kbd></code></pre> and check that there is a match. The command env</code> prints out all currently defined environment variables—we just search for the line that starts with VS_SESSION_DIR</code>. </a>A wrapper for Obsession.vim</h3> Obsession.vim</a> is itself a wrapper around the vim command :mksession</code>, which creates a session file and saves the current state of vim (e.g. tabs, windows, layout, etc.) to that file. If you have a session file session.vim</code>, you can restart it with vim -S session.vim</code>. Install this plugin in your vimrc</code> and also add the function definition command -nargs=1 VSave Obsess $VS_SESSION_DIR/<args>.vim </code></pre> This defines a command :VSave</code>, which takes exactly one argument which is the name of the session file (with no extension). To begin a new saved session, run :VSave my/session</code> from an active vim instance. To terminate, run qa</code>: note that closing files individually will modify the session file so those files will remain closed on restart. </a>Starting up existing sessions</h3> Fish functions are defined in the folder ~/.config/fish/functions</code> and corresponding completions in ~/.config/fish/completions</code>. Let’s write the command to start up new sessions, which we will invoke with vs</code>. We want to accept the session name as an argument, and then check if the session file exists: if it does, open it; if not, terminate with a nice error message. In the file ~/.config/fish/functions/vs.fish</code>, we define a function as follows: function vs --argument session_name set -l sessionfile $VS_SESSION_DIR/session_name.vim if test -f $sessionfile vim -S $sessionfile else echo "Could not find session '$session_name'" >&2 return 1 end end </code></pre> To invoke, just run vs <session name></code>, and the corresponding session will be started! The --argument session_name</code> automatically assigns the first argument passed to vs</code> to the variable session_name</code>. Note that the variable will be empty if there are no arguments passed to vs</code>. Any other arguments are simply ignored. In shell scripting languages, conditionals often execute based on the return code of a command. In this case, the command test -f</code> returns 0 if $sessionfile</code> exists, and returns something else otherwise. We redirect the output of echo</code> to STDERR with >&2</code>, and then return with the default error code 1. Note that you can define multiple functions in a single file myfunc.fish</code>, but fish only knows to load those functions on request if there is a matching filename. You should only define helper functions for the main function in the file, since they will not be loaded until the main function is called. You can also edit functions in the current interactive shell with funced <function name></code>, and save the functions to the directory with funcsave <function name></code>. However, doing this will remove any helper functions you have defined in the file! This is also an easy way to introspect fish functions which you may have not defined yourself. If you edit a function file, sometimes you need to reload your shell for proper execution. The easiest way to do this is to exec fish</code>. </a>A basic subcommand: session listing</h3> For convenience, it would also be nice to be able to get a list of the existing session names. This utility will also be necessary later, when we provide autocompletion. Now, since we want multiple behaviours, we will invoke the desired behaviour with two subcommands: we will invoke the previous function with open</code>, and the new listing function with list</code>. First, we define a helper function to list sessions. Using fd</code>, we can quickly get a list of candidate files: fd -e vim --base-directory $VS_SESSION_DIR</kbd></code></pre> However, we only want the name of the session and not the extension .vim</code>. The easiest way to do this is to use --exec echo {.}</code>: {.}</code> is replaced with the filename with no extension. This also handles the case where the filename has multiple periods, unlike something more direct such as cut -d "." -f 1</code>. We also want to sort the output, since fd</code> is multithreaded by default when called with --exec</code> and the order can change each time (which could be confusing). Wrapping this in a function, we get function __vs_list_sessions fd -e vim --base-directory $VS_SESSION_DIR --exec echo {.} | sort end </code></pre> We can add this as a subcommand to our original function: function vs --argument command session_name switch $command case open set -l sessionfile $VS_SESSION_DIR/session_name.vim if test -f $sessionfile vim -S $sessionfile else echo "Could not find session '$session_name'" >&2 return 1 end case list __vs_list_sessions end end </code></pre> Now, open session files with vs open session/name</code> and list possibilities with vs list</code>. </a>Fancy session selection with fzf</h3> For convenience, let’s also write an interactive file chooser using fzf</a> This command reads input from STDIN and opens up an interactive browser which allows selection. Upon choosing an option, the corresponding line is sent to STDOUT. This variable is captured using fish parameter expansion (...)</code> and saved in the variable fzf_session</code>. Note that if fzf</code> is terminated early using Ctrl+C</code></kbd>, the variable $fzf_session</code> will not be saved, so we also need to check that it is non-empty. Add the following at the beginning of the indentation block directly below case open</code>: if not test -n "$session_name" set -l fzf_session (__v_list_sessions | fzf --height 40% --border --tac) if test -n "$fzf_session" set session_name $fzf_session else return 0 end end </code></pre> Essentially, when vs open</code> is called with no session name, an interactive prompt opens and allows you to search the available sessions. In fish, quotes are usually not required since variables are passed ‘as atoms’ rather than being expanded and separated on whitespace (as is the case with bash). One of the few exceptions to this rule is test -n "$var"</code>, which checks that var</code> is defined and non-empty. In this situation, you must always quote the variable since if var is not defined, then $var</code> will expand to an argument list of length 0, essentially calling test -n</code> instead of the desired test -n ""</code>. </a>Active session management</h2> Now let’s add active session management. If one shell instance has a session file open, we want to prevent another instance from opening up the same session file: multiple writes to the session file could corrupt the file! We will achieve this with file locking</a>. However, a bit of care needs to be taken: we need to handle termination of the script while it is running. The easiest way to do this to use event handlers</a>. When a function is created, it can be registered as an event handler for certain events. We care about three events: when the function receives the signal SIGINT</code> or SIGHUM</code>, which indicates interruption of the script, or when the shell itself terminates. </a>Basic event handler example</h3> Consider the following function: function example function __example_cleanup --on-signal INT --on-signal HUP --on-event fish_exit functions -e __example_cleanup echo "Cleaning up!" end read -p 'echo "Press ENTER to continue "' echo "Done!" __example_cleanup end </code></pre> If you run the script normally, following the prompt, the function simply prints example</kbd> Press ENTER to continue [ENTER] Done! Cleaning up!</code></pre> to your terminal. However, suppose instead of pressing ENTER</code></kbd>, you hit Ctrl+C</code></kbd> to terminate. Then the __example_cleanup</code> event runs immediately, and the function will print example</kbd> Press ENTER to continue [Ctrl-C] Cleaning up!</code></pre> Even though the function never completed, the cleanup function still fires. The handler --on-event fish_exit</code> also catches the case where you, say, close the entire terminal window while the function is running. Note that we must delete the function __example_cleanup</code> when we execute it, with functions -e</code>. Otherwise, __example_cleanup</code> will continue to live in our interactive shell and will fire even if we run Ctrl+C</code></kbd> during the execution of a different program. </a>Incorporating file locking</h3> Our idea is now the following: when we first start up our session, we check for the existence of lock files. If one does not exist, create it, and start up the session; otherwise, terminate with an error, For convenience, since the session files are saved as <session name>.vim</code>, let’s save the lock files as <session name>.lock</code>. In order to avoid race conditions, we can create the lock file and test its existence simultaneously using mkdir</code>: if mkdir <session name>.lock &> /dev/null echo "Normal execution..." return 0 else echo "Lock file exists!" >&2 return 1 end </code></pre> This works since mkdir</code> returns error code 1 if the directory it is trying to create already exists. We also supress the mkdir</code> error message, since we want to send a more meaningful one to the user ourselves. We also need to clean up the lockfile on exist using the event handler from the previous section. All together, our code now looks like this if test -f "$sessionfile" function __vs_cleanup \ --inherit-variable lockfile \ --on-signal INT --on-signal HUP --on-event fish_exit functions -e __vs_cleanup rmdir $lockfile end if mkdir $lockfile &> /dev/null vim -S $sessionfile __vs_cleanup else echo "Session '$vs_fname' already running!" >&2 return 1 end else ... </code></pre> In principle, we might have to worry about multiple instances of the same event handler __vs_cleanup</code>. However, as of the time of writing this article, fish does not support background functions</a>, so we only need to worry about our function running in multiple shells, in which case we do not need have this issue. </a>A note on trap</h3> Fish comes with a function trap</code>, which is just a wrapper around the event handler method explained above. At its core, the implementation of trap</a> converts EXIT</code> into --on-event fish_exit</code> and all other signals into --on-signal <signal name></code>. You can call trap</code> directly with the cleanup function (with no handlers attached), like trap __example_cleanup INT HUP EXIT </code></pre> Note that, in this situation, the event handlers are not automatically deleted. To do this, you need to run trap - INT HUP EXIT </code></pre> to reset the traps. To debug issues with handlers persisting longer than you expect, you can get a list of all active handlers with functions --handlers </code></pre> </a>Finishing up</h2> </a>Starting new sessions</h3> It would also be nice to start new sessions with a terminal in the given directory. We can tell vim to execute some commands using the +<command></code> syntax: such arguments passed to vim will be executed in order as the vim session is started. For example, if you run vim +term</kbd></code></pre> you will get a vim terminal pane in the current directory. Since we already wrote a function VSave</code> earlier, it’s a simple matter to call this function as well: vim "+silent VSave <session_name>" +term</kbd></code></pre> The silent</code> command executes the next command without printing anything into the Vim pane. We also do a quick check that there is not an existing session with the provided name. set -l sessionfile $VS_SESSION_DIR/$session_name.vim if test -f $sessionfile echo "Cannot overwrite existing session '$session_name'" >&2 return 1 else mkdir -p (dirname $sessionfile) && vim "+silent VSave $session_name" +term end </code></pre> Now, running vs init <session_name></code> will create a new session with name <session_name></code> and start out with a terminal in the directory where the command was called. </a>The entire function</h3> It remains to add a case where an invalid command is given, and to print out a short error message. After doing this, our file vs.fish</code> now has the following contents: function vs --argument command session_name new_session_name function __v_list_sessions fd -e vim --base-directory $VS_SESSION_DIR --exec echo {.} | sort end set -q VS_SESSION_DIR; or set -l VS_SESSION_DIR "~/.local/share/nvim/sessions" switch $command case open if not test -n "$session_name" set -l fzf_session (__vs_list_sessions | fzf --height 40% --border --tac) if test -n "$fzf_session" set session_name $fzf_session else return 0 end end set -l sessionfile $VS_SESSION_DIR/$session_name.vim set -l lockfile $VS_SESSION_DIR/$session_name.lock if test -f "$sessionfile" function __vs_cleanup --inherit-variable lockfile \ --on-signal INT --on-signal HUP --on-event fish_exit functions -e __vs_cleanup rmdir $lockfile end if mkdir $lockfile &> /dev/null vim -S $sessionfile __vs_cleanup else echo "Session '$session_name' already running!" >&2 return 1 end else echo "Could not find session '$session_name'" >&2 return 1 end case list __vs_list_sessions case init set -l sessionfile $VS_SESSION_DIR/$session_name.vim if test -f $sessionfile echo "Cannot overwrite existing session '$session_name'" >&2 return 1 else mkdir -p (dirname $sessionfile) && vim "+silent VSave $session_name" +term end case '*' echo "Invalid command option '$argv[1]'" >&2 return 1 end end </code></pre> Here are some other feature ideas: custom rename</code> and delete</code> commands</li> nicer file listing with tree</code> (hint: use tree --fromfile .</code> to format input from STDIN, and isatty</code> to only format when the output is a terminal)</li> add some nice help messages</li> </ul> </a>Autocompletions</h3> Finally, it would be nice to have some autocompletions for our script. Completion files are stored in a file with the same name as the function file, except in the ~/.config/fish/completions</code> directory. We want basic descriptions for the commands when we hit TAB</code></kbd>, and we also want autocompletion for the session name when we call vs open</code>. Fish completion files are also just regular lists of functions, except they are loaded when autocompletion for a certain function is requested. You can read the fish docs about completions</a> if you would like. We begin by disabling file completion on the base command, which is enabled by default. This is done with the command complete -f -c vs </code></pre> This way, when we hit tab, we are not suggested offered files in the current directory in the completion list. Now, we need to add our subcommands. This is done as follows: to add the completion option open</code>, we use complete -c vs -a open -d 'Open the session file' </code></pre> However, this has a problem since now fish will suggest open</code> as a valid argument at any time, when it should only be valid at the beginning. In order to fix this, we first introduce a list of all our valid command names with set -l vs_subcommands open list </code></pre> and then use the -n</code> flag for complete</code> to only complete in the case that we have not yet seen any subcommands. We can also include an option for vs list</code>. complete -c vs -a open \ -n "not __fish_seen_subcommand_from $vs_subcommands" \ -d 'Open the session file' complete -c vs -a list \ -n "not __fish_seen_subcommand_from $vs_subcommands" \ -d 'List available session files' complete -c vs -a init \ -n "not __fish_seen_subcommand_from $vs_subcommands" \ -d 'Start up a new session' </code></pre> Finally, when we have seen the subcommand vs open</code>, we want to provide the valid list of options. Here, the vs list</code> command comes in handy: complete -f -c vs -a "(vs list)" \ -n "__fish_seen_subcommand_from open" -a "(vs list)" </code></pre> As a whole, the contents of the completion file can be found in the Git repository</a>. As a whole, the completion file ~/.config/fish/completions/vs.fish</code> looks like set -l vs_subcommands init list open complete -f -c vs complete -c vs -a open \ -n "not __fish_seen_subcommand_from $vs_subcommands" \ -d 'Open the session file' complete -c vs -a list \ -n "not __fish_seen_subcommand_from $vs_subcommands" \ -d 'List available session files' complete -c vs -a init \ -n "not __fish_seen_subcommand_from $vs_subcommands" \ -d 'Start up a new session' complete -c vs -a "(vs list)" \ -n "__fish_seen_subcommand_from open" -a "(vs list)" </code></pre> Now hitting vs</code> SPACE</code></kbd> TAB</code></kbd> prompts with two options: open</code>, or list</code>, and hitting vs open</code> SPACE</code></kbd> TAB</code></kbd> prompts with the possible session names. Managing Python Versions with Pyenv 2022-01-20T00:00:00+00:00 The pyenv</a> command line utility is convenient tool for managing python versions. </a>Installation</h2> It’s best to follow the above link for general installation instructions. Otherwise, I will assume you are using macOS with Fish Shell. First install pyenv</code> and pyenv-virtualenv</code> with brew: brew install pyenv pyenv-virtualenv</kbd></code></pre> You also want to add some lines to your config.fish</code>: set -Ux PYENV_ROOT "$HOME"/.pyenv status is-login; and pyenv init --path | source status is-interactive; and pyenv init - | source status is-interactive; and pyenv virtualenv-init - | source alias brew="env PATH=(string replace (pyenv root)/shims '' \"\$PATH\") brew" </code></pre> You can set PYENV_ROOT</code> to be any location you would like. The remaining commands are used to initialize pyenv</code> and add the corresponding python versions to your PATH</code>. </a>Startup</h2> The first thing to do is to set your preferred global python version: pyenv global 2.7.18 3.10.1</kbd></code></pre> sets the python2</code> version to 2.7.18</code> and the python3</code> version to 3.10.1</code>. The global version is useful for user-wide modules and tools you might want to install with pip</code>. You can get a list of possible versions with pyenv install -l</code>. </a>Managing virtual environments</h2> For specific projects, you probably only want to install the packages necessary for that project. A virtualenv is essentially an isolated installation of python (and packages) which are specific to the current environment. This lets you organize what modules you have installed, as well as the python version. As an example, let’s create a virtualenv named my-venv</code>. First, create it with pyenv virtualenv 3.10.1 my-venv</kbd></code></pre> Let’s say we are in a project directory where I want to use the my-venv</code> virtual environment. Simply create a file named .python-version</code>, which is populated with the name of the desired virtual environment: echo "my-venv" > .python-version</kbd></code></pre> Now, whenever you enter this directory, pyenv</code> will automatically activate the environment, and whenever you leave, the environment will deactivate. You can also manually activate the virtual environment with pyenv activate my-venv</kbd></code></pre> and deactivate with pyenv deactivate</kbd></code></pre> To get a list of all the virtual environments currently installed, run pyenv virtualenvs</kbd></code></pre> You can uninstall virtual environments with pyenv uninstall my-venv</kbd></code></pre> Previewing a Development Branch on Cloudflare Pages 2022-01-19T00:00:00+00:00 In this article, I assume that your repository is hosted on GitHub</a>, and the site is hosted on Cloudflare pages</a>. I’m sure other providers will work, with similar instructions. </a>Creating the development branch</h2> First, create a new branch development (or any name you would like): git pull</kbd> git branch development</kbd> </code></pre> Now to add draft changes, first git switch development</kbd></code></pre> then perform the changes you want and commit them. To include those changes in your main branch, git switch main</kbd> git merge development</kbd> git push</kbd> </code></pre> Now, we just need to push the development branch to our GitHub repository. git push origin development</kbd></code></pre> Cloudflare will automatically build changes to your development branch, which you can preview at the URL development.<project-name>.pages.dev</code>. </a>Customizing the build command</h2> It is often the case that you want the build command for your development branch to be different than the build command for your main branch. For example, if you use Zola</a> for templating, you might build the main branch with zola build</kbd></code></pre> whereas you might build the development branch with zola build --drafts</kbd></code></pre> Moreover, when using Zola, the site URL is automatically set based on the key base_url</code> in your config.toml</code>. This works for the main branch, but our development branch has a different URL, which will cause non-relative internal links to be broken. Conveniently, Cloudflare Pages defines an environment variable $CF_PAGES_BRANCH</code>, which is the name of the branch currently being built. We can use this variable to write a new build command with better behaviour: if [ "$CF_PAGES_BRANCH" = "main" ]; then zola build; else zola build -u "https://$CF_PAGES_BRANCH.<project-name>.pages.dev" --drafts; fi </code></pre> If the branch is your main branch, then just run zola build</code>. Otherwise, the preview URL will be https://development.<project-name>.pages.dev</code>, which we manually specify with the -u</code> option. And we also include draft articles in the preview as well, with the --drafts</code> option. If we decide to add more branches, the same non-main build command will work for any branch we add. Now, whenever you push commits on your development branch to GitHub, you can visit a preview of the build at https://development.<project-name>.pages.dev</code>.

Course details</h2>

Pre-requisites</h3>
The following pre-requisites are essential.</p>

Measure and integration 1 & 2</li>
Introductory probability theory</li> </ul>

How to Build a Personal Webpage from Scratch

Vim Session Management: An Introduction to Fish

Managing Python Versions with Pyenv

Previewing a Development Branch on Cloudflare Pages

Alex Rutar's Blog

Fractal geometry and dynamics

(Un)safely moving elements out of borrowed data

Dynamically set Cargo features in Neovim

Using Closure-style Traits to Simplify a Rust API

Against Open Workspaces

Oath Dice and Combat Odds

Alex Rutar's Blog

Fractal geometry and dynamics

Exercise sheets</h3> Exercise 5 typo: the definition of semi-algebra was missing the assumption that it is a finite disjoint</em> union (thanks Mikko for noticing this!)</p>

Final project information</h3> The final project will be due on Sunday, February 22 at 23:59. Here is the list of available projects.</p>

Evaluation</h3> This course is scored out of 100, but ultimately the evaluation is pass-fail.</p> To pass, you require at least 60 points, with a minimum of 25 points on the final project. The finer breakdown is as follows:</p>

Course details</h2>

Pre-requisites</h3> The following pre-requisites are essential.</p> Measure and integration 1 & 2</li> Introductory probability theory</li> </ul>

(Un)safely moving elements out of borrowed data

Dynamically set Cargo features in Neovim

Using Closure-style Traits to Simplify a Rust API

Against Open Workspaces

Oath Dice and Combat Odds

How to Build a Personal Webpage from Scratch

</a>An overview of static webpage development</h2> </a>What is a static webpage?</h3> Modern webpages are (primarily) composed of three types of files: HTML, CSS, and JavaScript. Basically,</p> HTML specifies the content</em>,</li> CSS defines the style</em>, and</li>

</a>What is a static webpage?</h3> Modern webpages are (primarily) composed of three types of files: HTML, CSS, and JavaScript. Basically,</p> HTML specifies the content</em>,</li> CSS defines the style</em>, and</li>

Vim Session Management: An Introduction to Fish

Managing Python Versions with Pyenv

Previewing a Development Branch on Cloudflare Pages

Pre-requisites</h3>
The following pre-requisites are essential.</p>

Measure and integration 1 & 2</li>
Introductory probability theory</li> </ul>