DEV Community: Christoph Grabo

Using git with multiple profiles and GPG+SSH keys

Christoph Grabo — Sat, 03 Apr 2021 00:00:00 +0000

I work across 2 computers and 3 OS, all with nearly same development setup. For work I need some special care for my git config, since I want/need access to personal repositories.

The slightly more complex version control system configuration is due to the following requirements and expectations:

I want to use my personal (and main) email address for my personal GitHub projects.
I want to use my work email address for the workplace stuff.
I want separate GPG keys for each email address.
I want to sign my commits with the individual GPG keys for each of the addresses.
I want separate SSH keys for each context (work, personal; but also for each computer).
I want to use the individual SSH keys based on the project I work on.
I want all of it happening as automatically as possible.
I want to forget that it is there.

I know, I know, this looks like a huge list of requirements. But not only is this my personal preference, partially also my workplace has some strictler rules, especially when it comes to security.

So, if you cannot get rid of the first point and do need also access to your personal persona on GitHub (or any other git based hosting platform for that matter), this article might help you to achieve it.

By the way, this approach should work for both single and multiple GitHub accounts. Since GitHub makes it easy to keep using a single account while also being a member of an Enterprise organization, I haven't bothered testing it with a true multi-account configuration, but since you will use individual SSH and GPG keys for either way your computer won't really know the difference.

SSH configuration

While git does support the HTTPS transport, in most cases you will use the more preferred way of talking git+ssh instead. So let's tackle this lower level first:

SSH Keys

If you working with GitHub you want to generate keys with the latest and greatest recommended algorithms:

ssh-keygen -t ed25519 -C "your_email@example.com"

If you work on other platforms, please check first, which algorithms are supported there.

In decreasing order of preference and security:

# prefer this if possible:
ssh-keygen -t ed25519

# this is still quite okay:
ssh-keygen -t ecdsa -b 521

# this only as a last resort option, should work everywhere:
ssh-keygen -t rsa -b 4096

# avoid this, please;
# also GitHub does not allow new keys with DSA anymore!
ssh-keygen -t dsa

More details about key generations at: https://www.ssh.com/ssh/keygen/

`~/.ssh/config`

### github

### -- PERSONAL/MAIN ACCOUNT --

Host github.com
  Hostname github.com
  User <YOUR GITHUB USERNAME>
  IdentityFile ~/.ssh/<YOUR PERSONAL SSH KEY>

### -- WORK PERSONA/ACCOUNT --

Host github.com-work
  Hostname github.com
  User <YOUR GITHUB USERNAME>
  IdentityFile ~/.ssh/<YOUR WORK SSH KEY>

### general

Host *
  AddKeysToAgent yes
  IdentitiesOnly yes
  PreferredAuthentications publickey
  Compression yes

Important note: Do not change the order of the configuration.

For each parameter, the first obtained value will be used. The configuration files contain sections separated by ''Host'' specifications, and that section is only applied for hosts that match one of the patterns given in the specification. The matched host name is the one given on the command line.

Since the first obtained value for each parameter is used, more host-specific declarations should be given near the beginning of the file, and general defaults at the end. ssh_config(5) manual

Since we will use two different hosts, we must repeat the Hostname line, but also want to specify User and IdentityFile specifically. If you use your ssh config only for git and also have only a single user name, you could move that config line into the generic section in the bottom. Though I still prefer the explicit repetition for each specific Host block.

At this point you might wonder »How is github.com-work supposed to function?« Hold that thought, we will come back to it later.

GPG key management

You want to use GPG for signing commits. Your workplace might not require it (yet), but if you have any level of trust issues, or just want to be sure that a commit was made by you and be able to prove it, use commit signing.

Interestingly GitHub does not recommend you to use a more modern algorithm and requires you to pick RSA. A bit sad, but RSA with 4096 bits seems to be still fine for this purpose.

After you have created your keys, you should grab the IDs for them:

gpg --list-secret-keys --keyid-format LONG

# I use shorter IDs and git doesn't seem to struggle
gpg --list-secret-keys --keyid-format SHORT

Example output:

/home/asaaki/.gnupg/pubring.kbx
-------------------------------
sec rsa4096/D73D7242 2021-02-14 [SC]
      AE93078BDC15BF6A84767DBBA3CBBB61D73D7242
uid [ultimate] TEST KEY <test-key@example.com>
ssb rsa4096/57047776 2021-02-14 [E]

The ID is the part after the rsa4096/ from the sec line: D73D7242

In the LONG variant it just used more characters from the whole fingerprint (which you can completely see in the line between sec and uid).

git shenanigans

The git command line interface (CLI) improved a lot over the years. I remember that I used a custom GI_SSH=… wrapper in my shell environments to make this whole host/key mapping possible, but thanks to the power of git configs this is a thing of the past.

`~/.gitconfig`

[init]
  defaultBranch = main

[commit]
  gpgsign = true

# other sections cut for brevity; add the following to the bottom:

[user]
  name = Your Name
  useConfigOnly = true

# optional (if you sometimes work outside of your regular directories)
[include]
  path = ~/.gitconfig.personal

[includeIf "gitdir:~/Development/Personal/"]
  path = ~/.gitconfig.personal

[includeIf "gitdir:~/Development/Work/"]
  path = ~/.gitconfig.work

`~/.gitconfig.personal`

[user]
  email = your.personal@email.here
  signingkey = <PERSONAL GPG SIGNING KEY ID>

`~/.gitconfig.work`

[user]
  email = your.work@email.here
  signingkey = <WORK GPG SIGNING KEY ID>

[url "git@github.com-work"]
  insteadOf = git@github.com

Explanation

include and includeIf are the key components to separate out specific configurations based on where you are on your system.

include is always pulled in, this is useful if you really want to separate out parts of your main .gitconfig.

If you only work in specific directories like ~/Development/Personal/ and ~/Development/Work/ — and this means where you also need to commit and push — then you could remove the general [include] section entirely. I keep it around, because I might have checked out a repository somewhere else and don't want to move it for a commit.

There's probably a better way to organize this, but the above has served me well for quite some time now.

I recently added the global [user] section for setting useConfigOnly = true and the name, since I only have one. useConfigOnly prevents git from guessing name and email and forces it to read it from the configuration files. If the email would be missing, git will complain the next time you try to commit or push. And you will know that something is broken in the configuration.

Important note: The trailing slashes (/) on the [includeIf …] lines are very important. If you forget them, then git would try to match only this very specific folder and ignore it for any folder within it. More details about conditional includes in the git documentation. (I totally missed that you can use them even for branches, too.)

The signingkey values should be set appropriately based on the IDs you have noted from the previous section of this article. Now when you commit anything git will use the correct key based on where the repository directory lives.

To automatically enforce the commit signing, use commit.gpgsign set to true.

Remember the question you had earlier about the weird looking Host configuration in SSH? The [url "git@github.com-work"] section is the counterpart making it work, because git will do the translation when you are in your company's repos.

What will happen is the following:

You are in a work related repository.
You want to fetch/pull the latest changes or push your local state to the origin.
Since git will load the work config, it replaces the regular URLs having git@github.com in it with the value of the [url …], here git@github.com-work.
git reaches one level down and uses ssh for the communication.
SSH sees a github.com-work host and tries to find all matching configurations for that, including the exact one we have defined above.
SSH will ignore our personal configuration, because the regular github.com does not match anymore.
SSH picks up your work identity file for authentication with GitHub's server.
SSH will also use the actual Hostname instead of Host (translating it back again).
Everyone is happy. \o/

What's with this [init] block you haven't mentioned before?

Since Git 2.28 you can set a name for the default branch when creating a new repository. Be a good citizen and avoid offensive and negatively connotated terms. The wider developer community seems to like "main" as a good replacement for the previous default name. You can read more about renaming existing default brances on GitHub.

Bonus

To quickly check which config is used execute the following command in a repository:

git remote -v

The URL should provide you a quick hint if the correct profile is used.

Alternatively you can also run:

git config --show-origin --get user.email

This will also print where the final value was retrieved from.

Git came a long way and I'm very glad and happy that we can have such setup without a lot of manual tinkering and workarounds. Gone are all my custom scripts, snippets, and .envrc's for that purpose, which were also not completely platform agnostic.

Rust/Wasm on AWS Lambda@Edge

Christoph Grabo — Tue, 16 Mar 2021 00:00:00 +0000

tl;dr: Check out the repo and give it a spin for yourself.

I sat down yet again and took some of my learnings into a repository, so we have a starting point.

As of today (January 2021) AWS only offers two languages for Lambda@Edge: Python and Node.js. Both are available in relatively decent versions, too.

Since I have never bothered with Python too much in my life, but have my fair share of experience with JavaScript (JS) and node, I stuck to the latter as the trampoline environment for the setup. Also I know that it comes with WebAssembly support out of the box, which wouldn't be the case for Python anyway.

So what is it gonna be anyway?

As you've maybe guessed the project will be some Rust, which gets compiled down to WebAssembly. This artefact then can be loaded and executed in the node environment.

A word about performance: I have not evaluated a "JS vs Wasm" comparison, and it's also not part of this exercise. There have been people and article in the past vouching for one side or another, all with their own benchmarks. So I won't bother you with that and advise you to take your own measurements.

WebAssembly will not beat all JavaScript code, especially very fine-tuned one. V8 (the underlying JavaScript engine for both Chrome and Node.js) is a very performant beast and comes with just in time (optimizing) compilation for further boosts.

The Rust code in Wasm clothing can give you probably certain garantuees you miss from JavaScript, but again you have to evaluate if the benefits are worth the effort.

Potentially you might also consider to switch to Python as your runtime instead. At least that language should have real integers as far as I know. 😉

No doubt you can build and deliver very fast and also safe programs with Rust/WebAssembly. Especially if you need some specific algorithms and computations where JS/node might not be the best and you would resort to some (probably C-based) native libraries anyway.

There are only a few issues with that:

You have not full control of the execution environment of your edge functions. Sure, you can introspect with a test function what you're dealing with, but how sure will you really be, that the environment on CloudFront does provide the exact same system and system dependencies as your local development environment (or the non-edge Lambda environment for that matter)? AWS has a track record of not providing you with reproducible local environments. In fact, it looks like they get away with it even further, since the announcement for containerization support for regular AWS Lambda. People, who know me, also know that I'm not a big fan of big docker images, but I'm afraid that's what we will see now happening there. I hope AWS promotes good containerization guidelines to prevent that waste-of-storage mess. Furthermore I really don't want to see docker on the edge for that reason. One can just hope, right?
You work in a very constrained environment. Check the current limits for Lambda@Edge: the zipped code can use up to 50MB on the origin side and only 1MB max if it shall be deployed for the viewer side. Of course, this is usually still plenty of spaces for most use cases, packaging up plain JS results in very small archives. But once you take the first issue into consideration, then this could actually become another problem for you.

The size restriction can be mitigated for JS-only code pretty easily by bundling the code with WebPack, Parcel, or Rollup. General advise is anyway to never deploy the unoptimized package especially when you want to push it to the edge. The node_modules folder grows very big, can still have quite some bloat even after an npm prune --production, because it only looks at packages, but not the content of them. Yep, my minimalism brain kicked in again.

The system dependency problem can only be solved by using solely pure JavaScript libraries and packages. That might work for a while, but eventually some use case might demand a non-JS solution (either a native library or some executable).

For example let's say you want to build an image transformation function and want to use sharp, a very well-known package in the JS ecosystem, then you already end up with around 37 MiB of data in your node_modules folder alone. Zipped up it's still around 13 MiB. That might be enough for you to run it as a trigger on the origin side of your CloudFront distribution; it's just about showing you how quickly a node project can grow.

If size and dependency management are not an issue

Maybe you love Rust (or any frontend language capable of being compiled to WebAssembly).
Maybe you love WebAssembly.
Maybe you do not have good JavaScript/Node.js expertise in-house.
Maybe you want to build your product with better safety.
Maybe it should be more robust, too.
Maybe you want to show AWS, that we need more than just Python and Node.js on the edge.
Maybe you have some other valid reason to escape that limiting cage.

Whatever your reasons are, I hear you.

AWS is improving on one side, but also loosing it on another. When it comes to CDNs (Content Delivery Networks) and Edge Computing, the competition is now sprinting ahead of AWS.

I cannot say a lot about Fastly's offering, it's mostly behind some beta doors, and mere mortals like myself are not allowed to peek. They have their fastlylabs, but that's for experimentation, not the final offering. So I don't even bother to check it out.

I can tell a bit more about Cloudflare though, because their edge computing offering is available and affordable to small businesses and individuals (even free in most cases). Check out Workers, really do! I have already played around with Workers and KV storage, it's a quite pleasant experience. I might write about a setup for them in the future as well.

Let's get started

GitHub repository to follow along:

https://github.com/asaaki/rust-wasm-on-lambda-edge

$ tree -L 1 -a -I .git # output truncated for brevity

.
├── .github - GitHub Actions workflow and dependabot
├── .gitignore
├── Makefile - very convenient make targets
├── README.md
├── fixtures - simple test fixtures and script
├── node - Node.js wrapper
├── rust - Big Business Here!
└── <and some more …>

Ingredients

Makefile for project level management
TypeScript (TS) for the Node.js part
Type definitions for AWS Lambda
Rollup as the bundler
Rust for the, well, Rust part
wasm-pack for WebAssembly building
zip to package up the function for upload
Example fixtures and code to have a very quick and dirty request test
GitHub Actions workflow for continuous integration (CI) purposes

On your machine you need to install Rust, node, wasm-pack, and zip, if not present yet. The workflow for GitHub Actions has that already sorted out for you.

This article won't give you steps to get your local development environment set up, please use a search engine of your choice and look up how to do it.

Node.js wrapper

I adopted a rollup based approach, since it's quite easy to get configured and also something we use at work. I always found webpack a little bit too cumbersome, and parcel is just yet another new kid on the block. I'm pretty sure you can adjust the project to your needs. All we need here is: compile TS to JS and bundle up everything into a single JS file. In the past I found the WebAssembly dependency management very tricky, in the end I used a plain "move the .wasm file into the final bundle" approach, which just works fine, because I did not want to inline the WebAssembly code (as most plugins try). Maybe you have a smarter solution for that, please open a pull-request in the repo. Just keep in mind: wasm-bindgen creates already a pretty decent module loader, so there is no need to work around that, but I fail to get any of these bundlers to move the wasm files along with it into the bundle output directory.

I use TypeScript here, because it gives you some nice support during development. Also the aws-lambda type definitions were useful to create the Rust structs and adjust the serialization. (AWS is actually very strict about the JSON you pass around, "something": null for absent data does not work, either it is a completely required field with a strict type like a string, or it should not be in the JSON at all).

In general for any bigger frontend or node backend project I would recommend to use TS nowadays. While not every of your dependencies might come with type definitions, at least within your own codebase you can enforce strict rules and type checks.

To make the node wrapper as slim as possible, we pass the event and context data directly into the WebAssembly and return whatever it returns.

Btw if you do return a specific struct instead of a generic JsValue, then TS checks will also kick in and use the auto-generated type definitions from the wasm-bindgen process.

For a quick baseline test and project I did not go down that road yet, as it would require to replicate all the TS specific stuff in the Rust code (wasm-bindgen cannot do everything fully automated yet). This is a great opportunity to create a utility crate for that, basically like rs2ts but in reverse direction. I wish aws-lambda-events already had those CloudFront events in it, but sadly they don't.

Yet also be aware of certain type limitations, read on to learn more about them.

Rust business logic

The Rust code is also nothing special so far.

// src/lib.rs

#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;

mod types;

use std::panic;
use types::cloudfront as cf;
use wasm_bindgen::{intern, prelude::*};
use web_sys::console;

type JsValueResult = Result<JsValue, JsValue>;

#[wasm_bindgen(start, final)]
pub fn start() {
    panic::set_hook(Box::new(console_error_panic_hook::hook));
    console::log_1(&intern("(wasm module start)").into());
}

#[wasm_bindgen(final)]
pub async fn handler(event: JsValue, _context: JsValue) -> JsValueResult {
    console::log_1(&intern("(wasm handler request call)").into());
    let request = cf::Event::request_from_event(event)?;

    // TODO: Fancy biz logic here ...

    request.to_js()
}

Note: The displayed code might not be up-to-date with the repository version.

There is one function (start) which is triggered when the Wasm module gets loaded. You can use it to set up some internal state if needed. We only used it here for configuring the panic handler; whenever an unrecoverable error happens, it gets logged via console.error, helps immensly with debugging. And as we do console logging anyway, there shouldn't be any significant overhead for that part. The compilation output will probably a bit bigger because it needs to store more information for the better panic output.

The other—probably way more interesting—function is handler, which takes the inputs from the JS side, does … a lot of nothing, and returns a request JSON blob for CloudFront to deal with.

Currently the machinery reads the arbitrary JsValue and tries to deserialize it into a struct, so we can deal with it in code. This is definitely not the most efficient way of doing it, but the conversions in and out really avoid some current existing pain points.

For example wasm-bindgen has not a great story around Rust enums, for now only very simple C-style enums are allowed. Meaning: for our CloudFront (CF) event data, which can be more strictly typed into either a CF request or response event, this does not play well with Rust's richer enums, as we cannot convince wasm-bindgen to use them. There is an open issue around this topic, but it was created just recently and thus no work has been done yet. Similarly Rust's Vec is also not fully supported yet (see issue 111), which might be the even bigger issue for some of us.

Workarounds can be a lot of Options and serialization skips, as I do internally anyway.

Some transformation overhead can be addressed by using serde-wasm-bindgen, but in my example repo I'll use it only for the input side (deserialization). On serialization a collection like HashMap or BTreeMap gets turned into an ES2015 Map, which is unfortunated as well, because they cannot be JSON stringified.

As you can see, currently there are trade-offs to be made in all corners, but that shouldn't stop us to explore further.

In the current state of the project I have provided pretty strict structs and enum for the CloudFront event data, it even surpasses now the TypeScript interfaces, which makes my point from the previous section pretty obsolete now. I still wish it was easier to autogenerate Rust types from TS definitions. The only good thing about CloudFront related data is, that it won't change that much … if at all. Some APIs in AWS have been stable for years now, so a "write once, use forever" approach might be sufficient.

Performance

Read about my poor man's performance testing of AWS Lambda@Egde functions on my blog. The tl;dr is that it's equally fast compared to a regular node.js setup.

Conclusion

This is all great news: you can run WebAssembly on AWS Lambda@Edge without a noticable performance penalty. Now write your Rust code and run it on the edge.

Of course I do hope that in the future this will become more native. There's a lot of development happening in the WebAssembly space.

Shrinking SVG code: ❮path❯ not always bigger

Christoph Grabo — Thu, 15 Oct 2020 15:52:42 +0000

I love vector graphics. I love SVG. And I love a good session of byte squeezing.

When I was triggered by Medium's new logo, I played around with their SVG source for the symbol icon, what they call "Unfinished Ellipses" — let's not go into the "beauty" of it … (to be honest I don't like it; it does not look very inspiring to me)

This post is more about some tiny revelation I had during my SVG icon optimization session earlier today.

Most of the time the <path> element is used for more or less complex graphics. But in the case of Medium's symbol, it was clear they could have used very simple shapes (aka primitives) like <circle>, <ellipse> (yes, Medium, that is a thing! :P), and others.

And most of the time the final code with such primitives should be much shorter, as a circle or ellipse can be described in a very concise fashion, while a path only knows how to draw straight lines, curves, and arcs. All of them involve usually more data than the primitive version.

Example: circle vs path

<!-- simple shape: a circle -->
<circle cx="500" cy="500" r="500"/>

<!-- converted to path -->
<path d="M1000 500a500 500 0 01-500 500A500 500 0 010 500 500 500 0
         01500 0a500 500 0 01500 500z"/>

So all is good and we can go home, right?

Well, not so fast.

TIL There are exceptions when the code of your primitive can be bigger than a complete path definition. And I think the line element will be always heavier compared to its path counterpart.

Example: line vs path

<!-- line primitive: -->
<line x1="0" y1="80" x2="100" y2="20" />
<!-- path equivalent: -->
<path  d="M0 80l100-60"/><!-- 16 chr -->

A single line would not make such a difference, but with many of them that can add up easily. And given that you usually combine many lines into a single path you will start saving even more.

So, unless you draw only a few circles, ellipses, and rectangles you will probably be better off with a single or combined path element.

Oh, and a very easy way to optimize your SVG code is the site SVGOMG. I know I can install svgo, but for a quick and dirty pass I always visit that page and paste my source and see how much it can reduce.

Final note: Always verify your assumptions. I was not 100 % sure about the overhead or savings of the primitive shapes, I'm glad I ran tests to get some proof. And don't be afraid if your experiments tells that you were wrong. That's life. 🤷🏻‍♂️

Sticky navigation bar without JavaScript

Christoph Grabo — Wed, 14 Oct 2020 22:48:25 +0000

Have you ever wanted to create a sticky menu, but without the hassle of writing extra JavaScript for it? CSS got you covered now!

The key for success is the property position: sticky. And despite it being marked as "partial support" for the majority browsers, it is working pretty well. The "partial" is due to the fact that some browser don't deal with that property correctly in some table setups. If you do not use tables and don't want some stickiness there, you're good to go.

The following is my code change on my personal site:

Before

JavaScript

const navbar = document.querySelector('.navbar');
let sticky = navbar.offsetTop;
const navbarScroll = () => {
  if (window.pageYOffset >= sticky) {
    navbar.classList.add('sticky')
  } else {
    navbar.classList.remove('sticky');
  }
};

window.onscroll = navbarScroll;

Stylesheet

.navbar {
  position: relative;
}
.sticky {
  position: fixed;
  top: 0;
  left: 0;
}

After

JavaScript

// nope

Stylesheet

.navbar {
  position: sticky;
  top: 0; /* it does not reposition right away,
             but determines at which point it sticks */
}

As the comment states, you will need top to tell where to stick once the element scrolled to it. Meaning: as long as you have not scrolled the bar up to top zero of your current view, it will keep scrolling up. Afterwards it stays there.

Not tested, but this could also work in all other directions. Someone up for a bottom bar? ;-)

Conclusion

I think 2 lines of CSS are better than several in CSS and JS.

What's not present yet is a way to apply different style when stuck or not, since there is no CSS selector for that. Dunno if that will ever come, but one can hope.

I recently blogged about this and JS usage in general in my article »How I wrote JavaScript to avoid JavaScript« - don't worry, you do not have to throw away everything like I did. But I want to give you some food for thought. Maybe you realize you solved your problems with way too much JS.

Also check out the specs and development of HTML and CSS standards, there are always interesting things to discover. One of the biggest changes in recent years were flexboxes and grids, I guess many web designers welcomed these additions.

Rust 2021

Christoph Grabo — Thu, 08 Oct 2020 16:33:33 +0000

Over at my home blog I wrote about what I want and wish from Rust in the next year and beyond.

Also note that I will not republish full articles on dev.to anymore.

So, please bookmark and visit markentier.tech instead (and it even has Atom/RSS feeds if you like).

Make git faster in WSL2

Christoph Grabo — Thu, 08 Oct 2020 15:18:30 +0000

For quite some time I wondered why my prompt was so slow in my Linux environments under WSL2. After some digging I finally figured it out: not only has my prompt tool an issue, but also in general the filesystem performance of WSL2 is not great.

On my blog I tell you the full story and provide you a solution on how to speed up git for you within WSL2.

I came not up with the fix, so I'm very grateful for the work of others. Writing it down and provide some explanations is my way of contributing back to the community.

Nokogiri installation errors on macos

Christoph Grabo — Sun, 30 Dec 2018 00:00:00 +0000

Quick answer:

bundle config build.nokogiri --use-system-libraries && bundle install

This was originally posted on my blog here.

Every other year or so I want (or need) to install dependencies for a Ruby application on my Macbook, directly on the host instead of a VM or container. Mostly it's a Rails app.

And every time our most "loved" dependency bails on me: nokogiri. I think it always fails on a Mac. (At least once.)

Because I never go directly to the documentation of whatever refuses to work, I usually google my way to a solution.
In my case this was then harder than it should have been, so I write this down here for me as a reminder.

The next time I google it, I hope to find my own blog post and will make the same expression at the end. Again.

How does it fail

Try to get and build the dependencies:

# maybe a fancy Rails application
bundle install

And after a while …

# snippet
An error occurred while installing nokogiri (1.8.5), and Bundler cannot continue.
Make sure that `gem install nokogiri -v '1.8.5' --source 'https://rubygems.org/'` succeeds before bundling.

In Gemfile:
  rails was resolved to 5.2.1.1, which depends on
    actioncable was resolved to 5.2.1.1, which depends on
      actionpack was resolved to 5.2.1.1, which depends on
        actionview was resolved to 5.2.1.1, which depends on
          rails-dom-testing was resolved to 2.0.3, which depends on
            nokogiri
# /snippet

Now if you run what is suggested …

gem install nokogiri -v '1.8.5'

Building native extensions. This could take a while...
ERROR:  Error installing nokogiri:
  ERROR: Failed to build gem native extension.

# ... snip ...

Undefined symbols for architecture x86_64:
  "_iconv", referenced from:
      _main in conftest-451598.o
  "_iconv_open", referenced from:
      _main in conftest-451598.o
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
checked program was:
/* begin */
 1: #include "ruby.h"
 2:
 3: #include <stdlib.h>
 4: #include <iconv.h>
 5:
 6: int main(void)
 7: {
 8:     iconv_t cd = iconv_open("", "");
 9:     iconv(cd, NULL, NULL, NULL, NULL);
10:     return EXIT_SUCCESS;
11: }
/* end */

You can also check the logs for later reference, too.

/Users/chris/.rbenv/versions/2.5.3/lib/ruby/gems/2.5.0/extensions/x86_64-darwin-17/2.5.0-static/nokogiri-1.8.5/gem_make.out
/Users/chris/.rbenv/versions/2.5.3/lib/ruby/gems/2.5.0/extensions/x86_64-darwin-17/2.5.0-static/nokogiri-1.8.5/mkmf.log

This is a problem that it cannot work with the iconv library currently present for linking.

Alternatively also another library can cause some troubles: libxml2

Then the output might look like …

Running 'compile' for libxml2 2.9.8... ERROR, review '/Users/chris/.rbenv/versions/2.5.3/lib/ruby/gems/2.5.0/gems/nokogiri-1.8.5/ext/nokogiri/tmp/x86_64-apple-darwin17.7.0/ports/libxml2/2.9.8/compile.log' to see what happened. Last lines are:
========================================================================
      _parseAndPrintFile in xmllint.o
  "_xmlXPathEval", referenced from:
      _doXPathQuery in xmllint.o
  "_xmlXPathFreeContext", referenced from:
      _doXPathQuery in xmllint.o
  "_xmlXPathFreeObject", referenced from:
      _doXPathQuery in xmllint.o
  "_xmlXPathIsInf", referenced from:
      _doXPathDump in xmllint.o
  "_xmlXPathIsNaN", referenced from:
      _doXPathDump in xmllint.o
  "_xmlXPathNewContext", referenced from:
      _doXPathQuery in xmllint.o
  "_xmlXPathOrderDocElems", referenced from:
      _parseAndPrintFile in xmllint.o
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

How to fix it

Well, if one would pay attention to the output, sometimes the output already tells you what could be done.

For the libxml case:

IMPORTANT NOTICE:

Building Nokogiri with a packaged version of libxml2-2.9.8
with the following patches applied:
    - 0001-Revert-Do-not-URI-escape-in-server-side-includes.patch
    - 0002-Fix-nullptr-deref-with-XPath-logic-ops.patch
    - 0003-Fix-infinite-loop-in-LZMA-decompression.patch

Team Nokogiri will keep on doing their best to provide security
updates in a timely manner, but if this is a concern for you and want
to use the system library instead; abort this installation process and
reinstall nokogiri as follows:

    gem install nokogiri -- --use-system-libraries
        [--with-xml2-config=/path/to/xml2-config]
        [--with-xslt-config=/path/to/xslt-config]

If you are using Bundler, tell it to use the option:

    bundle config build.nokogiri --use-system-libraries
    bundle install

Note, however, that nokogiri is not fully compatible with arbitrary
versions of libxml2 provided by OS/package vendors.

So, the last commands are the things you should consider for a bundler based project.

bundle config build.nokogiri --use-system-libraries
bundle install

You can check the config:

bundle config

Settings are listed in order of priority. The top value will be used.
gem.test
Set for the current user (/Users/chris/.bundle/config): "rspec"

gem.mit
Set for the current user (/Users/chris/.bundle/config): true

gem.coc
Set for the current user (/Users/chris/.bundle/config): true

build.nokogiri
Set for the current user (/Users/chris/.bundle/config): "--use-system-libraries"

The file ~/.bundle/config for completion (shown as diff):

  ---
  BUNDLE_GEM__TEST: "rspec"
  BUNDLE_GEM__MIT: "true"
  BUNDLE_GEM__COC: "true"
+ BUNDLE_BUILD__NOKOGIRI: "--use-system-libraries"

And that's it. Fixed!

Nokogiri documentation

If I had consulted the nokogiri documentation at all, I also would have got the hint earlier:

Nokogiri will refuse to build against certain versions of libxml2, libxslt supplied with your operating system, and certain versions will cause mysterious problems. The compile scripts will warn you if you try to do this.

It focuses on libxml2, but the steps also help with the libiconv issue, too.

🤦

Minimalism, Focus, Clean

Christoph Grabo — Tue, 01 May 2018 00:00:00 +0000

Start with whatever you have, but don't stop reaching for something better. Why I love minimalistic and simplistic web designs.

One: Nothing is forever

A few days ago I pointed a colleague to my freshly hatched blog, because I wanted to show him my recent post. In the end we didn't even chat about the post, but web design and the job (he's a web designer), challenges and opportunities and interesting stuff to do and creativity and the past and the kind reminder that I'm not the youngest anymore. What kept nagging in the back was the comment about my (now past) design.

Oh man you need need need to update your site

Want some design help on that bitch?

As much as I appreciate the help and support, but especially for my personal project I tend to do as much as possible on my own. Also taste is highly subjective; I live in Berlin, Germany, I see stuff, I know what I'm talking about. And I do not need to agree with the style and display of others and others' work. I nod (or shrug), I go, and probably forget about it ten minutes later anyway.

But there was a point to the above message. Something he couldn't even know. The design was a temporary solution, and I dug it up from a 4 years old proof of concept work I've done. It was the quickest way to get my site up and running without looking too shabby. I didn't need to seek for a pre-made design somewhere else and I didn't need to spend too much time on creating one from scratch.

While an old design doesn't need to be bad at all, mine wasn't really finished and fully thought through though. And so this sparked the urge to do something about it.

I also knew that I wanted to change the logo independently from a redesign, but now all things came together.

Two: Anything is possible

I love minimalism, I really do. And I wish I could follow this principle a bit more in my daily life, for now the digital one needs to be sufficient enough for this.

Not all my previous designs and themes were minimal, simple, or even easy to use. Some were artistic; I think in the early 2000s artsy, graphical and very detailed themes were a thing. Sadly I forgot to bookmark (and screenshot) some of my favourites, I cannot even remember the names of the people, so no hint how to find them again. Well, it's history anyway.

In the end I always come to enjoy a design and layout which is not overloaded with stuff and cruft. Sometimes I will add something here and there. And just a bit later I think I should remove something again.

Also: minimalism doesn't necessarily mean total emptyness or absense of everthing. But I came to love the huge blanks, and the vast endlessness of the plains.

<!-- basic SVG logo markup for markentier.tech -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
  <path fill="none"stroke="#0c1328"
        stroke-linecap="round"
        stroke-linejoin="round"
        stroke-width="64"
        d="M480 506v208-128s0-72 64-72 64 72 64 {…}"/>
</svg>

Three: Something is changing

I love vector graphics. And so I love SVG. I remember to have always liked this image format since discovery. It was quite sad, that it also took quite some time to have proper cross browser support. If you ignore old IEs, then the present day situation is awesome. SVG v2 is not there yet (and I really want to get rid of the xlink namespace), but the currently implemented spec is already good for a lot of use cases.

One perfect example are logos and icons. As you already see, my website's logo is delivered and rendered as SVG, I couldn't get it smaller than that anyway, any PNG, GIF or JPEG would always be much, much bigger than the following path definition:

M480 506v208-128s0-72 64-72 64 72 64 72v128-128s0-72 64-72 64 72 64 72v128-128s0-72 64-72 64 72 64 72 1 85 1 128c-1 28-24 54-24 54-126 161-348 207-527 111-179-97-262-309-196-501 66-193 261-309 462-275 200 33 347 206 348 409

Yes, exactly, this is all. It is probably the most compact version I could use. Hence the usage of a 1024x1024 viewBox and big numbers, just to avoid decimals, which carry the extra dot. This is a pro-tipp btw, always design your stuff on a huge canvas 1000 pixels or bigger in dimensions. Then with tools like SVGOMG (or already in your vector graphics program) you can save the file with zero decimals (so only integers) without loosing significant information.

If you want to get more excited about SVGs:

https://www.youtube.com/watch?v=lMFfTRiipOQ

https://www.youtube.com/watch?v=ADXX4fmWHbo

There are definitely more, but above videos should be a nice starting point. I might come back to this topic in the future.

Four: Everything is evolving

The screenshot above might look a bit weird (when you read this article on markentier.tech), because it fits perfectly into the current design.

I think this represents an interpretation of minimalism. At least one I like. There didn't went too much process or sciene into it, at least not consciously. Of course, I'm aware of some color basics, contrasts and a basic understanding of accessibility. It won't be perfect yet. And probably I won't bake in some changes you'd like to see.

But I do believe that my articles should be consumable without too much distraction or fatigue or strain. Since it is heavily color range reduced, color blind people (or with partial deficiency) should be able to read and navigate the site without loosing anything or getting confused. I haven't tested screenreaders, but I hope I don't use design magic which would impact your experience here.

I also still work on the performance aspect of it. And I also push for more modern browsers. Since it is my personal blog, I think I can afford to "loose" some customers, or at least give them not the full pleasure by not being always fully backwards compatible.

If you have questions or just want to know in more detail how something works here, ping me on twitter or open an issue at the repo for this site, I'm happy to explain, glad if you can learn something, and I welcome feedback and corrections.

TIL: rebeccapurple

Christoph Grabo — Wed, 11 Apr 2018 00:00:00 +0000

While polishing my theme, I discovered Rebecca. I love it, when technology gets some human touch.

I was just reading about the color data type in CSS over at MDN when I saw that a new named color will be part of the CSS Color Module Level 4.

There was a link to this Codepen blog post.

Rebecca was Eric Meyer's daughter. She was diagnosed with cancer. On her sixth birthday she left us.

This past Friday, June 19th, 2014, the community to which Eric has given so very much has seen fit to name #663399 as rebeccapurple with his permission.

Eric Meyer is probably most well-known for reset.css.

More TIL: Btw the changes for CSS 3 to 4 are also interesting from a technical perspective: https://drafts.csswg.org/css-color/#changes.

Hitchhiker's Guide To Structured Data

Christoph Grabo — Tue, 03 Apr 2018 00:00:00 +0000

A tiny journey to the building blocks of the semantic web and how they make our lives much easier.

“There is a theory which states that if ever anyone discovers exactly what the Universe is for and why it is here, it will instantly disappear and be replaced by something even more bizarre and inexplicable. There is another theory which states that this has already happened.”

—Hitchhiker's Guide To The Galaxy

When I started using computers, I never thought about if and how they could help me to do things — and if that in turn would improve my life. I automatically assumed that we invented tools, machines, devices, phones, computers, and so on because we wanted to make our lives better, and to think less about tedious tasks by making the complex and especially complicated ones easier and more usable.

In the late 90s I not only learned but experienced that computers are connected. There was this thing called internet, mostly advertised in the form of WWW, the world wide web: gazillions of documents more or less linked to each other. Mostly plastered with flashy animations saying that this place is under construction. And the <marquee> tag made us feel as important as breaking news or a stock market ticker.

Ah, yes, the good old internet. In the beginning quite static and mostly text, but it became richer, more versatile, dynamic, and included images, audio, and video. Besides the static sites, we built web apps, APIs and made the internet a place to interact with each other and with machines.

Nowadays our fridge "Marvin" can tell us via Twitter that he feels quite empty and sad

As a kid I read tons of books, mostly fiction, of course, but I remember I visited our library in the village quite often and borrowed books explaining the world to me. But I consumed so much, I couldn't keep all the information in my head, nowadays I'm not significantly more knowledgeable than decades ago. I remember bits and pieces, but more importantly, I usually remember where I need to look for the actual data to fill in the gaps.

I grew up with Google from the beginning. And while the old and manually maintained catalogs and directories were a good starting point to explore the digital universe, search engines made my life easier. Now I didn't even need to keep an index and graph of information fragments in my head anymore, I could shift to the skill of asking the right questions.

But there are a few problems with most general purpose search engines. The easiest way to build an index is to crawl the internet and grab the full text of every page discovered and connect it to keywords. Later when somebody searches for this keyword they will get a huge list of results. The algorithms became smarter, the better you can formulate your query, the more relevant and condensed the list will be.

But if you think about it, you can already ask very specific questions, and most search engines wouldn't really be able "to get it" right from the beginning.

"What are the books the author Douglas Adams has written?"

If you would have tried this maybe 10 or even just 5 years ago and you got lucky, then some result on page one would have pointed you to an article about his publications. If you're not using Google or WolframAlpha the situation is still quite disappointing.

Today I'm quite impressed how this works out:

As you can also see, the first organic result is about the author on Wikipedia, only the second one is close to what I was asking. But the top bar with the book covers is rocking it! (I first tried with Google.de and there it was just the 3rd result.)

And I will make a bold statement here: giving you such specific and contextually relevant information is not possible solely based on some full text search index; I believe this was driven by structured data (and potentially stored in a graph database … maybe).

My internal QuickCheck program narrowed it down to "douglas adams books" , but this is not the point (although parsing the input of a search box is probably a nice adventure on its own).

We can further decompose our query and figure that it consists of a tuple: "douglas adams" and "books". The first one describes the name of a person, the second one describes an entity type, and obviously we want to find a connection between this very person and the books he wrote. Since people rarely mentioned which books they have read, the query parser can already make an educated guess here and put as a relationship type a "has written" (also "has published" could work).

Or expressed in a pseudo query language and very simplistic:

SELECT * FROM books WHERE author = "Douglas Adams"

Of course, first you would need to resolve an actual author/person entity from your database:

SELECT id FROM people WHERE name = "Douglas Adams"

And then you realize that your people table/database could have multiple entries, and you would try to filter based on occupation or hobby. Maybe you have them ranked by popularity and will just take the highest ranked entry. Another option is to resolve the full query for each person and check which one has written the most books (if any at all) and use this one.

Whatever the approach is, you need to have your data stored in a structured way. And if you want to build a search engine, a knowledge database, or any kind of application querying and presenting such information (but not storing all the information itself) you need to rely on other sources providing them in a machine consumable way.

The idea of structured data and a semantic web is not new. And if you have used any blogging software then you also used some aspects of structuring: categories and tags.

Depending on your needs you even introduced your own taxonomies to describe and differentiate your articles. As an example: you're a movie reviewer and classify your reviews based on mood, target audience, and genres; all of these dimensions help you to describe your data, make it more discoverable, support consuming systems, and directly or indirectly give your readers more context and meta data, usually in a quicker and easier way, so they can decide if they want to dive deeper into your blog or look somewhere else.

The article previews/cards on Facebook and Twitter are also driven by structured data. When you look into the source code of some HTML pages you can spot some interesting meta tags with names or properties like "og:title", "twitter:creator", or "article:author". They are used to fill the pieces of the preview. And to be honest — you will most likely click on a blog post when it has a nice cover image and description line won't you?

It took us years to bring in more data, or to take advantage of the full potential of structured data, but nowadays this concept is the foundation of the web. Even with AI on the rise machines can do their job best if they can process the data in a structured way.

I think the art is to display content in a pleasant, human-readable manner and unobtrusively enrich it with machine consumable semantic information. This so that we can build interfaces and applications that can make sense of all of the data, and then visualize it in a different and more approachable way.

If you want to see what structured data can look like, then head over to wikidata:

These entity pages are very formal and not the most beautiful ones to read about a person's life, but they contain very valuable information by describing what this entity is about and what kind of relationship it has to other entities.

Such data is designed to be consumed by other services. For example the infoboxes on the right side of Wikipedia articles are mostly supplemented with wikidata information.

Some people have built tools to nicely visualize such data:

How could you use the structured data from wikidata for your own project?

You have built a website for your international book club. It comes with a knowledge base, which supports already 42 languages. While managing the content for the authors and books is pretty easy with Contentful, you realize that localization is sometimes painful, because you have a hard time to figure out what the translations of each person's name are.

Don't panic!

A friend of yours comes up with the idea to create a UI extension for Contentful, where you can look up the wikidata and automatically fill the translation fields for the names and other common properties. She has even developed a first prototype for you:

github.com/asaaki/cf-wikidata-ui-extension-example

You really like it and start to think about how to automate a lot of other steps. For example the extension could fetch all the known books and create drafts for each of them and link them back to the author entry. Since wikidata also provides links to other Wikimedia services you could store them with your knowledge base articles as well. You integrate a lot of links to other sites and maybe want to create some kind of preview box similar to Twitter Cards.

With well maintained structured data the possibilities are unlimited. So, go out, explore, and build awesome stuff.

“Curiously enough, the only thing that went through the mind of the bowl of petunias as it fell was Oh no, not again. Many people have speculated that if we knew exactly why the bowl of petunias had thought that we would know a lot more about the nature of the Universe than we do now.”

—Hitchhiker's Guide To The Galaxy

So Long, and Thanks for All the Fish! 🐟

Progressive Web App

Christoph Grabo — Sun, 01 Apr 2018 00:00:00 +0000

markentier.tech is a Progressive Web App now, too. What does it mean and why are PWAs so cool? Main reason: it is about speed!

Progressive Web Apps (PWAs) are web applications that are regular web pages or websites, but can appear to the user like traditional applications or native mobile applications. The application type attempts to combine features offered by most modern browsers with the benefits of a mobile experience.
—Wikipedia: Progressive Web Apps

I haven't really followed the development of Progressive Web Applications (short: PWA) for quite some time. And I think the last time I experimented with anything around this topic was, when Application Cache (or AppCache) was still a thing. So yeah, long time ago.

I have forgotten about web site/app optimization, simply because I had no real web site to build and maintain for years. The sites I had were either abandoned or I didn't care so much about the performance of them.

The very first question a lot of people might ask is:

Why even bother to read about it, if all I'll make will be a static site anyway?

Well, if you do care about web performance and speed, you might want to consider all the tools available to you.

If you in full control of the output (HTML, CSS, JS, images, fonts, ...) you have already lots of opportunities. You can minimize and compress the files. The HTML, CSS, and JavaScript stuff is fairly easy, for all of them exist online services or CLI executables.

But do not forget your assets like images (and audio/video if you host them yourself), most of them can be made smaller. PNG and JPEG are still the most used image file formats (well, also GIFs for animations), WebP is there, but I haven't really seen serious usage yet. Each format usually supports either lossless and/or lossy compressions. I still prefer PNG as my standard image format, and I like that there are tools out there helping me to squeeze out the last tiny bit to get to a pretty small file size.

Tools for minification and compression

Before I come to the PWA part, let's have a look at what can (and should) be done, no matter what kind of website you have.

HTML

So far I will only mention my go-to tool here: tidy-html5. I elaborated a bit further in my last post, when I wrote about changing my static site generator.

On the other hand the overhead of bloated and whitespace cluttered HTML pages is proably not the biggest issue when it comes to fat sites.

Stylesheets (CSS) and JavaScript (JS)

Instead of recommending a specific tool I'd rather point to projects like webpack, parcel, or your favourite static site generator of choice with proper support. Also if you use a service like Netlify, that you can enable asset optimization and they will take care of the byte crunching for your, the same goes for the

Even if you use WordPress I know that people have written nice plugins to help you with such task. Nobody needs to do this by hand anymore. The same goes for images as well, but for reasons I dedicate it its own section:

PNG and other images

While services like Netlify claim to support compression of images, I'm pretty sure they will have trade-offs to publish and deliver your site faster. Since images are one of the biggest pieces of the total page weight, I think they deserve more attention beforehand.

First of all do you know which size you need already? Do not simply put your desired image unaltered into your blog post. Unless you always choose the too small images, you probably end up embedding way too huge files instead. Nobody really needs that 3000x5000 photograph when reading your article. If you want to provide them that original file for later usage, give it a link to it for download. So resize the image to your needs. Consider all the usual presentation layers. Most people can live with a 1024 pixels maximum on either height or width, depending on your theme you might be able to use even smaller default sizes.

I use an aspect ratio of 2:1, so my default image dimension is 1024x512, which is used for my cover and further images. I use this maximum as default even though my article body width is a bit smaller. The reason is that the cover image is also used for Twitter Cards (and Facebook) presentation. Both platforms either support or suggest bigger sizes, but for now I think this is overkill.

As said, I love PNGs, even though for photos the JPEG format might be better suited. Anyway there are a bunch of tools for PNG optimization.

The most well-known is ImageMagick, which can be used for a lot of different image formats. I used it especially for resizing and generating my thumbnails of the cover images. Resizing down to the visibly rendered size saves already tons of bytes and therefore bandwidth!

Speaking of thumbnails I go even further, because they cannot be only small in dimensions, but highly reduced and compressed, since they serve as a visual hook, but do not need to be the prettiest pictures ever.

So something neat is the reduction of the color palette with pngquant; people familiar with GIF optimization now that this helps already a lot.

Second is done by optipng. pngquant already can do a lot of heavy lifting, so maybe the companion doesn't so much afterwards, but maybe it will find a file for further optimization.

Initially I also had pngcrush in the pipeline, but after checking the actual byte size of the files I saw that it mostly increased afterwards; I removed it, because I'm not interested in de-optimization of my content. 😅

For GUI lovers there is a handy tool for macOS users: ImageOptim. This works on a bunch of image file formats and with quite some tools under the hood.

Caching

Minimization and compression are just the beginning of a fast served site. Once all the files are up on a server, waiting to be delivered all around the world, they also do not change that often. Especially your very static pages with all the assets are unlikely to change (like blog posts and about and imprint pages).

So, to prevent a constant flow of all the bits and bytes for each request, we want to cache them, and ideally as close to the user as possible, so that the next time they request the exact same data, they are served from their devices instead. This becomes highly efficient for repetitively used and requested files like CSS and JS, which are shared across your whole site. Also your logo and header images do not need to travel each time that way.

Intermediate steps are server-side caches and CDNs by the way, but I'm not focussing on this right now.

Also: Caching in itself is a tricky story and should probably deserve its own article.

Generally speaking the Cache-Control header is a good starting point and helps browsers to determine, what and for how long it should try to keep a file in at hand instead of fetching it from the internet.

Next level: Progressive Web

Although I have heard of Progressive Web Application already, I never paid much attention to it. I surely thought that it might be cool to look into this topic, once I figured out a web app project. A static site was definitely not a trigger. I could not have been more wrong.

When I run the Audits tool in the Google Chrome developer tools, I had no idea what this Lighthouse stuff is. I remember that in previous version of Chrome, there was this PageSpeed Insights tab, which is deprecated and only available as a web service nowadays. It's still a useful tool on its own. But Lighthouse provides much more performance and optimization data.

So when the report was generated I was a bit confused that it had this Progressive Web App section. Sure, some sites might need this information, but the whole internet is not only about dynamic apps, is it?

Well, it was about time to dive into this previously neglected topic again. I read and learned about the Web App Manifest (manifest.json) and the PWA Checklist.

One important step for the baseline was:

All app URLs load while offline

With the suggestion to fix it by doing this:

Use a Service Worker.

Oh, I also read about them, but for the same reason above I just ignored this topic, too. If you want to learn what you can do with them, check out serviceworke.rs

As a starter I went for the pretty simple setup provided by Google. But also iterated further. Tell me if something doesn't work out well or the site just looks ugly (unstyled).

The cool thing is, that it not only makes your site perform faster and cache items, but also provides offline functionality.

The screenshots above are an example of how it would look like, if you decided to add markentier.tech to your homescreen. Coloring the address bar is also a nice gimmick.

Until now I cannot tell you much more about PWAs yet, since I'm learning the stuff right away on the go.

I encourage you to look into this topic as well. I hope I provided you with enough links to start your own journey.

From cobalt.rs to gutenberg

Christoph Grabo — Wed, 28 Mar 2018 00:00:00 +0000

I wish I could have the features of both tools, but for now I will use gutenberg over cobalt. A tiny migration and feature comparison story.

While cobalt is a pretty nice and easy static site generator written in Rust (in the vein of Jekyll, the famous tool used for GitHub pages), I struggled a bit. Especially that the stylesheet compilation is not enabled by default yet, but also other tiny annoyances or missing features played into that. I still want to stick with Rust and the only other active option here is gutenberg. But to be honest, this one also comes with its complications.

Cobalt is your tool for a quick blog-like setup, because it supports the usual two different article types of (static) pages and blog posts. Gutenberg doesn't really have such distinction, and therefore you need to be more elaborate if you want to achieve the same.

Not all perfect, but we're getting there

Since both projects are pretty young, they share similar shortcomings: the template libraries are usually not feature complete yet or behave a slightly bit different than their spiritual role models. Mostly one can work around those issues, but it's a bit painful still.

Gutenberg shines here a bit brighter, since it supports macros and shortcodes. Especially the latter is something nice, because I can quickly enrich my pages with snippets, which are usually weird or hard to be done purely in Markdown. Embedded HTML is not the nicest thing and if I can abstract them away, I'm all in for that.

Another tiny plus: Gutenberg is supported by Netlify, therefore I do not need to install the binary somehow on their side. Now I can let it build the final site on deployment and skip committing a prebuilt project. Pretty sure I could have done it with cobalt as well, but this way it worked out of the box.

Tools, tools, tools

Speaking of tooling: I was a bit adventurous and bundled two tiny binaries anyway and it worked.

`fd` - the simpler find, written in Rust

fd advertises itself as A simple, fast and user-friendly alternative to 'find'.

And according to their benchmarks it is incredibly fast. But I also like the easier command-line options. The interface is designed for the common cases. And it is written in Rust. Have I mentioned that I love Rust? No? ;-)

`tidy-html5` - getting rid of awkward whitespaces and indentation

The granddaddy of HTML tools.

The granddaddy of HTML tools. — well, yes, tidy is a pretty old tool, I probably used it already 10+ years ago.

I recommend this helper to anyone who gets slightly shitty HTML generated from their CMS, static site generator or whatevery is producing such files automatically.

Usually there is no harm in leaving the HTML pages as they are, as long as they render in most browsers. I like my pages nice and clean. And I wish most programs would come with tidy builtin. I know, I know, I'm such a dreamer.

Here a snippet how I use fd and tidy for my post processing:

# from my Makefile:

TIDY_SETTINGS = -q -m -w 0 -i \
                --indent-with-tabs yes \
                --indent-spaces 2 \
                --tab-size 2 \
                --clean yes \
                --join-styles yes

build-tidy-html:
  fd -p public -e html -x sh -c "echo {} && tidy $(TIDY_SETTINGS) {}" \;

find all files with extension .html in the public folder
apply command with -x option; since I want to do multiple things I have to wrap it with sh -c "…"
tidy removes all superfluous whitespaces and empty lines, properly indents the tags, and cleans up the inline styles, which is quite handy for the code snippes, because gutenberg (and cobalt) do not use a global/external stylesheet for the syntax highlighting

If you want to learn more about all the possible flags and options, check out the tidy reference for details and explanations.

This step helps me a lot getting a consistent output for my whole site, also I will get warnings/errors in case I messed up something in my templates and markup.

More about `gutenberg`

In the gutenberg repo itself is a nice comparison between gutenberg , cobalt , hugo , and pelican. Since I'm not really interested in non-Rust generators I just keep rephrasing the differences between the first two.

The only thing gutenberg has not is the data files feature of cobalt, which can be seen as flat file databases in YAML, JSON, or TOML format. You would maybe need this if you organize and use a lot of data while site generation step. While it sounds nice it is not something I really need yet.

What I really appreciate in gutenberg is the wide support of tiny features complementing Markdown based editing. Similar to GitHub wikis you can internally link between documents. Furthermore you get automatically linkable headers and can autogenerate a table of contents (TOC). The template engine is pretty nice (I still need more definable types like arrays and maps, something I could do with liquid based engines). Themes, Aliases, and Pagination are not my main concern yet, but at least the latter could come in handy pretty soon. What I really like are the (custom) shortcodes, I loved it already years ago as a WordPress plugin (or you remember them even from bulletin board/forum software). And the macro system is quite useful when you do base your design on a theme. As mentioned above the stylesheet compilation based on SASS is quite nice, just because splitting up the styles in logical chunks helps to better reason about them.

Currently there is a discussion about custom taxonomies which is interesting.

Oh and I totally forgot a tiny but really convenient feature: the automatic page reloading while editing and tweaking. People who also build React apps will love it.

Wishlist

I have more items I'd like to see:

probably a plugin system, although I have not an idea yet, how it could look like; but since gutenberg itself seems to be a pretty modular codebase there might be an option to get this going (extension language does not have to be Rust though)
more "native" blog support (a collection type of blog post based on a common parent directory)
better page collection access, globally (I have seen that this is done internally already for sitemap and feed generation, we just need to abstract and expose this nicely)
tera, the template engine could probably benefit from more types and related filters/builtin functions; even with the macro system some things still feel clumsy or nearly impossible

Migrate all the things

Although gutenberg is not cobalt or Jekyll, the move was not as painful as I initially thought it would be. The template languages are similar enough, syntactically and semantically, so that adjustments were sometimes just search-and-replace, both use curlies for their tags.

Some of the shortcomings of Tera made some changes slightly more difficult, but overall nothing was totally impossible, or I could just live with a similar but simpler solution for now.

I didn't like the builtin rss feed generation and it lacks different feed formats anyway, so I work around this by creation my own feed pages in a slightly awkward way: I built "html" pages for each feed format and rename/move the files in a post processing step later. The sitemap generation was a bit more straight forward.

The biggest part of my time I spent in adopting the blog post directory structure and page traversal for the home page. And while writing this post I have an idea how to make my life easier in the future: since I'm not really using the categories (yet) I could utilize a default category page for simpler blog post listings. Will definitely try this one. (If/when we get custom taxonomies I could shift again to use categories as intended.)

The organization of post related assets is now a bit different, but maybe even easier/more intuitive. Getting the cover image URL became a bit simpler now.

Overall the migration was quite fast, less than a day or so. For how it was done I recommend to head over to the markentier.tech repository and check out the commit history.

Functions, lambdas, and "serverless"

Recently Netlify opened up their previous beta features: Forms, Identity, and Functions (Lambdas).

I have no immediate use for the forms and identity service (yet), but the functions are probably a nice feature to check out first.

As with most of their tools and support they promise that it will be easy or easier than the underlying solution. And while I haven't even actively played around with AWS Lambda yet, I tested it via Netlify's Functions feature. The free tier is quite limited, of course, but I cannot image a simpler way to get started with functions and lambdas and the whole serverless universe. Although I don't really like this marketing term, since in the end everything is running on some server somewhere. I'd rather think of the evolution after Heroku, which never claimed to be serverless, but a platform where most of the painful infrastructure administration is abstracted away. Functions and Lambdas just further narrow down the scope and surface, but still: they are really tiny applications running on managed servers and services, and a little bit more on demand.

And I have to admit, there is great appeal in such services. Especially for single person projects (like this site), where you want a little bit more than just pure static, but also do not want to invest too much time and effort in setting things up.

Because in the end all you really want is: getting things done.

DEV Community: Christoph Grabo

Using git with multiple profiles and GPG+SSH keys

SSH configuration

SSH Keys

~/.ssh/config

GPG key management

git shenanigans

~/.gitconfig

~/.gitconfig.personal

~/.gitconfig.work

Explanation

Bonus

Rust/Wasm on AWS Lambda@Edge

So what is it gonna be anyway?

If size and dependency management are not an issue

Let's get started

Ingredients

Node.js wrapper

Rust business logic

Performance

Conclusion

Shrinking SVG code: ❮path❯ not always bigger

Example: circle vs path

Example: line vs path

Sticky navigation bar without JavaScript

Before

JavaScript

Stylesheet

After

JavaScript

Stylesheet

Conclusion

Rust 2021

Make git faster in WSL2

Nokogiri installation errors on macos

How does it fail

How to fix it

Nokogiri documentation

Minimalism, Focus, Clean

One: Nothing is forever

Two: Anything is possible

Three: Something is changing

Four: Everything is evolving

TIL: rebeccapurple

Hitchhiker's Guide To Structured Data

Nowadays our fridge "Marvin" can tell us via Twitter that he feels quite empty and sad

"What are the books the author Douglas Adams has written?"

How could you use the structured data from wikidata for your own project?

Don't panic!

Progressive Web App

Why even bother to read about it, if all I'll make will be a static site anyway?

Tools for minification and compression

HTML

Stylesheets (CSS) and JavaScript (JS)

PNG and other images

Caching

Next level: Progressive Web

From cobalt.rs to gutenberg

Not all perfect, but we're getting there

Tools, tools, tools

fd - the simpler find, written in Rust

tidy-html5 - getting rid of awkward whitespaces and indentation

More about gutenberg

Wishlist

Migrate all the things

Functions, lambdas, and "serverless"

`~/.ssh/config`

`~/.gitconfig`

`~/.gitconfig.personal`

`~/.gitconfig.work`

`fd` - the simpler find, written in Rust

`tidy-html5` - getting rid of awkward whitespaces and indentation

More about `gutenberg`