Steef Hegeman

Static site by HTML rewriting

2025-12-27T00:00:00Z

Setting up static site generators is fun; making changes later is not. Having tried several, and always ending up hacking around other people’s code, I decided to write my own based on HTML rewriting.

Elevator pitch:

Write blog post content in HTML (no Markdown or whatever)
Do all preprocessing with a simple, single-pass HTML rewriter

Concretely:

Posts are stored in ./blog/slug/index.html, at their desired path
A post starts with a <meta> tag with metadata like title, date
The rest is the post body, in HTML

For example, the source of this post (full source below) reads:

<meta type = post
      title = "Static site by HTML rewriting"
      date = 2025-12-27>
<p>Setting up static site generators...

SSGs always end up processing HTML in one way or another, I just cut out the middleman. Writing in HTML directly does not exclude fancy features: for example, I have a rule that replaces <img type=code src=in.c> with syntax-highlighted code snippets. There is also good support for an HTML-oriented approach: almost every programming language has a library for processing HTML, and many support CSS selector syntax (example: img[type=code]).

I decided to implement my SSG in JavaScript, targeting Bun, which has a builtin HTML rewriting library (based on lol-html), as well as builtin APIs to quickly implement a local preview server. The whole thing is a few hundred lines, including code for the blog index, Atom feed, and a local preview server that compiles pages on-the-fly and triggers browser reloads when files change. I have a better drafting experience now than I had with off-the-shelf SSGs.

Recently, the company behind Bun was acquired by a large VC-backed AI company… So I’m not sure if I would recommend it still.

I still use some self-contained dependencies like highlight.js, another benefit of staying in the JavaScript ecosystem. But it’s nowhere near the 5000-line package-lock.json I had with Metalsmith.

In some sense, the time is ripe for more minimal static site generators. Where ten years ago I needed a CSS preprocessor for nesting and calculations, nowadays this is part of standard CSS. Writing HTML by hand is much nicer than in the XHTML days: attribute values almost never have to be quoted, and most-used prose elements like <p> and <li> often do not need end tags. If custom elements didn’t require JavaScript, I would have been tempted to do away with the static site generator entirely!

My Metalsmith-based blog lasted nine years. Hopefully, this new script holds out for another ten. And my on-and-off blogging!

Bonus: source of this post

<meta type = post
      title = "Static site by HTML rewriting"
      date = 2025-12-27>
<p>
Setting up static site generators is fun;
making changes later is not.
Having tried several, and always ending up hacking around other people’s code,
I decided to write my own based on HTML rewriting.

<p>
Elevator pitch:
<ol>
	<li>Write blog post content in HTML (no Markdown or whatever)
	<li>Do all preprocessing with a simple, single-pass HTML rewriter
</ol>

<p>
Concretely:
<ol>
	<li>Posts are stored in ./blog/slug/index.html, at their desired path
	<li>A post starts with a <code>&lt;meta&gt;</code> tag
		with metadata like title, date
	<li>The rest is the post body, in HTML
</ol>

<p>
For example, the source of this post (full source below) reads:
<img type=code src=example lang=html>

<p>
<abbr title="Static Site Generator">SSG</abbr>s always end up processing HTML in one way or another,
I just cut out the middleman.
Writing in HTML directly does not exclude fancy features:
for example, I have a rule that replaces
<code>&lt;img type=code src=in.c&gt;</code>
with syntax-highlighted code snippets.
There is also good support for an HTML-oriented approach:
almost every programming language has a library for processing HTML,
and many support CSS selector syntax
(example: <code>img[type=code]</code>).

<p>
I decided to implement my SSG in JavaScript,
targeting <a href=https://bun.com>Bun</a>,
which has a builtin
<a href=https://bun.com/docs/runtime/html-rewriter>HTML rewriting library</a>
(based on <a href=https://github.com/cloudflare/lol-html>lol-html</a>),
as well as builtin APIs
to quickly implement a local preview server.
The whole thing is a few hundred lines,
including
code for the blog index,
Atom feed,
and a local preview server
that compiles pages on-the-fly
and triggers browser reloads when files change.
I have a better drafting experience now than I had with off-the-shelf SSGs.

<side-note>
Recently,
the company behind Bun was acquired by a large VC-backed AI company&hellip;
So I’m not sure if I would recommend it still.
</side-note>

<p>
I still use some self-contained dependencies
like <a href=https://highlightjs.org/>highlight.js</a>,
another benefit of staying in the JavaScript ecosystem.
But it’s nowhere near the 5000-line package-lock.json I had with Metalsmith.

<p>
In some sense, the time is ripe for more minimal static site generators.
Where ten years ago I needed a CSS preprocessor for nesting and calculations,
nowadays this is part of standard CSS.
Writing HTML by hand is much nicer than in the XHTML days:
attribute values almost never have to be quoted,
and most-used prose elements like <code>&lt;p&gt;</code> and <code>&lt;li&gt;</code>
<a href=https://html.spec.whatwg.org/multipage/syntax.html#optional-tags>often do not need end tags</a>.
If custom elements didn’t require JavaScript,
I would have been tempted to do away with the static site generator entirely!

<p>
My Metalsmith-based blog lasted nine years.
Hopefully, this new script holds out for another ten.
And my on-and-off blogging!

<details>
	<summary>Bonus: source of this post</summary>
	<img type=code src=index.html lang=html>
</details>

CUDA tricks

2024-03-29T00:00:00Z

Getting into CUDA, I found that the general architecture is well explained, but did not find much in the form of best practices for CUDA C++. Below are some tips and tricks that I use.

Feedback most welcome!

0. Check for kernel errors

You might expect errors during kernel execution to crash your program. They don't. Use some error checking wrapper as described here.

1. Use `--expt-relaxed-constexpr` (and secretly use some STL)

The --expt-relaxed-constexpr flag for nvcc allows the usage of unannotated constexpr functions in device code. Many functions in the standard library are constexpr, and can thus be used relatively safely from device code. You don't have to write your own std::tuple or std::bit_width. The STL is officially unsupported in device code, so formally you have no guarantee that this works. But it does.

2. Use Thrust (for tests)

Thrust comes with the CUDA toolkit and can be very useful for writing some quick tests.

3. Use `--extended-lambda`

The extended lambdas extension allows you to create device code lambdas. This can for example be handy in combination with the Thrust map, sort, and reduce utilities.

4. `global` member functions

Member functions cannot be global. This can be annoying if you have a class and want to write a kernel that operates on (a copy of) it. You could write a __global__ function outside the class that takes (a copy of) the class as an argument foo, and then write foo.member every time you have to access a member—but this gets old fast.

An alternative is to do something like:


class C;
__global__ call_f(C);

class C {
    __device__ f_kernel() { ... }

    void f() { call_f<<<...>>>(*this); }
};

__global__ call_f(C c) { c.f_kernel(); }

...which is not pretty, especially if you need many of these kernels. Moreover, if C were to depend on template arguments, call_f would have to depend on them as well—or you give up on the type system and use template <class T> call_f(T c) instead.

My solution: use --expt-relaxed-constexpr and std::invoke (constexpr!) to define the following:

template <auto F, class... Args>
__global__ void invoke_device(Args... args) {
    std::invoke(F, args...);
}

The code above can then be rewritten as:

class C {
    __device__ f_kernel() { ... }

    void f() { invoke_device<&C::f_kernel><<<...>>>(*this); }
};

Much better!

The same code can be used for classes that depend on template arguments (no need to restate them in the template argument to invoke_device), and the parameter pack allows invoke_device to be used for __device__ functions with arguments as well.

Bonus: class-of-pointers and `std::shared_ptr`

A pattern that I have found to be useful is to have a relatively lightweight class containing pointers to device (or managed) memory, which is then passed to kernels by value.

It can be useful for this class to have a destructor deallocating the pointed-to device memory. However, as it is passed to kernels by value, this destructor will be called after each kernel call. A trick I took from BGHT, is to use std::shared_ptr with cudaFree as a custom deleter instead:

class C {
    std::shared_ptr<Foo> foo;

    C() {
        Foo *_foo;
        cudaMalloc(&_foo, ...);
        foo = std::shared_ptr(_foo, cudaFree);
    }
};

Features I look forward to in future CSS

2022-09-25T00:00:00Z

When writing a web page, I try to avoid JavaScript. Relying on a general-purpose programming language for layout doesn't feel right, not to mention that JavaScript can be blocked or unsupported. In a perfect world, HTML is content, and CSS takes care of the delivery.

CSS has come a long way, and websites like css-tricks.com are full of brilliant examples. With the coming of variables and calc(), and the going of Internet Explorer, JavaScript and CSS preprocessors are slowly becoming unnecessary for my simple use cases. With that in mind, here are two likely future CSS features that I am looking forward to.

October 2025: now that CSS supports nesting, I no longer use a preprocessor for this site (nor JS).

The `:has()` pseudo-class

Truth be told, the :has() pseudo-class (allowing to select a parent by its children) is probably more of a utility feature to me. I would use it in places where I would now use classes, allowing me to focus more on content when writing HTML. But Jen Simmons shows some really cool use-cases, some of which are currently impossible to implement purely in CSS. WebKit and Blink already support it. Hopefully, Mozilla will follow suit soon.

The `attr()` function

Yes, the attr() function, for referencing the value of an HTML attribute, is not that new. In fact, it is widely supported — for use in the content property. But I would like to use it in places like this:

<div class=timeline data-from=2000 data-to=3000>
	<section data-year=2000>Something happened.</section>
	<section data-year=2200>Then this.</section>
	<section data-year=2300>Then that.</section>
	<section data-year=2400>And such.</section>
	<section data-year=2800>And then, after a long time.</section>
	<section data-year=3000>Finally.</section>
</div>
<style>
.timeline {
	--from: attr(data-from);
	--to: attr(data-to);
	--span: calc(var(--to) - var(--from));
}
.timeline section {
	--year: attr(data-year);
	--reltime: calc(calc(var(--year) - var(--from)) / var(--span));
	background-color: rgb(255 140 0 / var(--reltime));
	padding: .5em;
}
.timeline section::before {
	content: var(--year);
	margin-right: 1em;
}

A timeline, where the further we go towards the end, the darker the orange background gets, giving a bit of sunset vibes.

This does not work in any current browser. For a good reason: attr(data-from) will return 2000 as a string, as will all attr(attribute) calls, and therefore the calc()s will fail. Luckily, the draft specification allows us to specify the desired type (as well as a fallback value).

The proper code (according to the current draft) becomes:

.timeline {
	--from: attr(data-from number); /* specify number type */
	--to: attr(data-to number);
	--span: calc(var(--to) - var(--from));
}
.timeline section {
	--year: attr(data-year number);
	--reltime: calc(calc(var(--year) - var(--from)) / var(--span));
	background-color: rgb(255 140 0 / var(--reltime));
	padding: .5em;
}
.timeline section::before {
	content: attr(data-year); /* re-attr() since we need a string */
	margin-right: 1em;
}

Sadly, at the time of writing, no browser supports it yet. For use cases like this, we are either bound to a preprocessor (separate class for each timeline, seperate class for each timeline section) or we must fall back to JavaScript.

To show what the above should look like, we can use a tiny bit of JavaScript:

const timelines = document.querySelectorAll(".timeline");
const sections = document.querySelectorAll(".timeline section");
const convert = attr => el =>
	el.style.setProperty(`--${attr}`, parseFloat(el.dataset[attr]));
timelines.forEach(convert("to"));
timelines.forEach(convert("from"));
sections.forEach(convert("year"));

If you are from the future, and all is well, you should see the effect below. If not, press to let JavaScript do the attr()s.

Something happened.

Then this.

Then that.

And such.

And then, after a long time.

Finally.

Neat, right?

Conclusion

The web is close to the ideal situation where HTML can be used just for content, and all styling can be handled in CSS. JavaScript will still be invaluable for interactive content, as it should be. But for simple websites, the added complexity and performance overhead will become unnecessary — W3C/WHATWG volente.

In memoriam: Wim Hegeman

2022-09-17T00:00:00Z

Wim Hegeman — 1964–2022

Wim Hegeman

26 januari 1964 – 17 september 2022

Begin dit jaar kregen wij de onwerkelijke boodschap dat Wim ongeneeslijk ziek was. Door het verdriet te kunnen delen en de steun die wij kregen bleven we overeind, en hebben we met elkaar nog veel moois mee mogen maken.

Bang ben ik niet
Met mijn dood kan ik wel
leven voor jullie had ik wel
graag nog even gebleven

Nu het moment van ‘nooit meer samen’ is gekomen, zouden we graag, met iedereen die Wim een warm hart heeft toegedragen en met ons heeft meegeleefd, afscheid van hem nemen op vrijdag 30 september. Heb je geen kaart ontvangen, maar wil je hier bij zijn? Mail ons op wim@steefhegeman.com.

We ontvangen graag herinneringen aan Wim. Bij de ceremonie zal een herinneringendoos staan. Ook kun je ons mailen.

Tot het einde heeft Wim altijd graag anderen geholpen. Daarom heeft hij zijn lichaam afgestaan aan de wetenschap.

Status update, March 2022

2022-03-01T00:00:00Z

Henceforth I plan to copy the habit of other bloggers to post a monthly status update, to remind myself to write some code every month.

While I plan to only talk about my hobbies here, I cannot ignore Russia's gruesome and deplorable invasion of Ukraine. It has to be stopped. Putin and his allies must be stopped. Their bloody and unjust attack on peace, sovereignty, democracy and human rights must never be forgotten or downplayed.

Hobbies. In the past months I have been moving from dwm on Xorg to river, to ride the Wayland wave. I have mostly got it set up now, with foot replacing urxvt, bemenu replacing dmenu, and mako replacing dunst (though it seems that dunst now also has Wayland support). Waybar replaces dwm's builtin bar for now—though I hope to replace it with something leaner: at cold boot it often takes seconds to start. Firefox's Wayland backend is papercut-free. So everything I use on a daily basis works without issue, now without tearing.

The downside of all of this is that snixembed will probably get even less love from me. But hopefully it will cease to be useful soon.

I learned to use git send-email and sent a small patch for adding an about:commands page to visurf. Visurf is a fun project of building a vi-like frontend to netsurf. It's still very bare bones, and netsurf of course cannot render every website you throw at it well, but the UI is very responsive and consistent. This cannot be said of the Firefox add-on I'm using currently, which is Firefox's fault (design decision). Its urlfilter concept is also interesting: you can specify a program of choice for mapping locations (stuff passed to the open command) to URLs. This allows for easy URL rewriting, setting search engines as fallbacks, et cetera. I hope to spend more time on visurf.

I also sent a 3-liner patch for making passmenu look for more dmenu alternatives on Wayland (it currently uses dmenu-wl). It made me learn more about POSIX sh for-loops—which is great—but I now doubt the patch itself is actually useful. (One might as well shadow dmenu-wl in the path.)

That's all the public code I wrote in the past month. I spent more time on e-mail trouble. My current host (Soverin) has had server issues in the past months. From SMTP failures to IMAP (and webmail) being unavailable for hours last night. I recall their Cal/CardDAV server often being offline when I used it, and then being dropped for an alternative without automatic migration or an e-mail about the imminent change. Their status page is also broken. I'm kind of surprised by all of this, since Soverin is advocated by Bits of Freedom. One good thing about Soverin, it must be said, is their kind and prompt handling of support queries, and their small price. It may very well be that these are growing pains.

But I'm going to try something else. I've started a trial at Migadu during last night's outage, and it works well so far. Migadu's documentation is a lot better, and I like the idea behind their pricing. The only downside is that it seems impossible to sign up for it without an e-mail address, but maybe I didn't look hard enough.

While writing this, I notice that my Markdown parser does not support footnotes. It's high time I give the innards of this blog some love. Metalsmith has been working well for me, but the downside of the plugin system is that one of them eventually becomes unsupported and starts dragging behind the whole system because of dependency conflicts. So maybe I should move to a more self-contained solution.

The story of snixembed

2022-01-10T00:00:00Z

It's February 2020 and my riot-desktop tray icon vanished. Electron (Chrome, rather) dropped support for the System Tray Protocol Specification: an old but widely used system tray protocol for the Linux desktop. Chrome moved to StatusNotifierItem (SNI), a D-Bus based protocol that — while still too complicated for my tastes — is simpler than the X based tray protocol, and ready for Wayland.

The problem: I was not ready for Wayland. I was running dwm with a tray bar patch that doesn't support SNI. Convincing Electron to reconsider seemed impossible, so I looked for another way.

The solution: implement the bare minimum of SNI and then "translate" it to the old protocol. Thus snixembed was born.

I do not understand Xorg, and I did not feel like learning legacy technology (for which there is surprisingly little tutorial-style documentation online). So I decided to use a toolkit to handle the translation: I would set up the proper D-Bus services, parse the data, and leave the rest to Qt.

It didn't work: QSystemTrayIcon does not allow for choosing the backend. As soon as I started impersonating an SNI host properly, Qt started talking SNI back to me instead of XEmbed to my old tray.

Then I tried GTK. It worked: GTK didn't (and probably still doesn't) support the new tray icon specifications, because they had stopped believing in system trays since GNOME 3. The old implementation was marked deprecated as well. That didn't bother me much: I had little free time and wanted my icons back, fast.

I decided to use Vala, a language I used previously for a never published project. Vala has a simple (too simple, it turned out) abstraction over D-Bus and is made specifically for using GTK. That meant writing less code. Less code is my first ingredient for finished projects.

Two days later, snixembed worked. The code was awful, slapped together in a few hours with little design considerations. But I had my icons back, so I was happy. I put it on sourcehut (warning for crappy code and incomplete functionality), and announced it on the Arch Linux forums.

I didn't expect anyone to use it, but someone did. I saw people recommending snixembed on GitHub. I got sourcehut tickets, and made a Matrix room that saw use. Small numbers, about ten people in total. Far more interaction than I had expected.

2025: I still get bug reports, and interesting use cases — like getting tray icons to work on WSLg.

I no longer use snixembed. Months after its creation, Electron decided to reintroduce its legacy tray code. Some time later it had hit production. I spread the word, and expected that would be the happy end of snixembed.

But once in a while, someone comes around with a bug or feature request. These people do not use snixembed in any way I would have imagined. One person uses (used?) it because they were running a KDE session but without its tray, and just the KDE session being there made applications ignore their legacy tray. Someone is using obscure apps that only use AppIndicator. (AI was Canonicals "competitor" to SNI that uses the same service names as SNI but then breaks from it in silly ways. I could write a whole blog post about the pains of this and other ways in which the ecosystem manages to just diverge from quite simple specifications and how I worked around it.) It's fun to see my project live longer than I have a need for it to.

These are the things I learned from snixembed:

Sometimes writing ugly code is the best way to finish a project.
Publish early. People will find your project, use your project. Some will report bugs, help fixing bugs. It's useful and motivating.
People will use your software in unexpected ways.
It's nice to fix bugs and it's important to do so only when it's convenient.
When implementing a protocol, do so faithfully — expect others do not.
Dirty hacks can make a difference.

Matrix and the flood of lookup queries

2021-07-14T00:00:00Z

Matrix and DNS

For a while now, I have been running a small Matrix homeserver for personal use. First in the cloud, now at home for privacy and cost efficiency. It works, but I've found that synapse can at times spit out hundreds of DNS queries in seconds. This is not unexpected, as federation means communicating with many different parties. But at home, this means connection issues for my other devices: very slow DNS queries or even connection failure. The problem is acknowledged, albeit sprinkled between other issues (e.g. here and here). Thankfully, a little relief is not hard to achieve: cache the query results. I decided to try out systemd-resolved.

Debian and systemd-resolved

Since the default network configuration for Debian using ifupdown tends to overwite /etc/resolv.conf and hence does not play well with systemd-resolved, I decided to switch the whole configuration to systemd and use systemd-networkd instead. Luckily, there is some documentation. Note that simply disabling networking.service does not seem enough to stop ifupdown from hijacking the interface, so I really had to (re)move the /etc/network/interfaces file as stated.

Once systemd-networkd was set up, all it took was enabling systemd-resolved.service and symlinking /etc/resolv.conf to the systemd-resolved-managed stub /run/systemd/resolve/stub-resolv.conf.

Results

After one hour of running time, the initial results are promising:

$ resolvectl statistics
[...]

Transactions
Current Transactions: 0
  Total Transactions: 21450

Cache
  Current Cache Size: 8
          Cache Hits: 5204
        Cache Misses: 16309

[...]

Looking at the cache size, systemd-resolved does not appear to cache aggressively. Maybe results could be improved by using a different cache system. However, this configuration seems to already alleviate the issues I was having on other devices, probably because it flattens the occasional big wave of requests coming from synapse. On a system that uses systemd, it is easy to set up.

From Jekyll to Metalsmith

2017-04-30T00:00:00Z

It has been roughly a year since I set up my static Jekyll blog on GitHub Pages. Back then, this free Jekyll hosting service was one of a kind. Nowadays, services like GitLab Pages allow free automated generation and hosting of static websites as well, and many limitations were removed.

The new site is generated with the amazingly simple Metalsmith, which is based on Node.js instead of Ruby. Which is great, because it allows for really easy integration of the Node ecosystem, and I find setting up a Node environment a lot easier than a Ruby one. (Bundler is nice, but I still encountered version conflicts, especially while using Middleman for a different website).

GitLab Pages makes getting online a breeze. A simple .gitlab-ci.yml file like this suffices:

image: node:alpine

pages:
  cache:
    paths:
    - node_modules

  script:
  - npm install
  - npm run build

  artifacts:
    paths:
    - public

  only:
  - master

Under the hood

Most of the hard work is done by Metalsmith plugins metalsmith-collections, metalsmith-markdown and metalsmith-jstransformer. Nunjucks is used as a templating language. I really liked Haml, but it's not really a first class citizen outside of the Ruby world, and Nunjucks is so much more KISS.

Domain name

After much thought, I decided steefhegeman.com to be the best domain name for this website. It annoys me how unoriginal it is, but sometimes boring is good.

With this, I hope to have a more stable website from now on. No more broken links. Promise.

Getting started with Libpeas extensions in Vala

2016-01-20T00:00:00Z

If you've been looking for easy ways to make your application extensible using "plugins", surely you must have come across a GObject extensions library called libpeas. Its engine can seamlessly load GObject-based extension objects which act as "entry points" to the application. Currently, plugins written in C/Vala (shared object files), Python and Lua are supported.

Note the date. This has not been checked in years and is kept for nostalgia only.

As a project I'm currently working on (more on that soon) requires a system like this, I decided to take a look. I must say, it took me a while to get it all up and running. Which is why I decided to write a simple introduction in the hope that the journey will be less painful for others. The end goal is to make a small a Gtk+ window with buttons provided by plugins. The core of the application will be written in Vala, and plugin examples are provided in Python and Vala. Let's get started.

What you need

Vala (obviously)
libpeas
Gtk+ (to spice the example up a bit)
Python (optional, for the Python plugin)
- Python
- python-gobject
- gobject-introspection

Do make sure you have the development versions installed too, if your distribution splits library packages.

Valadoc contains a great reference for all the libraries used in this post (libpeas-1.0 and gtk+-3.0).

The structure

For this little tutorial I've poked around a bit in the source code of gedit, the project where libpeas was first conceived. I had never seen an extensible application up close before, so seeing the structure was a nice aha-moment for me.

Most of gedit is actually a shared library. The library defines basically the whole application. Then there's also a little executable called gedit which doesn't do much more than creating some objects defined in libgedit to start the main loop. In fact, it's so small it's made of one C file: gedit.c.

Ten years later, there are several files. But Gedit still appears to have a familiar structure.

Why is this the case? For an application to be truly extendible, plugins need to be able to deal with its internal objects. Thinking about it like this, it's only logical that extendible applications are basically a library. Of course, not all the internal objects need to be accessible by plugins. To hide an object, simply don't ship the header file defining it or in Vala's case, mark the object as private.

To summarize: one big library compiled into a shared object file which a small launcher application and plugins utilize.

Part 1: the library

Just so you know: this will be most of the work.

As our application consists of a simple Gtk window, we will define the window here. Furthermore, we will define an interface for the extension objects. For good measure, let's give our little app an original name. Like foo.

namespace Foo {

	public class Window : Gtk.Window {

		public Gtk.ButtonBox buttons { get; set; }

		private Peas.ExtensionSet extensions { get; set; }

		public Window() {
			this.buttons = new Gtk.ButtonBox(Gtk.Orientation.VERTICAL);
			this.destroy.connect(Gtk.main_quit);

			/* Get the default engine */
			var engine = Peas.Engine.get_default();

			/* Enable the python3 loader */
			engine.enable_loader("python3");

			/* Add the current directory to the search path */
			string dir = Environment.get_current_dir();
			engine.add_search_path(dir, dir);

			/* Create the ExtensionSet */
			extensions = new Peas.ExtensionSet(engine, typeof (Foo.Extension), "window", this);
			extensions.extension_added.connect((info, extension) => {
				(extension as Foo.Extension).activate();
			});
			extensions.extension_removed.connect((info, extension) => {
				(extension as Foo.Extension).deactivate();
			});

			/* Load all the plugins */
			foreach (var plugin in engine.get_plugin_list())
				engine.try_load_plugin(plugin);

			this.add(buttons);
			this.show_all();
		}
	}

	public interface Extension : Object {

		/* This will be set to the window */
		public abstract Window window { get; construct set; }

		/* The "constructor" */
		public abstract void activate();

		/* The "destructor" */
		public abstract void deactivate();
	}
}

As you can see, in the constructor of Foo.Window, a Peas.Engine is used to search for plugins in the current directory and load the plugins. A Peas.ExtensionSet takes care of creating extension objects implementing the Foo.Extension interface as their plugins are loaded by the engine.

By connecting to the extension_added signal of extensions, we make sure that after an extension object is created, its activate member function is called. By connecting to the extension_removed signal, we make sure that the deactivate() member function is called. If you want, you could see a Foo.Extension's activate and deactivate functions as some sort of constructor and destructor. In activate they set their stuff up, add a button to the window, and in deactivate they remove the button again.

If you're familiar with GObject-style construction, you'll see that we tell extensions to create every extension object with its window property set to this (the current Foo.Window instance). This way, extensions will have a reference to the window from which they can start messing with the application.

Note that the Python loader has to be explicitly enabled.

Of course you can retrieve way more information about a plugin before (and after) loading it. The variable plugin is of the type Peas.PluginInfo, which, combined with Peas.Engine.provides_extension should give you all the info you could wish for.

Save the file as foo.vala and create the library:

# Generate shared object file, C headers, vapi file and gir file
valac -o libfoo.so --library foo -H foo.h  --gir Foo-1.0.gir  -X -shared -X -fPIC --pkg libpeas-1.0 --pkg gtk+-3.0 foo.vala

# Compile typelib file (Python and Lua)
g-ir-compiler --shared-library libfoo Foo-1.0.gir -o Foo-1.0.typelib

What we get:

A shared object file compiled from the library
A vapi file for Vala plugins and the launcher
A C header file for C and Vala plugins and the launcher
A GObject introspection file to compile...
...a typelib file for Lua and Python plugins

Part 2: the launcher

Next, we create a launch point for our application. The contents of the file should be pretty straightforward:

void main(string[] args) {
	Gtk.init(ref args);

	var window = new Foo.Window();

	Gtk.main();
}

That's all. Save it to a file called launcher.vala and compile it to the executable foo:

valac -o foo launcher.vala --vapidir . --pkg gtk+-3.0 --pkg foo -X -I. -X -L. -X -lfoo

The extra options are to make sure our library files can be found while they're not installed in a default search directory.

If you already tried to run the launcher, chances are you've run into this error message:

./foo: error while loading shared libraries: libfoo.so: cannot open shared object file: No such file or directory

Because the shared object file isn't installed properly but is located in the current directory, in order to run the launcher, the environment variable LD_LIBRARY_PATH needs to be set to the current directory. For the Python plugin, our typelib file also needs to be found in the current directory using GI_TYPELIB_PATH:

export LD_LIBRARY_PATH=.
export GI_TYPELIB_PATH=.

Now you should be able to run the launcher using ./foo. An empty window, great!

Part 3: plugins

Finally, let's write some plugins! Libpeas plugins consist of at least two files: the actual plugin (a shared object file or a script) and a plugin file containing some information about the plugin. Let's start off by writing a plugin in Vala.

Vala

class ValaExtension : Object, Foo.Extension {

	public Foo.Window window { get; construct set; }

	Gtk.Button button;

	void activate() {
		button = new Gtk.Button.with_label("Say Hello");

		/* Change label when clicked */
		button.clicked.connect(() => {
			button.set_label("Hello World!");
		});

		/* The magic, it's happening! */
		window.buttons.add(button);
		button.show();
	}

	void deactivate() {
		window.buttons.remove(button);
	}
}

/* Register extension types */
[ModuleInit]
public void peas_register_types(TypeModule module) {
	var objmodule = module as Peas.ObjectModule;

	objmodule.register_extension_type(typeof (Foo.Extension), typeof (ValaExtension));
}

A few remarks:

Notice how the extension object is derived from Foo.Extension. window points to the actual window object because the property is set on construction by the Peas.ExtensionSet (using Peas.Engine.create_extension).
libpeas uses GObject-style construction. Reading up on how it works would make you understand better how these construction properties work. If you want to define a constructor, use a construct {} block.
Shared-object-file-based plugins (C/Vala) require a peas_register_type function (don't forget the leading [ModuleInit] to register the extension types.

Save the file as vala-extension.vala and compile it to libvala-extension.so using:

valac -o libvala-extension.so --library vala-extension vala-extension.vala -X -shared -X -fPIC --vapidir . --pkg libpeas-1.0 --pkg gtk+-3.0 --pkg foo -X -I. -X -L. -X -lfoo

Time to write a plugin file. This is written in the KeyFile format. For all the options, see the reference. Note that all this information will be accessible through Peas.PluginInfo.

[Plugin]
Module=vala-extension.so
Name=Say Hello
Description=Displays "Hello World!" on click

Notice how in the Module value, the preceding "lib" is omitted.

Great! Save it to vala-extension.plugin and run the launcher. You should see a window with the button we just defined in it.

Python

Next, let's add a button to quit the application, this time in Python. I'm not going to show how Python and python-gobject work (wish I could! If I did it wrong, please let me know) here, so I'll keep it short.

from gi.repository import GObject
from gi.repository import Peas
from gi.repository import Gtk
from gi.repository import Foo

class PythonExtension(GObject.Object, Foo.Extension):
	window = GObject.Property(type=Foo.Window)
	button = GObject.Property(type=Gtk.Button)

	def do_activate(self):
		self.button = Gtk.Button(label="Quit")
		self.button.connect("clicked", Gtk.main_quit)

		self.window.get_buttons().add(self.button)
		self.button.show()

	def do_deactivate(self):
		self.window.get_buttons().remove(self.button)

Save it as python-extension.py.

The complementary plugin file (notice how ".py" is omitted):

[Plugin]
Module=python-extension
Loader=python3
Name=Quit button

Save it to a .plugin file like you're used to, and enjoy the quit button. Don't forget to set GI_TYPELIB_PATH to the current directory (export GI_TYPELIB_PATH=.).

Final words

Well, that's it! I hope this gave you a good impression of what libpeas can do for your application and how to achieve it. Of course, it can do way more. Plugins can bring extra datafiles and GSettings, for example, and libpeas-gtk provides widgets to manage plugins easily. If you want to know more about libpeas, a good starting point would be the official reference. Other sources I used to write this post are:

Thanks for reading! If you have any questions or other feedback, please let me know.