
In this post we're going to see how we can build a Mastodon bot with GO that posts pre-planned post once per day. It will support attachments and respective alt texts to cover visually impaired people as well.

The library we're going to use to talk to the mastodon API is [go-mastodon][go-mastodon], which supports all the features we need for uploading assets and attaching them to our post.

## Preparing a Post/Toot

To keep our future posts nice and organised, we'll drop them into directories that have a `$year/$date.toml` structure. We'll use [toml][toml] for our content since it doesn't rely on indentation like yaml and lets us create key/value pairs without much trouble.

The first post ever posted by the [Game Trivia Bot][gametrivia bot] looks like this:

```toml
text = "The official Twitter account for Fall Guys released a \"human for scale\" illustration featuring their playable characters. Fall Guys are all 183cm (6ft) by the way."
tags = ['FallGuys']
assets = ['fallguys-scale.jpeg', 'fallguys-eyes.png']
assetsAlts = ['A Fall Guy next to human', 'Fall Guy eyes and skull']
credits = ['https://www.artstation.com/tudormorris']
```

We have the body `text`, the `tags` which will appear like `#FallGuys`, the `assets` (image files) and the alt text for those image files: `assetsAlts`. Lastly we also have `credits` for the image we're posting because we obviously want our followers to explore the cool creators behind visuals, talks or screenshots.

For our example we will simplify the format a little bit and only support one media attachment per post, like some of the famous bird site accounts that post a fox or an opossum every hour.

Now we also need a function to load the post and to parse it into a data type that we can work with in our program.

Let's create a file called `posts.go` to parse an example toml file:

```go
package main

import (
  "fmt"
  "os"
  "time"

  "github.com/BurntSushi/toml"
)

type Post struct {
  Text       string
  Tags       []string
  Asset      string
  AssetAlt   string
  Credits    string
}

func LoadPost() (Post, error) {
  var post Post
  postFileName := "posts/example.toml"

  _, fileExistErr := os.Stat("./" + postFileName)

  if fileExistErr == nil {
    fmt.Printf("File exists, processing\n")
  } else {
    fmt.Printf("File does not exist\n")
    return post, fileExistErr
  }

  _, tomlError := toml.DecodeFile(postFileName, &post)
  if tomlError != nil {
    fmt.Printf("TOML file reading/decoding error: %v\n", tomlError)
  }

  return post, nil
}
```

To load a post for a specific day, we would have to change the `postFileName` to something like:

```go
  currentTime := time.Now()
  postFileName := fmt.Sprintf("date-posts/%s/%s.toml", currentTime.Format("2006"), currentTime.Format("2006-01-02"))
```

which would allow you to use a directory structure like this:

```
├── date-posts
│   ├── 2022
│   │   ├── 2022-12-01.toml
│   ├── 2023
│   │   ├── 2023-09-23.toml
│   └── drafts
```

We'll get back to actually using the parsed post later.

## Getting the Mastodon API key

Mastodon bots are their own accounts, so you should check with your instance policies if bot accounts are allowed and then register an account with the desired username. Then, in the web interface you need to create an app with the right scopes. We'll need "write" at least, but check whatever you need for your bot.

![mastodon application scopes](/assets/2023/mastodon-api-keys.webp)

find your client key and client secret:

![client key and secret](/assets/2023/mastodon-application-bot-scopes.webp)

We'll also need to tell the bot which server it lives on like `streamers.social` or `mastodon.social`.


## Loading API Configuration

We need to pass the respective credentials to our bot and when we deploy it we probably also want to read it from the environment and not from a file committed to git, so let's create our `main.go` file and a `config.go` file to load our configuration either from a `.env` file in development or from the ENV variables in production.

main.go:

```go
package main

import (
  "fmt"
  "log"
)

var config map[string]string

func main() {

  envs, error := GetConfig()

  if error != nil {
    log.Fatalf("Error loading .env or ENV: %v", error)
  }

  fmt.Printf("%v", envs)
}
```

config.go

```go
package main

import (
  "fmt"
  "os"

  "github.com/joho/godotenv"
)

func readConfigFromENV() map[string]string {
  var envs = make(map[string]string)

  envs["MASTODON_SERVER"] = os.Getenv("MASTODON_SERVER")
  envs["APP_CLIENT_ID"] = os.Getenv("APP_CLIENT_ID")
  envs["APP_CLIENT_SECRET"] = os.Getenv("APP_CLIENT_SECRET")
  envs["APP_USER"] = os.Getenv("APP_USER")
  envs["APP_PASSWORD"] = os.Getenv("APP_PASSWORD")

  return envs
}

func GetConfig() (map[string]string, error) {

  if os.Getenv("APP_ENV") != "production" {
    envs, error := godotenv.Read(".env")
    if error != nil {
      fmt.Println("Error loading .env file")
    }
    return envs, error
  } else {
    envs := readConfigFromENV()
    return envs, nil
  }
}
```

and lastly this is the content of our `.env` file which sould also be listed in your `.gitignore` file:

```
MASTODON_SERVER="https://streamers.social"
APP_CLIENT_ID="2atM1d_KxIswqRn7uvusTe"
APP_CLIENT_SECRET="siuI0GDyOv9xD_htlQ5Tu"
APP_USER="gametrivia@jonathanmh.com"
APP_PASSWORD="super secret password"
```

You will need to replace the values with the ones you got from the web interface and a strong randomly generated password for your bot account.

Now if we run

```bash
go mod init
go mod tidy
go run .
```

We should see the following output that confirms that our config is being loaded correctly:

```
map[APP_CLIENT_ID:2atM1d_KxIswqRn7uvusTe APP_CLIENT_SECRET:siuI0GDyOv9xD_htlQ5Tu APP_PASSWORD:super secret password APP_USER:gametrivia@jonathanmh.com MASTODON_SERVER:https://streamers.social]
```

## Using the Mastodon API

This is great, we've moved our config loading to a file outside of our `main.go` to keep it a bit tidier and now we'll move on to making sure our API connection works as intended. In the examples of go-mastodon we can steal the following snippet:

```go
  c := mastodon.NewClient(&mastodon.Config{
    Server:       "https://mstdn.jp",
    ClientID:     "client-id",
    ClientSecret: "client-secret",
  })
  err := c.Authenticate(context.Background(), "your-email", "your-password")
  if err != nil {
    log.Fatal(err)
  }
  timeline, err := c.GetTimelineHome(context.Background(), nil)
  if err != nil {
    log.Fatal(err)
  }
  for i := len(timeline) - 1; i >= 0; i-- {
    fmt.Println(timeline[i])
  }
```

and we can amend it to use our config like this:

```go
  c := mastodon.NewClient(&mastodon.Config{
    Server:       envs["MASTODON_SERVER"],
    ClientID:     envs["APP_CLIENT_ID"],
    ClientSecret: envs["APP_CLIENT_SECRET"],
  })

  err := c.Authenticate(context.Background(), envs["APP_USER"], envs["APP_PASSWORD"])
```

remember to also import `"github.com/mattn/go-mastodon"` and then we can run:

```
go mod tidy
go run .
```

Which should no emit any errors or output since your bots timeline is empty. If you have manually posted anything, the posts should be listed in your terminal. If your credentials are wrong of if there are any bugs in your code, it should show something like the following error:

```
2023/01/22 17:41:18 bad authorization: 401 Unauthorized: invalid_client
exit status 1
```

## Posting to the Mastodon API

Finally, we'll post our example post, let's create a file called `posts/example.toml` and add a picture called `posts/owl.jpg` and try to post it to the timeline.

example.toml:

```
text = "The majestic owl, owling about in its natural habitat."
tags = ['owl', 'nature', 'photography']
asset = 'owl.jpg'
assetAlt = 'an owl'
credits = 'https://unsplash.com/photos/miEWeTPYsFE'
```

Now we amend the main.go file to include the following:

```go
  post, err := LoadPost()
  if err != nil {
    log.Fatal(err)
  }

  var media mastodon.Media
  file, err := os.Open("./posts/" + post.Asset)
  if err != nil {
    log.Fatal(err)
  }

  media = mastodon.Media{File: file, Description: post.AssetAlt}
  attachment, err := c.UploadMediaFromMedia(context.Background(), &media)
  var attachmentIDs []mastodon.ID

  attachmentIDs = append(attachmentIDs, attachment.ID)

  finalText := post.Text + "\n"

  for i := 0; i < len(post.Tags); i++ {
    finalText = finalText + "#" + post.Tags[i] + " "
  }

  finalText = finalText + "\n" + "Credits: " + post.Credits

  toot := mastodon.Toot{
    Status:   finalText,
    MediaIDs: attachmentIDs,
  }

  fmt.Printf("About to publish: %#v\n", toot)
```

In this snippet we first upload the attachment for the post and save the attachment ID, then we alter the text and append each hashtag prefixed with a `#` and lastly add the credits.

Then we provide both to the `mastodon.Toot` type struct, made available by the library.

If you receive no error, you can add the final lines to post to your bot account:

```go
status, err := c.PostStatus(context.Background(), &toot)

if err != nil {
  log.Fatalf("%#v\n", err)
}
```

Now you should be able to see your post on your bot account:

![bot account published post](/assets/2023/mastodon-bot-toot.webp)

To post periodically I use a cronjob to run the application inside a docker container in production once per day. This takes a bit of planning, but it deploys automatically to dokku on merges to the main branch, which I will cover in the future.

Thank you so much for reading, [drop me a link on mastodon](https://streamers.social/@jonathanmh) to which wonderful bots you're creating!

[go-mastodon]: https://github.com/mattn/go-mastodon
[gametrivia bot]: https://streamers.social/@gametrivia


In this post we're going to see how we can build a Mastodon bot with GO that
posts pre-planned post...

Building a Mastodon bot with GO


Gemini is a smaller than HTTP protocol which only supports a smaller than Markdown syntax and supports virtually no media but ASCII art.

I like the concept and even though it's very niche, I wondered:

> How hard can it be? I have all my content as .md(x) files now anyways, surely it's going to be a quick one!

I was slightly unprepared for some of the pitfalls that of course partly are a result of me using [dokku][dokku] for deploying a lot of my web projects. Dokku by default only lets you handle http and https connections, but there's a cool plugin that lets you handle `gemini://` or other generic TCP connections.

## Preparing Content for Extraction ⚒️

I'm running [Next.js][nextjs] for my main blog for a few weeks now and I really like it. I can write markdown, push to a git remote and have an article published in a workflow that fits me well. On top of that I can write JavaScript components that let me do interactive stuff like [breaking down texts with virtual textmarkers](/p/building-a-text-annotation-component-with-react/) or [blurhash playgrounds](/tools/blurhash).

The metadata for blog posts is saved in frontmatter on top of the file, easy to extract from small scripts, which I made use of for the gemlog mirror.

First I created a new directory, let's say my blog lives in `jonathanmh.com` and my gmi mirror at `gmi-jonathanmh.com`. My content is not actually served based on file path of the `.mdx` file, because I wanted to sort my posts into years like `2021`, `2022` and so on, so I have a `slug` field in my frontmatter that tells Next.js the path.

This is my hacked together content extraction script, cut down a little bit for cases that might not be super relevant for you:

```JavaScript
const fs = require('fs');
const path = require('path');
const glob = require('glob');
const matter = require('gray-matter');
const DateTime = require("luxon").DateTime;

const contentPath = path.resolve(__dirname, '../', '../', 'jonathanmh.com', 'posts');

const files = glob.sync(`${contentPath}/**/*.mdx`, {
  realpath: true
});

let posts = files.map(postFileName => {
  const markdownWithMeta = fs.readFileSync(postFileName, 'utf-8');
  const { data: frontMatter, content } = matter(markdownWithMeta);

  return {
    frontMatter,
    content,
    isDraft: frontMatter.isDraft,
    slug: frontMatter.slug,
    baseName: path.basename(postFileName, '.mdx')
  }
});

posts = posts.sort(function (postA, postB) {
  const postADate = DateTime.fromSQL(postA.frontMatter.date);
  const postBDate = DateTime.fromSQL(postB.frontMatter.date);
  return postBDate.toMillis() - postADate.toMillis();
});

// posts for the index page
const indexPosts = [];

let indexTemplate = fs.readFileSync(path.resolve(__dirname, '../', 'templates', 'index.gmi'), 'utf-8');

for (let i = 0; i < posts.length; i++) {
  const post = posts[i];
  if (i < 10) {
    indexPosts.push(post);
  }

  const destinationPath = path.resolve(__dirname, '../', 'mdContent', `${post.slug}.mdx`);
  const content = `# ${post.frontMatter.title}\n\n${post.frontMatter.date}, by: Jonathan M. Hethey\n\n${post.content}`;
  console.log(`writing ${post.slug}.mdx`);
  fs.writeFileSync(destinationPath, content, 'utf-8');
}

// instead of using a templating engine we're going to stick stuff in this string
let indexPostsString = '';

indexPosts.forEach(post => {
  indexPostsString += `=> ${post.frontMatter.slug}.gmi ${post.frontMatter.title} - (${post.frontMatter.date})\n`
});

console.log('buliding index.gmi')
indexTemplate = indexTemplate.replace('[PLACEHOLDER]', indexPostsString)
const indexDestinationPath = path.resolve(__dirname, '../', 'content', `index.gmi`);

fs.writeFileSync(indexDestinationPath, indexTemplate, 'utf-8');
```

The most important parts are:

We're finding the directory where all the mdx posts are:

```JavaScript
const contentPath = path.resolve(__dirname, '../', '../', 'jonathanmh.com', 'posts');
```

We're not just copying the file, but we're writing `title` and `content` to a new mdx file!

```JavaScript
const content = `# ${post.frontMatter.title}\n\n${post.frontMatter.date}, by: Jonathan M. Hethey\n\n${post.content}`;
```

We're building a gemtext string from a template and writing the last 10 blog posts to it:

```JavaScript
indexPosts.forEach(post => {
	indexPostsString += `=> ${post.frontMatter.slug}.gmi ${post.frontMatter.title} - (${post.frontMatter.date})\n`
});

console.log('buliding index.gmi')
indexTemplate = indexTemplate.replace('[PLACEHOLDER]', indexPostsString)
```

with my `index.gmi` template looking like this:

```gmi
# JonathanMH.com

This is the gemini presence of jonathanmh.com

## Recent Posts:

[PLACEHOLDER]

=> https://jonathanmh.com For an http version of this site

=> https://streamers.social/@jonathanmh I'm on Mastodon

=> Full Archive /archive.gmi
```

This is pretty crude, but does what we want `¯\_(ツ)_/¯`.

Now we still need to convert our markdown to actual gemtext, for which I use [md2gemtext][md2gemtext], which I've paired with the copy script in a small bash file:

```bash
#!/bin/bash

mkdir -p mdContent
node scripts/copyContent.js

for document in mdContent/*.mdx; do
	echo converting $document
	md2gemtext $document content/$(basename $document .mdx).gmi
done
```

Now we have a `content` directory full of our previously markdown, now gmi posts, hell yeah! Alright, now for the deployment!

## Deploying Gemini or other NON HTTP to Dokku 🐳

The Dockerfile for this one was pretty simple, because all the work happens before the server starts, we're using [agate][agate] to serve the files:

```Dockerfile
FROM rust:latest

RUN cargo install agate

WORKDIR /usr/src/blog
COPY content content

EXPOSE 1965
CMD ["agate", "--hostname=jonathanmh.com", "--addr=0.0.0.0:1965"]
```

I wanted my gemini blog to appear at `gemini://jonathanmh.com` and not at a subdomain which is why I added another dokku app and pointed my domain at it and only on port 1965, where as the main site takes care of ports `80` and `443`. For that we also need the `nginx-stream` plugin, since the default plugin only handles http and https:

```bash
sudo dokku plugin:install https://github.com/josegonzalez/dokku-nginx-stream.git
sudo dokku apps:create gmi-jonathanmh-com
sudo dokku domains:add gmi-jonathanm.com jonathanmh.com
sudo dokku proxy:ports:remove 80 gmi-jonathanmh.com
sudo dokku proxy:ports-add gmi-jonathanmh.com tcp:1965:1965
```

If you get an error message like:

```
nginx: [emerg] "stream" directive is duplicate in /etc/nginx/nginx.conf:88
nginx: configuration file /etc/nginx/nginx.conf test failed
```

You can fix your config by opening `/etc/nginx/nginx.conf` and removing this duplicate block in the end:

```nginx
stream {
  include /etc/nginx/app-stream/*.conf;
}
```

This sometimes happens when two plugins try to install the same block and don't check for the presence of a block.

After that you can reload the main nginx config:

```bash
nginx -t
systemctl reload nginx
```

After deploying your app you should be able to see your gemlog at `gemini://yourdomain.tld`, YES! Also very cool that I can point one domain at different applications that respond on different ports, thank you dokku!

## Persisting Gemini Certificates 🔐

What I didn't account for was that `agate` does generate a new certificate and that if a gemini browser previously accessed a page with a different cert, it will show an error page. To persist the certificates we need to mount a volume into our app at the correct directory, so that the certificate gets created the first time the container runs and then loads the same ones afterwards:

```bash
dokku storage:ensure-directory gmi-jonathanmh-agate-certs
dokku storage:mount gmi-jonathanmh.com /var/lib/dokku/data/storage/gmi-jonathanmh-agate-certs:/usr/src/blog/.certificates
# output
=====> gmi-jonathanmh.com storage information
  Storage build mounts:
  Storage deploy mounts:
    -v /var/lib/dokku/data/storage/gmi-jonathanmh-agate-certs:/usr/src/blog/.certificates
  Storage run mounts:
    -v /var/lib/dokku/data/storage/gmi-jonathanmh-agate-certs:/usr/src/blog/.certificates 
dokku ps:restart gmi-jonathanmh.com
```

If you want to make sure it worked, you can run `dokku ps:restart gmi-jonathanmh.com` and then reload the page in your gemini browser. If you get not certificate warning, it is still using the same cert, even after the container being restarted.

## Summary

This was a fun one and it's really nice to see that my content migration paid off. Having an uncomplicated way to access the text part of the content available without joining over 30 tables and being able to parse the metadate with a single NPM package is absolute gold.

Improvements I still want to make is to finish converting my legacy content to markdown, because there are a few stray HTML tags here and there sticking out in the gemlog, which I need to fix.

In the meantime, get a gemini client like [Lagrange][lagrange] and check out [gemini://jonathanmh.com][gemini://jonathanmh.com]

[dokku]: https://dokku.com/
[agate]: https://github.com/mbrubeck/agate
[md2gemtext]: https://docs.rs/md2gemtext/latest/md2gemtext/
[lagrange]: https://github.com/skyjake/lagrange
[gemini://jonathanmh.com]: gemini://jonathanmh.com


Gemini is a smaller than HTTP protocol which only supports a smaller than
Markdown syntax and suppo...

Mirroring Next.js Blog to Gemini


Blurhash is an algorithm to save a tiny version of an image while the high resolution version is being fetched or for NSFW content warnings.

I first stumbled across [blurhash][blurhash] through Mastodon a few years back, but they're not the only ones using it, apparently Wolt themselves and Signal use it as well. In short, it's a string that looks like a very blurry image, which can be scaled seemlessly.

```
eKR2}TXUXo4TtS_M%LxatRad?wMxVs.8WBDONHIpRPX9%gt7n$NGj?
```

By now there's lots of implementations for both en- and decoders [listed on their github repo](https://github.com/woltapp/blurhash/), which makes it really easy to implement.

## Why should I use a Blurhash?

For me, there are two good reasons, performance and more fine-grained control for the users.

### Performance

If you're able to render a blurhash before a high resolution image is loaded, it gives you something to render into the placeholder element that will tell the visitor that something will be there soon and you can mitigate [Cumulative Layout Shift](https://web.dev/cls/) (CLS), which will improve the overall performance of your page load speed.

This may seem counter-intuitive, but rendering an image with unknown dimensions at the top of the page while the page loads will likely cause the browser to re-calculate the position of all elemnents that occur after it, which we want to avoid.

An element that you could use instead of implementing images directly on a blog could look like this:

```html
<div
  className="blurhash-image"
  data-blurhash="eKR2}TXUXo4TtS_M%LxatRad?wMxVs.8WBDONHIpRPX9%gt7n$NGj?"
  data-img-src="/assets/example-dog.jpg"
  style="width: 400px; height: 200px;"
>
</div>
```

and with a JavaScript library like [fast-blurhash](https://github.com/mad-gooze/fast-blurhash) you can pick up the `data-blurhash` value and render it to a canvas element when the page or component loads. When your real asset is available you can swap it out.

If you want to keep the initial page load as small as possible, just wait for the element to come into view through an [intersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). You can start loading the image asset if it's close to the scroll depth of the user, remove the `canvas` element and substitute it with the `img` tag.

One of the things crucial for performance is to know the dimensions of the element beforehand, so just not loading the images at first has a limited effect.

### Additional Control for your Users

Another reason to use a blurhash instead just rendering the video is to let users decide if they can or want to view a specific type of content in their feed right now. If you're scrolling through your timeline at work, you maybe want to display the recent upload of your favourite nude photographer as a blurry box and only reveal the actual shot after an extra click, like for example Reddit and Mastodon encourage:

![reddit nsfw mode](/assets/2022/analog-nsfw-blurhash-combined.webp)

Source: [r/analog post](https://www.reddit.com/r/analog/comments/z5dajl/la_sunrise_contax_g2_35mm_portra400/)

Technically reddit does not use blurhash, but, at the time of writing, a combination of a processed jpg, which their servers blur, and a [CSS blur][css blur] filter.

Mastodon on the other hand uses the blurhash algorithm which saves some bandwith compared to having an actual image file, but emits less immediate detail:

![Mastodon NSFW mode](/assets/2022/mastodon-blurhash.webp)

Source: [Mastodon post](https://mastodon.art/@Saltybretzel/109396720818864733)

## Try it out

If you want to try out how your blurhash previews would look, you can play a bit on the [blurhash playground][blurhash playground]. It's still a bit rough around the edges, but it supports different aspect ratios in contrast to the official one website.

The images are not leaving your browser, but are processed by the TypeScript library in that very browser window.

[blurhash]: https://blurha.sh/
[css blur]: https://developer.mozilla.org/docs/Web/CSS/filter-function/blur
[blurhash playground]: /tools/blurhash


Blurhash is an algorithm to save a tiny version of an image while the high
resolution version is be...

What is a Blurhash?


Let's check out how to host a [gemini][gemini] capsule based on the content you have in [hugo][hugo] already!

For this little tutorial, we'll use the Hugo [Getting Started guide](https://gohugo.io/getting-started/quick-start/) and create a small blog with exactly one blog post and then start serving it over `gemini://`.

The markdwon to gemtext conversion and serving will be done through some GO packages, so remember to install [go][go].

## Setting up Hugo

Firstly we'll set up hugo, either through your package manager or through the GO toolchain. Open up a terminal and run the default tutorial instructions:

```bash
hugo new site quickstart
cd quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> config.toml
hugo server
```

Now we also need some example content, so we'll add `my-first-post.md` to the `content` directory:

```markdown
---
title: "My First Post"
date: 2022-11-20T09:03:20-08:00
---
## Introduction

This is **bold** text, and this is *emphasized* text.

Visit the [Hugo](https://gohugo.io) website!
```

now we should see the post show up at `localhost:1313`. So far so good!

## Serving Gemini from Hugo Content

There are three related projects all by [n0x1m][n0x1m] that are going to enable us to serve gemfiles from the existing hugo content. What they did is to grab some hugo code from a few versions ago to generate an identical path tree and they also serve it over gemini, perfect, right?

With the go toolchain installed you can run:

```
go install github.com/n0x1m/hugoext@latest
go install github.com/n0x1m/md2gmi@latest
go install github.com/n0x1m/gmifs@latest
```

Now we can run:

```
hugoext -ext gmi -pipe md2gmi
```

and it will build the `.gmi` file output in the `public` directory `\o/`.

Next, to serve the content we can run:

```
gmifs -autoindex
```

and visit: `gemini://localhost`

What we should see in a gemini browser is this:

![](/assets/2022/gmifs-serve-hugo.png)

Brilliant, we can conclude it works!

Now we just need to deploy it somewhere and point a domain at it.

## Deploying hugoext / gmifs with Docker

I'm used to Docker at this point and I don't have the nerve to learn 100 different hosting providers own config syntax, so we'll write a small Dockerfile.

One of the providers I've been wanting to try out is [fly.io][fly.io], but you can obviously deploy anywhere where Docker images are supported, like heroku, AWS, Azure or whatever you can think of.

```Dockerfile
FROM golang:1.19-alpine

# install GO dependencies
RUN go install github.com/n0x1m/hugoext@latest
RUN go install github.com/n0x1m/md2gmi@latest
RUN go install github.com/n0x1m/gmifs@latest

RUN mkdir -p /var/site
WORKDIR /var/site

COPY content /var/site

EXPOSE 1965

CMD ["gmifs", "-autoindex", "-autocertvalidity=666"]
```

In the `CMD` line we add `"-autocertvalidity=666"`

because by default our certificate the self-signed cert would only be valid for 1 day:

```
-autocertvalidity int
        valid days when using a gmifs provisioned certificate (default 1)
```

Now let's build it with `docker build . -t hugo-gmi` and run with:

```bash
docker run --init -p 1965:1965 -t hugo-gmi
```

which maps the exposed port to the same post on the host system. If you get an error, it's because you still have `gmifs` running on the same port in another terminal.

Accessing `gemini://localhost` should now again show you your website.

### Deploying Docker Image to fly.io

If you want to use [fly.io][fly.io], head on over and create an account first, you'll need to punch in your credit card if you want to deploy.

You'll get some things for free, but be vary of excess bandwidth you might have to pay for:

> Up to 3 shared-cpu-1x 256mb VMs
> 3GB persistent volume storage (total)
> 160GB outbound data transfer 

First we need to install the [flyctl][flyctl], for me that is:

```bash
curl -L https://fly.io/install.sh | sh
```

Then you will want to authenticate your flyctl to your fly.io account, so you run:

```bash
flyctl auth login
```

which will open your browser and let you authenticate the request, after that you're logged in on your system.

Next, to trigger the interactive dialogue for deployment, we run the following in our `quickstart` directory or where your gmi-hugo blog is located.

```bash
flytcl launch
```

We answer a few questions, but the defaults are pretty good. We need to answer with `y` when it comes to if we actually want to deploy.

![flyctl region selection](/assets/2022/flyctl-region.png)

Now we can watch some terminal output of our image being built in production, after it's done we can go to our fly.io dashboard, find our app and access the random subdomain with our gemini browser!

![fly.io dashboard and lagrange](/assets/2022/fly-dashboard-lagrange.png)

Now you just need to grab your DNS settings and point `gmi.yourdomain.com` at this IP address or host to make sure you can be reached at the desired address!

## Closing Thoughts

I got incredibly lucky finding the awesome projects thata are gmifs and hugoext because they were exactly my use case. Trying out fly.io was very pleasant and really perfect for tiny projects and niche blogs!

Your deploy process might vary, you might already have a Dockerfile and might just want to copy your content directory to a different project directory that will only have the dockerfile above to push to a separate remote.

For my own blog I had to use a slightly different approach to get my content in shape to be served through `gemini://jonathanmh.com`, because I don't personally use hugo.

[fly.io]: https://fly.io
[n0x1m]: https://github.com/n0x1m
[go]: https://go.dev/
[hugo]: https://gohugo.io/
[gemini]: https://jonathanmh.com/p/getting-started-with-gemini/


Let's check out how to host a [gemini][gemini] capsule based on the content you
have in [hugo][hugo...

Gemini Mirror from Hugo


Let's have a look at how to start a minimal web server on Windows to make your frontend development easier. This is useful for especially vanilla JavaScript development or if you want to make sure your asset loading works as it would on the server.

Lots of tutorials either focus on one underlying programming language only or they suggest installing more complex servers like nginx or apache through XAMPP which is usually a lot more configuration than you need to do.

We'll use [Chocolatey][chocolatey] to install either node, ruby, python or php which all come with a small web server built in, that you can start on any port to serve your frontend project from the directory you're in with Powershell. You can use any other terminal you have installed, it's just a default on Windows, feel free to use your preferred one.

## The Example Project 😎

Our example Project will have 3 files:

* index.html
* index.js
* games.json

which will mimick a site that loads additional data from a server, which in our case is just a JSON file with some structured data in it, a list of our favourite games!

index.html:

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Jonathan's Gaming Site</title>
</head>
<body>
  <h1>A list of my favourite games!</h1>
  <div id="games"></div>
    <h2>debug:</h2>
  <pre id="debug"></pre>
  <script src="index.js"></script>
</body>
</html>
```

* `<script src="index.js"></script>` loads our `index.js`

games.json:

```json
[
  {
    "name": "Warhammer 40k: Darktide",
    "developers": [
      "Fatshark"
    ],
    "publishers": [
      "Fatshark"
    ],
    "released": {
      "year": 2022
    }
  },
  {
    "name": "Valheim",
    "developers": [
      "Iron Gate Studio"
    ],
    "publishers": [
      "Coffee Stain Publishing"
    ],
    "released": {
      "year": 2021
    }
  },
  {
    "name": "Deep Rock Galactic",
    "developers": [
      "Ghost Ship Games"
    ],
    "publishers": [
      "Coffee Stain Publishing"
    ],
    "released": {
      "year": 2020
    } 
  }
]
```

This is our structured data source, you could also imagine that this is a network request to an API.


index.js:

```javascript
console.log('index.js starts executing!')

fetch('./games.json')
  .then((response) => response.json())
  .then((data) => {
    const debugElement = document.querySelector('#games');
    const outputElement = document.querySelector('#games');

    debugElement.innerHTML = JSON.stringify(data)

    let ul = document.createElement("ul")

    data.forEach(element => {
      let li = document.createElement('li')
      li.innerText = `${element.name} (${element.released.year})`
      ul.appendChild(li);
    });

    outputElement.appendChild(ul);
  });
```

* `fetch` lets us load data from another file or server response
* `element.appendChild()` lets us put newly created HTML elements into existing ones

If we were to just double-click our `index.html` from a file manager, it would load the JavaScript file just fine, but as soon as our JavaScript tries to make a network request, it would show us an error in the browsers JavaScript console, since the browser will not let JavaScript make a "network" request to the local file system.

This puts our pages in a bit of a broken state, as you can see here:

![](/assets/2022/non-cors-file-path.png)

The CORS error in Firefox:

```
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///home/jonathan/projects/simple-servers/games.json. (Reason: CORS request not http).
Uncaught (in promise) TypeError: NetworkError when attempting to fetch resource.
    <anonymous> file:///home/jonathan/projects/simple-servers/index.js:3
```

The CORS error in Chrome:

```
Access to fetch at 'file:///home/jonathan/projects/simple-servers/games.json' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.
GET file:///home/jonathan/projects/simple-servers/games.json net::ERR_FAILED
(anonymous) @ index.js:7
Uncaught (in promise) TypeError: Failed to fetch
    at index.js:3:1
```

These are not the only contexts for these errors, you can also mitigate them with server headers if you're not trying to load something through the `file://` protocol.

My usual default solution, because I always have Node.js installed would be:

```
npx serve .
# or
npm install -g serve
serve .
```

but it also works with lots of other languages and runtimes, which we're checking out in the next section.

The *working* version of the test site is supposed to look like this:

![](/assets/2022/cors-simple-server-success.png)

## Installing Dependencies with Chocolatey 🍫

You don't **need** to do this step, you can also install [node.js][nodejs] or any of the options from the official websites, it's just more convenient to me to have a package manager like `brew` on MacOS or `apt` or `pacman` on Linux available on Windows as well.

If you open your Powershell as an Administrator after installing [Chocolatey][chocolatey], you can for exmaple install ruby to run a server.

![](/assets/2022/powershell-as-admin.png)

```Powershell
choco install ruby
# cd C:\Users\jonathan\simple-server
ruby -run -e httpd . -p 8080
# if: webrick is not found. You may need to `gem install webrick` to install webrick.
# gem install webrick
```

and you can visit your tiny ruby server at `http://localhost:8080`.

Now your Powershell output should look something like this:

![](/assets/2022/powershell-ruby-server.png)

This also works for python:

```Powershell
choco install python3
# cd C:\Users\jonathan\simple-server
python -m http.server 8080
```

You can even run this straight from within VScode or any other editor that has any terminal integration, you can bring it up with `CTRL+J`:

![](/assets/2022/vscode-python-server.png)

This also works in Sublime and a few others, but I would recommend getting in the habit of having a terminal open in the directory where you're editing code because it's a very common practise in lots of languages.

## Adding Python3 to Path on Windows 🐍

I had to add the Python3 installed through Chocolatey to my Path manually, which was fairly simple if you find your "Advanced System Settings":

![](/assets/2022/windows-powershell-python-path.webp)

You'll need to add a new line to the Environment which is the path to where `python.exe` exists, so we need to check where chocolatey installs it.

## Summary 💡

Now we have a super simple web server that we only run when we want to, so not as a continous background service, that runs on a port of our choosing like 3000 or 8080 and it lets us develop websites much closer to real world conditions than only using the file system like back in the old Frontpage days 🙌.

Further Reading:

* [MDN: local dev server](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server)

[chocolatey]: https://chocolatey.org/
[nodejs]: https://nodejs.org/


Let's have a look at how to start a minimal web server on Windows to make your
frontend development...

Simple Webserver on Windows


In this post I'll illustrate how to pay next-to-nothing for email sending by using the Mailgun FLEX **plan**, if you complete the maze of design dark patterns, that is the mailgun web application.

I was recently in need of a developer friendly email plan to facilitate signup confirmation and password reset emails for a project and one of the services that sprung to mind was [mailgun][mailgun]! 

Obviously not the only mail sending service on the market, but they do in fact offer a pretty good price! It's 1000 mails free and after that about 1 USD per 1000 mails, which is great for not having to host your own email infrastructure that would probably get insta-spam blocked by the big email players anyways.

[The honorable Mr. Wixfort](https://wixfort.de/), when we were debugging a server issue, alerted me that I was in fact on a trial that would charge me 35$ a month for about 50 emails (instead of the first 5000) free ones, because my sending volume is VERY low, so I started digging around for alternatives.

I was sure there was some cheap low volume option, but I couldn't see anything on their pricing page:

![mailgun plans](/assets/2022/mailgun-plans.png)

As I was about to cancel my mailgun account I did find the option to pay as you go with 1000 free emails sends a month! The shady thing is that you need to complete the following steps first:

1. Sign up on a free trial for the Foundation Plan
1. Enter your credit card information
1. Complete cell number verification
1. UNSUBSCRIBE from the trial (this is not actually relevant for you if you just want to send transactional emails, your domain stays verified as well)

I have illustrated the steps below, starting in the billing interface:

![](/assets/2022/mailgun-billing.png)

Unsubscribe

![](/assets/2022/mailgun-flex.png)

Next

![](/assets/2022/mailgun-flex-plan.png)

Finished! You're now "unsubscribed", yet on a "pay as you go" PLAN and you can still send emails.

This must have been the worst UX experience I've had in recent times and the business desire here STRONGLY outweighs the user experience by several orders of magnitude.

You can read about the [flex plan in the mailgun help center](https://help.mailgun.com/hc/en-us/articles/203068914-What-Are-the-Differences-Between-the-Free-and-Flex-Plans-), which doesn't exactly show you how you get there, but at least it tells you how to set a global sending limit for your account.

[mailgun]: https://mailgun.com



In this post I'll illustrate how to pay next-to-nothing for email sending by
using the Mailgun FLEX...

Cheap Email API: Mailgun Flex Plan


Mastodon is gaining popularity in admirable spikes, especially from Twitter, which brings out a lot of user experience flaws, floods the [r/mastodon][r/mastodon] subreddit with support requests and lots of hobby admins face more serious server load, resulting in more serious bills for hosting.

In this post I want to take a brief look at common questions, misunderstandings and that there is no simple answer to a lot of questions.

Firstly, I will describe **good** things as things **I like**, since values are relative and we all have our little lens of memories and experiences. Secondly, I'll try to include intention and expectation of possible users, like what a non tech-savvy user would expect from *similar* apps to cull the what-about-ism that's befalling too many conversations about how comparable social networks are.

## Good Things About Twitter

Some good things about for example Twitter is that there's a lot of brain power and money at work which make some things incredibly convenient and hard to replicate. People are used to NOT having to think about a list of things like:

* What server they're on, one brand usually means one thing
* Caring for which format a photo is in before they upload it (AAAH! LET ME UPLOAD WEBP)
* Well indexed and fast search for entities like accounts, posts, etc
* Near real-time status updates on timeline and threads
* Content moderation, to some degree
* Reliability of services! Big tech outages make mainstream news these days

Some of these issues are architectural, others are more human factors.

Somebody who starts their own server and suddenly gets 10000 signups in the 8 hours they sleep will have an outage unless they made preparations and are willing to more or less blindly spend more money. Also if they don't share the responsibility they alone are a liability by being a single point of failure.

Technical issues are generally solvable, but most come down to money. It's unreasonable to expect some things to be as fast, smooth and well functioning without a similar effort being spent.

## Good Things About Community Driven Media

This is not specific to Mastodon, it's for all indie media, it's just the elephant (heh) in the room right now! Things will always evolve and develop, some mistakes we will repeat as a species over and over, let's see where this one goes.

### Trust Issues 🧐

By all of the questions that come up around Mastodon, like:

> How do I know if the admin of the server changes password storage so they can steal my password?

I like to believe that people develop a more critical understanding of the old saying that

> The cloud is just someone else's computer

I like that, because it's an uncomfortable and relevant discussion that only flares up once in a while when Apple starts scanning everyones iMessages or facebook ignores creative usage of its API for abysmally manipulative political targeting.

### Independent Communities 🪐

In a way each instance in the Fediverse, if it's a clone of something that exists or something different, is a bit of indie community. It's maybe the smaller version of the forums that have fallen to the mighty social networks. There are some great pools of interests, hashtags and servers to dip and dive into. Lots of them will not last forever, but that wasn't really the point in the beginning.

If we don't see communication as pointless, but every connection made and conversation had a win for the involved parties, that's cool with me. I'm having a lot of fun, no matter if this will be a new "big" or even "default" social network.

### Government Communication 🔏

The German government was quick on their feet to launch their own instance at and it's in fact populated with active accounts, which I think is brilliant, if you meet an account it can easily be *verified* by being from that domain, which is closed for registrations from external users.

It's a different topic how much a domain should mean for trust, but it's a common practise how things work on the web. You look at the URL if you want to be sure the site you're on is actually your bank or whatever more sensitive service you're about to use.

More importantly the government IT can take care of their own accounts and don't need to go through any authentication procedures with the social network to be recognised as the real deal, which is great!

![](/assets/2022/social-bund-mastodon.wepb)

## Filter Bubbles? 🧋

One of the topics that comes up in the server context of having more *specific* servers for generally *like minded* people is filter bubbles, which we all somehow live in, but which can be more extreme when you spend a majority of your social media time in an even more isolated one.

Even newly established Mastodon instance [journa.host][journa.host] for journalists, by the New York Times struggles with backlash and moderation in the new federated model where the different parts of the system can stop listening to each other:

> Zach Everson, one of the journa.host administrators, responded that he agreed with Ms. Molloy, then added, “Banning someone for posting a link to an NYT article sets a precedent that we really need to work through.”

Source: [Chaos on Twitter Leads a Group of Journalists to Start an Alternative](https://www.nytimes.com/2022/11/21/style/mastodon-twitter-adam-davidson.html)

An admin from a reasonably busy instance with 80 thousand active users recently posted:

> What's it with people reporting every single person they dont like.. :amaze: 
> Please, stop with that.
> This is not #Twitter. Please use features like mute or block if you don't like people but stop reporting otherwise I'll start banning people who keep reporting for nothing :blobhammer: 
> I'm trying to keep things running with so many new people and it's such a waste of time to hear whatever you don't like
> Otherwise go waste Elon's time, not mine

Source: [mstdn.social/@stux/109369969599633401](https://mstdn.social/@stux/109369969599633401)

This is a human aspect of moderation that can both be very time intensive but that the fediverse also has an opportunity to do better, because your "chosen home instance" will probably be closer to what you consider acceptable and can differ from the average or other poles of the network.

**Update 2022-11-25:**

Another post regarding basically gaming federation policies was posted by Jeffrey Phillips Freeman titled [Eugen Rochko, CEO of Mastodon, Caves to Nazi's Agenda](https://jeffreyfreeman.me/eugen-rochko-ceo-of-mastodon-found-to-support-nazis-agenda/) and deals with automation and claims that some things are about looks and not resolving actual issues.

## Technical Difficulties 🔥

As teased earlier, it's not all nerds bringing *superior tech* to the table, especially the UX is a challenge for lots of people, that post [boomer screenshots](https://www.reddit.com/r/Mastodon/comments/z03kqe/what_am_i_doing_wrong_here/) on reddit or express their frustration in not being able to join and look around:

> I was hoping Mastodon would surprise me and not just be the standard “FOSS always has very poor UX.” I can't even make an account.

which I think is perfectly justified. It's a frustrating experience wanting to try something out and then meeting a closed door or your entire freemail provider being blocklisted by a server that doesn't accept `@gmail.com` or `@hotmail.com` in new user applications. This would not happen anywhere else, as social media and messengers usually try to spend venture capital to create the highest monthly active user numbers in the whole industry.

Allegedly tumblr, the site that gutted itself after purging NSFW content, plans to implement ActivityPub to connect tumblr to the Fediverse. However, that's [just a tweet](https://twitter.com/photomatt/status/1594577983028740096), we'll need to see what actually materialises.

Self-hosting is not a path that the average person can take, probably not even with a one-click server provider. In contrast to [Fab][fab]'s perception of me, I am somewhat aware of the barrier of entry, but I want to respond to his takes anyways:

<TextBreakdown notes={[
  <><p>There are some proponents of single user instances, but I don't share their approach, what I believe is that people should have the possibility to own their data or to have great liberties who to trust with them. Host your own instance if you want to, but I wouldn't portrait it as a viable solution for most people. Social media with the ambition for above average adoption should work for everyone at a cost much lower than 10€ a month.</p>
  <p>I am very priviledged to be able to just spin up servers left and right and try running part of the network, because I happen to live in a country where I got paid to study lots of nerd stuff and now have money to spare from my day-job. This still leaves an interesting question, what does the network cost at different levels of scale and who's going to pay for it?</p>
    </>,
  <>I have a LOT of nerdy connections, but I'm also building UX for normal people that either are using mobile devices as their main device. I'm not wearing the tech-utopia hat here and I don't believe that if everyone was just a bit more <em>developer</em>, everything would be well. I want things to be simple and attainable for the average person.</>,
  <>For me this isn't the point and I'm not romanticising it. It's fine to get excited about things, tell your friends to check it out, but a lot of people set themselves up for disappointment if they expect a drop-in twitter replacement both based on the unambiguity of a globally accepted network (and brand) and how much people will choose convenience over everything else.</>
  ]}>
<p>This is exactly why distributed networks like this are doomed to fail. <mark data-note-index="0">If all of the users are admins, only people that are willing to be admins will be users.</mark> And that's probably less than a few hundred thousand people in total.</p>
<p>[...] Your perspective is <mark data-note-index="1">warped by being in a bubble that has nothing to do with reality</mark>. I've been there. I used to believe Linux was a viable operating system for most people. Or that Valve was going to bring AAA games to Linux. <mark data-note-index="2">Or that people were going to move from Twitter to federated social systems en masse. And stay there 😂</mark>.</p>
</TextBreakdown>

Obviously I can't prefix every light-hearted retoot with that, so I hope it helps that I SPELL IT OUT here 😛.

Source: [the thread on Mastodon (how on brand!)][joke-thread]

PS: If you want to see Fab and me shout at each other regularly, you can check out [our YouTube channel where we play Tarkov](https://www.youtube.com/@scenictarkov1849)!

[r/mastodon]:https://www.reddit.com/r/Mastodon/
[joke-thread]:https://streamers.social/@fabsh/109365589244534201
[journa.host]:https://journa.host
[fab]:https://fab.industries


Mastodon is gaining popularity in admirable spikes, especially from Twitter,
which brings out a lot...

Mastodon Mythbusting: November 2022


In this post we're going to have a look at how to build a component to annotate text. This is probably useful for linguistic analysis, I primarily built it for song lyrics and to do some communication breakdown of some messages I get that **are wrong on so many levels**, that I need visual aid to break them down.

## Genius Like Song Annotation

One of the examples I thought of when building this in my head was genius.com, they have a community of people doing interpretations of lines in songs, which is a bit different than having to know every reference, but you can submit an interpretation or something you know of a specific passage, which is interesting.

![screenshot of genius dot com](/assets/2022/genius-florence-howl.png)

## Theoretical Requirements of Text Annotation

1. I want to be able to highlight words and sentences and write a bullet point about that specific piece of text below the actual text.
1. Both words and bullet point need to be coloured in the same colour.
1. Different words should be able to be referenced by the same bullet point, for example "The egg is in the basket", both *egg* and *basket* should have the annotation: *noun*

This is turning out to be a bit like annotated text in a school book for learning languages, but that's not too bad. School books aim to clarify and visualise knowledge for 100% of the seeing population, so I guess I can't get a more versatile role model than that.

The search for a colour palette went down a bit of a rabbit hole, so I'll just explain my colour choices here instead of later:

```css
.breakdown {
	--color-opacity: 0.666; /* heh */
	--color-hl-fallback: hsla(56, 85%, 60%, var(--color-opacity));
	--color-hl-01: hsla(331, 72%, 51%, var(--color-opacity));
	--color-hl-02: hsla(223, 100%, 70%, var(--color-opacity));
	--color-hl-03: hsla(251, 83%, 65%, var(--color-opacity));
	--color-hl-04: hsla(23, 100%, 50%, var(--color-opacity));
	--color-hl-05: hsla(41, 100%, 50%, var(--color-opacity));
}
```

These are the colours I use and they are slightly brightened colours from the colour blindness friendly palettes collected here: [davidmathlogic.com/colorblind/](https://davidmathlogic.com/colorblind/) which are super great. Also I'm using the `hsl(a)` colour space to be able to darken, brighten, play with the opacity.

## The React `<TextBreakdown/>` Component

I needed a react component, since I'm going to use this in the context of next.js and displaying it in MDX posts for this blog, so I wanted to go for something that is fairly vanilla HTML in the elements that are passed. We're going to use the fantastic metal history song *Metal Crüe (2006)* by *Sabaton*.

The passage we want to break down a little is the chorus:

> When the priest killed a maiden in the metal church
Armored saints and warlocks watched the slaughter
Rage of the slayer forced the pretty maids
To kiss the Queen in crimson glory

Alright we have lots of metal bands we need to reference.

I started by writing the component by having the data just as variables before the render, but here's how the component works:

```jsx
<TextBreakdown notes={[<>Hello, I'm a note</>]}>
// children go here
<p>Let's see how these <mark data-note-index="0">annotated</mark> things look!</p>
</TextBreakdown>
```

We're using the `<mark>` tag here, which is [an HTML tag meant for highlighting](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark)

So both the prop `notes` and the `children` of the component are react nodes aka HTML elements. Technically these are not the same, but for all we care they are when writing content.

Now we just need to write a component that receives the props and children to do our bidding and satisfy our highlighting needs:

```tsx
// TextBreakdown.tsx
import React from "react";

import styles from './TextBreakdown.module.css';

const TextBreakdown = ({ notes, children }) => {
	const notesList = notes ? notes.map((note, index) => <li key={index} data-note-index={index}>{note}</li >) : null;

	return (<div className={styles['breakdown']}>
		<div className={styles['breakdown-text']}>
			{children}
		</div>
		<ul>
			{notesList}
		</ul>
	</div>)
}

export default TextBreakdown;
```

The important bit about this file is only this bit:

```jsx
const notesList = notes ? notes.map((note, index) => <li key={index} data-note-index={index}>{note}</li >) : null;
```

You could also just pass strings to the notes prop, however I wanted hyperlinks to work and other HTML elements like images. Even better for my workflow would possibly be to pass markdown strings, but that would escape the scope of this for now.

Here we assign the same `data-note-index` to the notes list that we already use in our content. Then we move on to styling:

```css
.breakdown {
	--color-opacity: 0.666;
	--color-hl-fallback: hsla(56, 85%, 60%, var(--color-opacity));
	--color-hl-01: hsla(331, 72%, 51%, var(--color-opacity));
  /* other colours mentioned above */
}

.breakdown mark {
	padding: 3px;
	background-color: var(--color-hl-fallback);
}

.breakdown mark[data-note-index="0"] {
	background-color: var(--color-hl-01);
}

.breakdown mark[data-note-index="1"] {
	background-color: var(--color-hl-02);
}

/* and so on until index 4 */

.breakdown li {
	margin-top: 10px;
	padding: 5px;
	background-color: var(--color-hl-fallback);
}

.breakdown li[data-note-index="0"] {
	background-color: var(--color-hl-01);
}

/* and so on until index 4 */
```

We're targeting `[data-note-index="0"]` and assign the colour for either the mark background colour or the list item background. You can also use borders or whatever you want to style, as long as you target the same index, you can give them the same colour.

This will result in a simple component:

![simple annotated text](/assets/2022/simple-annotation.png)

Now for a more advanced example where the amount of notes exceeds the amount of colours we have available, we have 6 references, but only 5 colours plus a fallback assigned:

<TextBreakdown notes={[
  <>Reference to the band Judas Priest</>,
  <>Reference to <a href="https://en.wikipedia.org/wiki/Iron_Maiden">Iron Maiden</a>.</>,
  <>Reference to the band Metal Church 🤘⛪</>,
  <>Reference to the band Armored Saints</>,
  <>Reference to the band Warlock</>,
  <>Reference to the band Slaughter</>
]}>
  <p>When the <mark data-note-index="0">priest</mark> killed a <mark data-note-index="1">maiden</mark> in the <mark data-note-index="2">metal church</mark><br />
  <mark data-note-index="3">Armored saints</mark> and <mark data-note-index="4">warlocks</mark> watched the <mark data-note-index="5">slaughter</mark><br />
  Rage of the slayer forced the pretty maids<br />
  To kiss the Queen in crimson glory</p>
</TextBreakdown>

So every reference AFTER the first 5 will get a pale yellow colour, like the last one in this example. If I ever run into this case where I can not break up the source text enough, I could also number them with some old school footnote annotations like `[1]`.

In case my styling changed since this blog post was published, here's a screenshot of what was supposed to be there 😛:

![text annotation component](/assets/2022/text-annotation-component.png)

As you can see, I'm not amazing at picking examples because obviously the song references only bands, but you can totally pass longer texts without completely wrecking the layout.

Next steps for me would be to find a good way of highlighting the relevant annotation or maybe even displaying as a tooltip, which would improve the user experience.

What are you building that requires text annotation? Let me know!


In this post we're going to have a look at how to build a component to annotate
text. This is proba...

Building a Text Annotation Component with React


When using either self-hosted or cloud hosted web fonts we can make small adjustments to the font definition in CSS that can decrease the first time page load of your site significantly. Instead of always loading the specified webfont, we can define either alternative fonts or the same font to load from the client system.

At the end of this post, there is a small utility to display all fonts on your system using Chrome.

The performance improvements for my blog for people who have the *DejaVu* font familiy installed is pretty good, on first load these fonts are loaded from disk instead of the network:

* DejaVu Sans Bold: 351kB
* DejaVu Serif: 212kB
* DejaVu Sans: 380kB

Example of the DejaVu font combinations I use on this blog at the time of writing:

```css
@font-face {
	font-family: 'DejaVu Serif';
	src: local('DejaVu Serif'),
		url('/fonts/DejaVuSerif.ttf') format('truetype');
	font-display: swap;
}

@font-face {
	font-family: 'DejaVu Bold';
	font-weight: 700;
	src: local('DejaVuSans-Bold'),
		url('/fonts/DejaVuSans-Bold.ttf') format('truetype');
	font-display: swap;
}
```

The line that can decrease the page load time for anyone with that font installed (mostly Linux users I guess), is this one:

```css
  src: local('DejaVu Serif'),
```

Which tells the client system to first look for the local font, for which you can define an array. So if there are multiple variants you'd be okay with loading instead of requiring more bandwidth or if the font can have different names, you can specify multiple possibilities:

```css
  src: local('DejaVu Serif', 'dejavu serif', 'DejaVuSerif'),
```

and so on.

This is about what I did until I found the correct name for the bold variant:

```css
src: local('DejaVuSans-Bold'),
  url('/fonts/DejaVuSans-Bold.ttf') format('truetype');
```

## Debugging Font-Loading

The easiest way to figure out **when** and **if** your font is loaded over the network is to open the browser `Network` tab and see if the request is made or when it's made to see if other content is prioritised when you define the `swap` rule.

![chrome waterfall network graph](/assets/2022/network-waterfall-font-load.webp)

We want to eliminate this network request if possible, so if the user already has our font installed.

## List Installed Font in the Browser

Finding the name of a font that you may want to substitute with a file already present on the client system can be a littly tricky, since this is a risk for people's privacy. Fingerprinting fonts is being used in the wild and there are other ways to do it by measuring the width of some rendered elements, but that's not what we're interested in here.

On MacOS you can also make use of Font Book to find the installed font, we're interested in the `PostScript name`

![](/assets/2022/fontbook-font-name.webp)

In Chrome on any platform, there is a Font permission API, so if you open the JavaScript console you can find the exact names with: 

```javascript
try {
  const availableFonts = await window.queryLocalFonts();
  for (const fontData of availableFonts) {
    console.log('postScriptName:',fontData.postscriptName);
    console.log('fullName:',fontData.fullName);
    // console.log(fontData.family);
    // console.log(fontData.style);
  }
} catch (err) {
  console.error(err.name, err.message);
}
```

after acknowledging a permission prompt.

![font permission prompt](/assets/2022/font-permission-prompt.webp)

which will output a list:

```
fullName: DejaVu Serif
postScriptName: DejaVuSerif-Bold
fullName: DejaVu Serif Bold
postScriptName: DejaVuSerif-BoldItalic
fullName: DejaVu Serif Bold Italic
```

There are a few different values, we're going to take the postScriptName for `DejaVu`, because that's already installed on a lot of systems that use open office and a few Linux distros and this is how we use it in CSS:

```css
@font-face {
  font-family: 'DejaVu Bold';
  /* this is the postScriptName value */
  src: local('DejaVuSans-Bold'),
    url('/fonts/DejaVuSans-Bold.ttf') format('truetype');
}
```

You can use the component below to see the fonts currently installed on your system listed by `postscriptName`, ready to use (in Chrome, Edge and Opera):

<LocalFontDetect />

Further Reading:

* [Chrome dev blog on local fonts](https://developer.chrome.com/articles/local-fonts/)
* [caniuse: queryLocalFonts](https://caniuse.com/?search=queryLocalFonts)


When using either self-hosted or cloud hosted web fonts we can make small
adjustments to the font d...

Webfonts: Using Local Fonts as Source


Videos are a very powerful media type of entertainment and visualisation, let's see hwo we can self host high compression videos that save bandwidth for your viewers/users and how to find out which codec to pick from.

A word of caution, lots of people, like me, do not prefer video over written text for many contexts, but to explain complex user interfaces or complex data types they're incredibly good.

This post does not apply if you are not responsible for the content distribution, if you are uploading your videos to YouTube or Vimeo that have their own transcoding machinery, you should just render what ever is convenient and high quality to you, because you have no control over the finished result that they transcode for you. This post is about producing end results that are similar to theirs.

There are lots of cases where you want to self-host video, for example if it's going to be part of a layout element or if you need more control over how your video is displayed or without third party branding and recommended videos at the end.

The video examples in this post are from our Norway Travel VLOG, that you can see in full below with a few epic drone shots and some dog and moose content:

<iframe width="560" height="315" src="https://www.youtube.com/embed/rKlQW2s-T28" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

## Installing ffmpeg 5

If you're on an Ubuntu-like distro like Linux Mint or similar, you might want to ensure you have ffmpeg 5 installed for the stable version of the av1 encoder through the PPA if necessary.

You can check your locally installed version of `ffmpeg` by running:

```
ffmpeg -version
```

```bash
ffmpeg version 5.1.2-0ubuntu1~20.04.sav1 Copyright (c) 2000-2022 the FFmpeg developers
built with gcc 9 (Ubuntu 9.4.0-1ubuntu1~20.04.1)
configuration: --prefix=/usr --extra-version='0ubuntu1~20.04.sav1' --toolchain=hardened --libdir=/usr/lib/x86_64-linux-gnu --incdir=/usr/include/x86_64-linux-gnu --arch=amd64 --enable-gpl --disable-stripping --enable-gnutls --enable-ladspa --enable-lcms2 --enable-libaom
# [...]
```

and you want to look for `5.x` and in the list of features for `--enable-libaom` to confirm that you have the av1 encoder built into your ffmpeg binary.

If they don't show up or if you want to upgrade to the stable av1 encoder you can check out the [ffmpeg 5 ppa][ffmpeg 5 ppa] and follow the installation instructions below:

```bash
sudo add-apt-repository ppa:savoury1/ffmpeg4
sudo add-apt-repository ppa:savoury1/ffmpeg5
sudo apt-get update
sudo apt-get upgrade && sudo apt-get dist-upgrade
sudo apt-get install ffmpeg
```

## What Codec is Best? VP9 vs AV1

Great about both codecs is that they are rather unproblematic in terms of patent restrictions, which historically have been an issue in mp3, mp4, m4a and other formats.

If you don't care about Edge or Safari and iOS users, you can use [av1] as your only video codec today, otherwise I would strongly recommend [vp9]. This is true for the time of writing, I would recommend checking [caniuse: vp9/av1][caniuse: vp9/av1] for the up to date support of browsers and platforms.

Let's compare the size and quality of the different encoders below, we'll use an h/264 mp4 rendered by Adobe Premiere of a vertical video trailer for instagram promoting our [NORWAY travel VLOG][NORWAY travel VLOG] 😉.

**Note:** The video examples are cut to the beat of the music, **they do not stutter randomly**, please play with audio!

Encode to `vp9`:

```bash
ffmpeg -i mobile-trailer.mp4 -c:v libvpx-vp9 -b:v 3M -cpu-used 8 mobile-trailer_vp9.webm
```

* `-i mobile-trailer.mp4` specifies the input file
* `-c:v libvpx-vp9` use the vp9 encoder for video
* `-b:v 3M` keep the target bitrate per second under/at this

<video controls>
	<source src="/assets/2022/mobile-trailer_vp9_720.webm" type="video/webm" />
</video>

Encode to `av1`:

```bash
ffmpeg -i mobile-trailer.mp4 -c:v libaom-av1 -b:v 3M -cpu-used 8 mobile-trailer_av1.webm
```

* `-c:v liaom-av1` use the av1 encoder for video
* `-cpu-used 8` use 8 threads

<video controls>
	<source src="/assets/2022/mobile-trailer_av1_720.webm" type="video/webm" />
</video>

The -cpu-used option was only necessary for av1 because otherwise it was excruciatingly slow to encode. I'm not sure if it just has a different default for now, but adding it helped it run at about the same speed of `vp9`, on my AMD Ryzen 7 2700+ at about .4 the play time of the video, so about twice the time spent playing the video.

Now that we have produced two video files, we can compare them locally:

```bash
9.1M mobile-trailer_av1.webm
 42M mobile-trailer.mp4
7.9M mobile-trailer_vp9.webm
```

As we can see they are both significantly smaller than the source file. The `av1` version is slightly larger, so we would have to tweak the averate bitrate setting to get a smaller result, we could decrease `-b:v 3M` to something like `-b:v 2500k`.

We can go with the result as is, which looks slightly sharper, especially in areas of the frame where a lot of motion happens (like the waterfall on dark rock).

## Remove Audio Track from Video

If you want to use a video as a replacement for a GIF that auto plays on a loop for comedic effect or to visualise something, you can remove the audio track instead of just muting it on the video element itself, which is a requirement for some browsers to play it at all:

```bash
ffmpeg -i mobile-trailer.mp4 -an -c:v libvpx-vp9 -b:v 3M -cpu-used 8 mobile-trailer_vp9_no_audio.webm
```

* The `-an` option will not encode any audio tracks

This will also reduce the file size slightly:

```bash
7.7M mobile-trailer_vp9_no_audio.webm
7.9M mobile-trailer_vp9.webm
```

Lastly, we can implement it as an auto-playing element with this HTML snippet:

```html
<video muted autoplay loop playsinline>
  <source src="/assets/mobile-trailer_vp9.webm" type="video/webm" />
</video>
```

If your video is not auto-playing in Safari, you likely forgot the `muted` and `playsinline` attributes.

## Converting GIFs to WEBM

If you have a hand full of GIFs and you're trying to replace them, you can use the ffmpeg line below:

```
ffmpeg -y -i jeannie.gif -c:v libvpx-vp9  -cpu-used 8 -b:v 500K -pix_fmt yuv420p jeannie.webm
```

which saves you some bandwidth as well, which will have more extreme effects on larger GIFs with higher framerates, even though a GIF is limited to much fewer colours.

```bash
656K jeannie.gif
176K jeannie.webm
```

Let me know what sort of video you're producing and if the post was slightly useful `\o/`

<video muted autoPlay loop playsinline>
  <source src="/assets/2022/jeannie-popcorn.webm" type="video/webm" />
</video>


**Credits:**

Music by Alexander Nakarada (www.serpentsoundstudios.com)
Licensed under Creative Commons BY Attribution 4.0 License
https://creativecommons.org/licenses/by/4.0/

[av1]: https://en.wikipedia.org/wiki/AV1
[vp9]: https://en.wikipedia.org/wiki/VP9
[ffmpeg 5 ppa]: https://launchpad.net/~savoury1/+archive/ubuntu/ffmpeg5
[NORWAY travel VLOG]: https://www.youtube.com/watch?v=rKlQW2s-T28
[mdn: video codecs]: https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Video_codecs
[caniuse: vp9/av1]: https://caniuse.com/?search=vp9


Videos are a very powerful media type of entertainment and visualisation, let's
see hwo we can self...