Right now, I'm building more of a knowledgebase/book kind of thing. And date is not the most important criteria to sort all articles. Though, it's still useful to display the most recent edited articles at some place.

Nevertheless, I wanted my collection to be the in the same order as they occur in my table of content file. Which happens to be the root src/index.md in my case.

Also, I didn't want to maintain the order by frontmatter or additional json data.

This is why I built something that parses the file and creates a sorted collection from collection.all, sorted by occurrence in my TOC file:

async function createSortedCollection(eleventyConfig) {
  const src = await readFile('src/index.md', 'utf8');
  const linkRegex = /\[.*?\]\((.*?)\)/g;
  const hrefs = ['./src/index.md'];
  let m;
  while ((m = linkRegex.exec(src)) !== null) {
    if (m[1]?.startsWith('https://') === false) {
      const file = './src/' + m[1];
      hrefs.push(file);
    }
  }
  eleventyConfig.addCollection("toc", function (collectionsApi) {

  return collectionsApi.getAll()
    .filter(a => hrefs.indexOf(a.inputPath) >= 0)
    .sort(function (a, b) {
      const aIndex = hrefs.indexOf(a.inputPath)
      const bIndex = hrefs.indexOf(b.inputPath)
    
    return aIndex - bIndex
  });
 });
}

How to use this?

You can add this to the Eleventy config via eleventyConfig.addPlugin(createSortedCollection).

Then, I can put "previous" and "next" links onto my pages.

I use this on a german study site where I prepare myself for a certification, the Certified Professional User Experience, Foundation Level. I had the need to transfer it to a simpler-language version and provide it in HTML. There's a PDF for learning, but I failed learning from it, due to complex sentences and me being demotivated quickly when dealing with PDFs.

The site is https://learosema.github.io/cpux-prep/, in german. The little prev next links at the bottom of the page are driven by the above TOC collection:

https://github.com/learosema/cpux-prep/blob/main/src/_layouts/default.njk#L35

Caveats

This is not a one-fits-all solution and probably needs some work to make it one. But that's fine for me, as of current. It doesn't need to be a one-fits-all-solution. YAGNI maybe.

Also, one tricky part is getting from the hrefs to something that identifies the items in the collection correctly. I used the inputPath and prepended my base directory to the href. Also, my URLs in the TOC are all relative. I use a custom permalink setting where I just do relative links to markdown files which are post-processed from .md to .html afterwards :).

In the default eleventy config, this needs to be adjusted. You could use the filePathStem property and prepend the base URL there.

It can only handle markdown and the path to the TOC file is hardcoded.

To make it more agnostic to the inut file format, you could process the input once and then process the output html file via a DOM parser library.

Have I mentioned that I find linkedom pretty great for server-side HTML processing tasks?

Resources

• Eleventy documentation, Collections API

For example, this looks like in the following code snippet:

---
title: Hello World
---
# {{ title }}

Lorem ipsum is a pretty cool dummy text dolor sit amet.

Sometimes, I want to provide the title by just adding an h1 to my markdown. It's less verbose:

# Hello World!

Lorem ipsum is a pretty cool dummy text dolor sit amet.

This has the downside that there is no title variable populated which I can reuse to fill my <title> tag in my layout file.

Using an eleventyComputed variable as title

So, I found a way to make that work via an eleventyComputed. Since version 3, eleventy provides the raw input in the eleventy supplied data.

The raw input is the unprocessed unparsed template body minus the template's frontmatter.

So, you can provide a computed title variable. When the input file format is markdown, it is parsed via a regular expression:

eleventyConfig.addGlobalData("eleventyComputed.title", () => {
  return (data) => {
    if (data.page.inputPath?.endsWith('.md')) {
      const titleRegex = /^\#\s(.*?)\r?\n/;
      const match = data.page.rawInput?.match(titleRegex);
      return match ? match[1] : '';
    }
    return '';
  }
})

Further considerations

This is specific to markdown though. Also, it isn't perfect. Further formatting inside the h1 isn't processed.

You could add that with a few further regular expressions, like I did with my non-complete mini-markdown implementation, or just use a complete markdown parser like markdown-it at that point. Somehow I refuse to do that because Eleventy already does that at the template processing point, as that could have a bigger performance impact.

Other formats and advanced use-cases

For other formats and/or more advanced use-cases, you could also combine it with an HTML parser, like linkedom. I'm in love with that library; it's great for server-side HTML processing.

import { parseHTML } from 'linkedom'

/* ... */
if (data.page.inputPath?.endsWith('.html')) {
  const { document } = parseHTML(data.page.rawInput);
  return document.querySelector('title').textContent;
}

In my use-case, handling the markdown headline with the above regex was sufficient.

Why?

This was a side-quest for my try to migrate a site from Jekyll to Eleventy which provided the title via a single hash sign (#). While Jekyll populated the title variable from it, Eleventy didn't do this.

Drawback

The drawback is performance. It is an additional parsing step in the build for each markdown file.

This is probably fine for my smaller website. But I guess this could quickly add up for the larger sites.

My long-term fix for this would be to update all my files to the frontmatter format. But my brain hates chore tasks.

A quick and dirty way to publish that to the web is to use Jekyll. Github supports Jekyll out of the box, via GitHub Pages.

So, if you have markdown in your repository, you can make Github transform it automatically to a website, with (almost) zero configuration.

You can provide your own design by HTML layout templates, by adding a _default/layout.html and additional assets like css, similar to Eleventy.

The experience for Jekyll is pretty user-friendly, even for non-developers. Markdown is automatically transformed to HTML with zero configuration.

Moving off jekyll to Eleventy brings a couple advantages: it's super fast and adds more flexibility, like adding additional post-processing, using CSS-preprocessors like lightningcss, and it could probably make you more independent from GitHub.

To be fair, you can host Jekyll anywhere else, but GitHub made it pretty configuration-free and straightforward.

Yes, to be fair, eleventy can do markdown configuration-free, too.

But one thing I needed to change was the URL handling, so it is more like in Jekyll. Eleventy uses extension-free URLs, which are pretty cool. They are the best when it comes to end-user usability (shorter, human-readable URLs). But that's not how Jekyll works.

In my markdown files, I often use several relative links to other markdown files. Navigating these links from the github-repo-integrated file viewer works as well as on the published jekyll site, where the links are rewritten as .html links.

I found this behaviour for my anchors pretty cool. I must admit this is more a "developer experience" feature.

Anyways, a struggle to move off Jekyll to Eleventy could be a missing eleventy.config.js which you can put into your repo and everything else works as before, without any changes.

So, this is what i did:

First, I changed the global permalink settings to use "resource mode", like documented in the eleventy documentation

Disclaimer: this is usually not recommended, the extension-free URLs are the user-friendlier ones.

So, maybe refactor later? 🙈

Then, I used linkedom to process my HTML output. It's a lightweight DOM implementation which let's me parse HTML and manipulate it with DOM APIs, just like in the browser's JavaScript environment.

So I can loop through all anchor tags, via document.querySelectorAll and handle all relative links with a .md ending and replace it with .html, like Jekyll does it.

The eleventy setup:

npm init -y
npm i @11ty/eleventy -D
npm i linkedom

The resulting eleventy.config.js:

import { parseHTML } from 'linkedom';

export default function (eleventyConfig) {

  eleventyConfig.addGlobalData('layout', () => 'default.html')
  // Set global permalinks to resource.html style
  eleventyConfig.addGlobalData("permalink", () => {
    return (data) =>
      `${data.page.filePathStem}.${data.page.outputFileExtension}`;
    });

    eleventyConfig.addTransform('remap-md-links', function (content) {
    if (((this.page.outputPath || "").endsWith(".html")) === false) {
      return content;
    }
    const { document } = parseHTML(content);
    const isRelativeLink = (href) => /^https?:\/\//.test(href) === false;
    const anchors = document.querySelectorAll('a[href]')
    for (const anchor of anchors) {
      const href = anchor.getAttribute('href') || ''
      if (isRelativeLink(href) && href.endsWith('.md')) {
        anchor.setAttribute('href', href.replace(/\.md$/, '.html'))
      }
    }
    return document.toString();
  })

  return {
    dir: {
      input: '.',
      includes: "_includes",
      layouts: "_layouts",
      output: 'dist',
    }
  }
}

Then build with npx eleventy or watch and serve with npx eleventy --serve.

Isn't that a horrible advice?

Yes, this will make the URLs of your published site less readable. At best, it's just an additional .html instead of a trailing slash. At worst, it gets very long and sprinkled with hexacdecimal code sequences.

But the usability point about relative markdown links in the git platform's file viewer is also valid.

In the end, it depends on your and your users' needs.

"But I want the nicer URLs?"

If you want the best of both worlds, human-readable urls with trailing slash in the published website, while keeping relative links to markdown documents, you can do that, too.

You can keep the default permalink behaviour if you adjust the anchor manipulation post-processing accordingly.

Keep in mind that special characters are slugified by default. This means, all non-alphabetic characters are replaced with hyphens. This avoids the URL to look cryptic.

There's an NPM package for that. It's called slugify (slugify). But it's small enough to incorporate it into your build yourself, in case you struggle to npm install it (because JavaScript dependency management is a mess).

A very minimal non-perfect slugify that works for plain english (ASCII characters only) is probably something like this:

function slugify(str) {
  return str?.replace(/[\W]+/g,'-')
}

The anchor manipulation code then becomes like this. This splits the URL parts at the slashes and slugifies the path parts and then joins them together again.

// the anchor manipulation code:
// Take the bigger code snippet from above and adjust the line with
// anchor.setAttribute accordingly.

anchor.setAttribute('href', 
  href.replace(/\.md$/, '/')
    .split('/')
    .map(str => slugify(str))
    .join('/'))

EDIT: Misleading Title

For transparency: I originally named this article "an eleventy config for moving from GitHub Pages" before.

This is a little misleading and baity, as Kristof Zerbe pointed out. Also, as he mentioned, you can perfectly deploy an Eleventy site to GitHub. So, this is more about Jekyll, not about moving away from GitHub.

I initially took this title because GitHub Pages integrated Jekyll so seamlessly.

People might resist changing to other platform where they have to write an additional YAML file. So, this seamlessness could be something that stops them for migrating away from GitHub.

As I mentioned, aborting is not too intuitive. When using fetch, you can provide a signal in the request options, which can then be used to abort operations.

This can not only be used inside the fetch API but inside everything asynchronous.

Wait, Vanilla JavaScript has signals?

Yes. But not the Angular kind. It's solely for aborting async operations and that's why it's called AbortSignal.

It works like this: you create a new AbortController.

The controller exposes an abort method and a signal property. The signal can be used to listen on abort events, via signal.addEventListener.

Code Example

let abortController = null;
let counter = 1;

async function loop(t = 0, signal) {
  const timeout = setTimeout((t) => loop(t, signal), 1000);

  $counter.innerHTML = counter;
  counter++;
  signal.addEventListener("abort", () => {
    clearTimeout(timeout);
    $counter.innerHTML = "aborted :)";
  });
}

abortButton.addEventListener("click", () => {
  if (! abortController) return;
  abortController.abort();
  abortController = null;
});

runButton.addEventListener("click", () => {
  
  if (abortController) return;
  abortController = new AbortController();
  counter = 1;
  
  // The abort signal is a property of 
  // the AbortController, which we pass to the 
  // async loop function. 
  // We could even "await" it here, but as we
  // don't do anything further afterwards, it can be a 
  // fire and forget.
  const abortSignal = abortController.signal;
  loop(0, abortSignal);
});

Nested asynchronous functions

When you have nested asynchronous functions, don't forget to pass the signal down.

function wait(ms, signal) {
  return new Promise((resolve, reject) => {
    const timerId = window.setTimeout(resolve, ms)
    signal?.addEventListener('abort', () => {
      window.clearTimeout(timerId)
      reject()
    })
  })
}

async function incrementTripleTimes(signal) {
  $counter2.innerHTML = counter2;
  await wait(1000, signal)
  $counter2.innerHTML = ++counter2;
  await wait(1000, signal)
  $counter2.innerHTML = ++counter2;
  await wait(1000, signal)
  $counter2.innerHTML = ++counter2;
}

async function loop2(t = 0, signal) {
  // uncomment below and see what happens
  // signal = null
  signal?.addEventListener("abort", () => {
    $counter2.innerHTML = "aborted :)";
  });

  await incrementTripleTimes(signal);
  await incrementTripleTimes(signal);
  await incrementTripleTimes(signal);
  
  console.log('restarting loop')
  window.setTimeout((t) => loop2(t, signal), 0);
}

runButton2.addEventListener("click", () => {
  if (abortController2) return;
  abortController2 = new AbortController();
  counter2 = 1;
  loop2(0, abortController2.signal);
})

abortButton2.addEventListener("click", () => {
  if (! abortController2) return;
  abortController2.abort();
  abortController2 = null;
});

Check the full demo on CodePen.

Sources

• DOM spec: aborting ongoing activities
• MDN: AbortController
• MDN: AbortSignal

It took me two weeks to debug a problem with my font-loading function, and it turned out I simply wasn't allocating enough memory. The culprit? My DPMI allocation function. I need to convert the memory size to paragraphs (1 paragraph = 16 bytes), but I accidentally divided by 16 twice. Facepalm.

To be fair, the two weeks is partly because I don't do DOS development full-time. That wouldn't pay my bills.

Want Some Retro Trivia?

Ever heard of DPMI? Wondering why I needed my own memory allocation function? Let's dig in.

What is DPMI?

DPMI stands for DOS Protected Mode Interface. It allows you to write 32-bit applications for DOS while still accessing BIOS functions. Pretty wild, huh? BIOS (Basic Input/Output System) is the low-level system that helps your machine boot up. On modern systems, BIOS has been mostly replaced by UEFI, but back in the day, it was the gatekeeper for hardware control.

Why Do We Need DPMI for Memory Allocation?

Here's the deal: all the BIOS stuff lives in the lower memory block, the first 640KB of RAM. My C program, which is a 32-bit application, is loaded into the upper memory block. But there's a catch: BIOS is still 16-bit. If I want it to read or write to memory, it can only access that lower chunk of RAM.

This is where DPMI steps in. Normal malloc() from C won't cut it here—I need to allocate memory in the lower block and create a descriptor. Think of it as a bridge that lets my 32-bit code talk to 16-bit BIOS routines.

// Data structure holding my DOS lower memory block
typedef struct dos_block_s {
    uint16_t segment;   // Real mode segment for ES
    uint16_t selector;  // Protected mode selector for direct access
} dos_block_t;

#if defined __DOS__ && defined __386__

dos_block_t dpmi_alloc_dos_block(uint32_t size)
{
    dos_block_t dblk = {0, 0};
    union REGS regs;

    regs.x.eax = 0x0100; // DPMI function: Allocate DOS memory block
    regs.x.ebx = (size + 15) >> 4; // convert to paragraphs (1 paragraph = 16 bytes)

    int386(0x31, &regs, &regs);

    if (regs.x.cflag)
        return dblk; // Failure, return {0, 0}

    dblk.segment = regs.w.ax;
    dblk.selector = regs.w.dx;
    return dblk;
}
#else
// Stub for platforms other than dos, 
// basically to make VSCode happy.
#define dpmi_alloc_dos_block(size)
#endif

Why Go Through All This Trouble?

For fonts! I wanted to use a custom font for my text-mode application. I designed a sans-serif 8x8 raster font, which really changes the look and feel of the classic DOS screen.

The cool part: text-mode graphics and raster fonts are still a huge deal in the indie gamedev scene. There's something incredibly satisfying about pushing chunky pixels directly and seeing the result instantly on the screen.

To feature a decent example, check out Monogram and DungeonMode by datagoblin.

Beautiful 8x8 raster fonts that makes you want to start building a roguelike RPG from scratch.

What's the big picture?

The big picture is to build a basic music application in textmode that runs everywhere, using the old OPL2 chip that was used in Ad Lib and soundblaster cards.

Why? Because my elder brother built a music application in the 90s in Pascal. It had MIDI support and everything!

He has always been a role model to me.

Why DOS? It's easier to start with DOS for me. It's a limiting choice. But this way, I won't feel overwhelmed by the drive to build it for Windows, Linux, Mac and the Web simultaneously. Maybe just to get a foot in the door about non-web UI development. Or, to keep it short: for fun.

The code for it is still in an early stage. I'm putting together puzzle pieces here:

• https://github.com/learosema/muzimake/
• The special font loading experiment I talked about: https://github.com/learosema/muzimake/blob/main/tests/test_fnt.cpp

Wrapping Up

This journey into DPMI and custom fonts has been a massive learning experience. It might not be the smoothest path, but debugging this low-level stuff really makes you appreciate the magic of modern OS memory handling.

Next on my list? Building a proper text-mode UI for my application. Let's see how deep this rabbit hole goes...

I still see accessibility as a crucial part for building digital products, but it's not my career path anymore to become an accessibility specialist.

I'm still very enthusiastic about accessibility, but I'm not happy about how things are in the industry at the moment.

What frustrates me about Accessibility?

IAAP certifications are broken and need to be fixed. One thing that is problematic is the certificate expiry. I get the point, people working in accessibility should know their stuff.

Still, the required certificate renewal lets it look like a money pit. Also, I dislike the gatekeeping. There shouldn't be any requirements to get the certificates IMHO.

Furthermore, these certificates shouldn't be necessary to work in accessibility, and some companies misconcept it like that; which can make it hard to get a foot in the door. You have a perfect vicious circle when certificates require work experience and the clients require certified people.

Another thing I was thinking about is that Accessibility audits are often pointless. Even easily fixable bugs are not addressed and rot in the backlog. Instead, a relauch in the future is promised, with a more accessible version of the product. But without further information on when this will be.

Additionally, you probably won't get to building software anymore as an accessibility specialist. Your main task is going to be to create accessibility audits. This feels like a step down, like being degraded from a Software developer down to a WCAG compliance tester.

In client work and enterprise contexts, accessibility is often about WCAG compliance, but not about really making the product as accessible as possible.

A further point I really dislike the Fear marketing regarding the European Accessibility Act. This is a strategy some accessibility consultants run and it quite tells that it's about compliance rather than real accessibility improvement efforts.

Quo vadis Lea?

As I said in the opener, I'm still very enthusiastic about accessibility, but I'm not happy about how things currently are in the industry.

My focus is still on building user interfaces with accessibility in mind. But I want to build the things. I'm a lousy tester, I guess.

Also, I would like to get a more T-shaped skillset. I love to explore the Software Architecture field, while still keeping my strong focus on UI development, usability and accessibility.

Following that path, I hope I can have more impact and bring in my accessibility knowledge, from the position of a developer or maybe of a Software architect in the future.

But it turns me off when such a space is exclusively open to "experts only". There are events that accept speaker proposals only when they are "experts".

Some events even limit the attendees to "expert-only" as well.

In either way, only one or a few people are in power to decide who is "expert enough" in order to be part of it. And I have very mixed feelings about it.

"Maintain Quality"

One reasoning behind creating "experts-only" spaces is to maintain quality. This way, organizers can (or think they can) ensure a topic is covered in a high quality. Also, (they think) discussions can go in depth, and beginner questions in complex topics aren't covered over and over.

It's perfectly fine and valid to communicate a target audience upfront for certain advanced-level sessions. But I wouldn't systematically exclude people from a meetup based on the perceived level of expertise.

The problem

Perceived level of expertise. This perfectly describes the core problem: deciding who qualifies as an "expert" is rarely an objective process.

Often, it depends on criteria that favor individuals who have had greater access to education, mentorship, and professional opportunities.

For example, women are often seen as less competent than their male counterparts, even when they have the same qualifications. In "expert-only" spaces, this bias might result in women being overlooked or undervalued.

The vicious cycle of "Experts only"

For marginalized groups, gaining expertise often involves breaking through barriers like limited networking opportunities, implicit bias, or outright discrimination.

If advanced meetups exclude these individuals based on their perceived lack of experience, it creates a vicious cycle:

• They can’t enter "expert-only" spaces
• Without access to these spaces, they can't advance
• They miss network opportunities
• They’re perpetually excluded from opportunities that could help them advance.

This structural problem disproportionately affects those who already face hurdles in accessing resources and recognition.

Reinforcing Toxic Cultures

The exclusion often overlaps with other problematic practices, such as creating unwelcoming environments for women, LGBTQ+ folks, or people of color.

"Bro-culture" events (like beer-driven meetups) can amplify this issue.

What are meetups for?

Meetups are for networking and gaining new perspectives on certain topics.

The time for a meetup is already very limited (I learned that from facilitating HHTML, where having 4 talks on a single evening turns out as a bit too much).

Mostly, when you want to cover a topic more in depth, the best way to do so is to link to more detailed resources. For example, refer to an in-depth article or book on the slides.

If you run an "experts-only" space, you – and everyone else involved – are going to miss out the opportunity to advance.

Creating a space for all levels allows cross-level communication, where everyone, beginners as well as more advanced foks, can gain new perspectives.

The tech industry already struggles with inclusivity. Let's not reinforce this structural discrimination further.

In a hobby project, I tried a slightly less hot thing. Less hot, but pretty stable to use and available in TypeScript from the beginnings: have it the other way round.

Write JavaScript code without all the type juggling, sprinkle it with a couple JSDoc comments. JSDoc can be used to describe your declarations. This will help autocomplete feature (aka IntelliSense for Microsoft-style IDEs).

You can annotate JSDoc with TypeScript types. These are also used to display type information in the autocompletion feature. You can additionally check the JavaScript code base by the typescript compiler.

How does JSDoc-annotated code look like?

/**
 * Poor girl's handlebars
 *
 * @param {string} content the template content
 * @param {Record<string, string>} [data] the data object
 * @param {TemplateConfig} [config] the template configuration, 
 * where you can specify additional filters available inside the template
 * @returns {Promise<string>} the template result string
 */
export async function template(content, data, config) {}

You can place a little comment block above your function (or whatever else you want to document). In curly braces, you can additionally provide the types used in parameters or returns. Whenever you have an asynchronous function, remember to return a Promise<returnType> of your return type. Parameters can be specified as optional via square brackets. Your code editor may auto-insert such a block whenever you write /** and hit enter above a declaration.

Every built-in type you know from TypeScript is available. This includes primitives such as string, number boolean but also more complex object types. Object types can be defined using the @typedef directive. The definition of the TemplateConfig object looks like this:

/**
 * @typedef TemplateConfig
 * Configuration object for the template() function.
 * @property {Map<string, Function>} [filters] map of additional filters to be used
 */

Interfaces?

A thing loved by software architects and design pattern evangelists in programming languages are interfaces, wich are often used in Software Design concepts such as Dependency Injection.

But JavaScript lacks interfaces. And JavaScript is often criticized due to that.

That can also be represented as a @typedef in JSDoc.

As an example, look at the following TypeScript:

interface FileResolver {
    async loadFile(fileName: string): Promise<string|Buffer>
}

It can be represented via JSDoc:

/**
 * @typeDef FileResolver
 * @property {(fileName: string) => Promise<string|Buffer>} loadFile
 */

Using types from other files

Using types from other files is a bit tedious though. How would you reference a type from another file?

Microsoft IntelliSense in Visual Studio and Visual Studio Code have a special syntax for it. So called triple-slash-references:

///<reference path="typedefs.js"/>

But jsdoc requires another syntax, which looks like this

/**
 * My setup function 
 * @param {import("./typedefs.js").Configuration} [config] 
 */
function setup(config) {
}

This works for me, but it's a bit verbose. You can use a combination of both: The triple-slash reference and the inline type imports. Unfortunately, I haven't found a simpler way yet.

Setting up TypeScript

Let's have a look how you can use TypeScript in your project without writing TypeScript but JavaScript with JSDoc.

First, install typescript as a devDependency.

npm install typescript -D

In the tsconfig, you can specify allowJs: true and checkJs: true. This allows you to use JavaScript in TypeScript and let it check by the typescript Compiler.

Regarding my rules, I've set strict to true, but noImplicitAny set to false. With some effort, I could get it to work with noImplicitAny set to true, but this would have required me to add more typings with inline comments. In general, that would also be a good starter ruleset to migrate a JavaScript codebase to TypeScript.

Having tsc to check the JavaScript still helped me find certain problems where stuff could possibly be undefined.

For my js-only codebase, I went with this tsconfig.json, extending from a node22-preset. At the time of this writing, node 22 was the LTS version.

npm install @tsconfig/node22 -D

{
  "extends": "@tsconfig/node22/tsconfig.json",
  "compilerOptions": {
    "rootDir": "./src",
    "allowJs": true,
    "checkJs": true,
    "declaration": true,
    "declarationMap": true,
    "emitDeclarationOnly": true,
    "outDir": "./dist",
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "noImplicitAny": false,
    "skipLibCheck": true
  },
  "include": ["src"]
}

When I run npx tsc now, it would generate type declarations for all files in src and save them to dist.

Auto-generate documentation

Additionally, I even could run typedoc which generates a nice website with the API for me. I found this super helpful, so I built a Github action that builds and deploys it:

npm install typedoc -D

# .github/workflows/documentation.yaml:
name: Deploy API Documentation to GitHub Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment,
# skipping runs queued between the run in-progress and latest queued.
# However, do not cancel in-progress runs.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: $
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Build API documentation
        run: |
          npm ci
          npm run docs
          touch docs/.nojekyll
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'docs'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Further Resources

• official JSDoc website
• typedoc
• LinkedIn article about --experimental-strip-types, by Stefan Judis, which inspired me writing this article

So, I was wondering, why do I have to run Windows for development tasks in the project? I might get the point. Maybe the team doesn't want to care too much about cross-platform compatibility. But most of the tools were cross-platform anyway. So I was asking myself again, why?

The machine I work with is a Mac with a Silicon Chip. Usually, this will do fine for most for web development tasks.

I learned more about why the project requires Windows for development. Most of the tools used (eg. Visual Studio Code, Azure Data Studio, Docker, Node, etc) were in fact perfectly available for Mac. But the database server running in a Docker image doesn't support the Apple Silicon chip.

So, an option proposed to me was to hand me a second machine that runs Windows. Another option would be to use a VM. I wanted to avoid both options if possible. Working inside a VM is pretty cumbersome, and having to carry two laptops around every day in the Office would be quite exhausting. it would require me to always switch between the two computers all the time (operative tasks on Windows, administrative tasks on the Mac).

The database server inside Docker was the first hurdle. But all I had to do was to install the x86 CPU emulation layer on my mac, via:

softwareupdate --install-rosetta

Far from optimal, but this made it run on my Silicon Mac. I'm not sure (and not a backend dev), but the backend was using an Object-relational Mapper (ORM). It might have been possible to configure the project with a something more cross-platform-compatible database engine like PostgreSQL. But we went with the emulation and it worked just fine.

The second thing was a question of comfort. The whole project had a lot of good old DOS-style Batch files for running repetitive tasks during development. For example, there was a RUN.BAT for running frontends, backends, etc.

Simplified and anonymized, it looked something like this:

@echo off

if "%1" === "frontend" goto frontend
if "%1" === "backend" goto backend
if "%1" === "migrate" goto migrations

echo Usage: RUN [frontend|backend|migrations]
goto :end

:frontend
cd frontend
npm start
goto :end

:backend
dotnet run backend\backend.vspjoj 
goto :end

:migrations
CALL db migrate %2
goto :end

:end

Most of the commands inside that batch file also run just fine on the Mac. So the quick solution was to always do a cat RUN.BAT and copy the code from the appropriate jump marks.

I did this to get the thing running on day 1. On day 2, I got tired of this.

First thought was to introduce a top-level package.json and use the scripts section for running tasks:

npm init -y

As a result, you get a json file. Then, you can edit the scripts section accordingly, so you can invoke the tasks via npm run frontend and so on:

{
  "name": "foldername",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "frontend": "cd frontend && npm start",
    "backend": "cd backend && command_to_run_backend"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": ""
}

That was declined. Second thought was to install WINE which is a Windows environment wrapper for UNIX-style OSses, including Mac. Actually, it does come with winecmd which enables me to run batch files on my Mac. But I didn't manage to make it work with tools like node installed on my machine.

My solution in the end was to port the Batch files to UNIX-style shell scripts. I'm not a Shell Guru. But that turned out to be straightforward:

#!/bin/sh

frontend() {
    echo running frontend
    # frontend tasks here
}

backend() {
    echo running backend
    # backend tasks here
}

if [ "$1" == "frontend" ]; then frontend; fi
if [ "$1" == "backend" ]; then backend; fi

Whatever you use, I would recommend avoiding Batch files in web development codebases. The same for proprietary database engines with limited CPU support. This would make the project unnecessarily dependant on propietary platforms like Windows.

Yeah, to be fair, unix-style shell scripts aren't available in Windows by default, but you can install MSYS (aka Minimalist GNU for Windows) when you are on Windows. Often, you don't even have to install it separately, as git, the version system which is most commonly used nowadays comes with a rudimentary bash shell which you can use.

I wanted to share this. Maybe it helps you in case you encounter a project like this.

But I didn't really cover how it works under the hood, which also isn't covered in the official React documentation. So this article tries to catch that up.

What's JSX at all?

It's an extension of the JavaScript specification (ECMA-262). Efforts to get this integrated into the official specification weren't successful so far, apparently.

Transpiling JSX to JavaScript

As JSX is not part of JavaScript, it requires an additional transpile step in order to support it. This is done via a so-called transpiler. Here, you have a couple of options:

• TypeScript
• ebuild
• vite (out of the box)

JSX is an extension which adds support for writing XML-like snippets directly into JavaScript. When it was introduced by Facebook and React, there were mixed feelings coming from the JavaScript community.

On the one side, mixing markup into your JavaScript inline was considered a very bad practice, violating separation of concerns. But on the other side, it apparently seemed to make sense in component-style JavaScript frontend frameworks. I remember an old article dated year 2015 on that by Eric Elliot back then, which quite shows the mixed feelings of it when it was introduced: JSX looks like an abomination

JSX gained a lot of popularity and so other frameworks adopted it.

JSX changed over time

One thing that left me confused when I had a first look at React 17.

The team decided to introduce a breaking change to the JSX factory so now there is a React-17 way and a React-pre-17 way to transpile JSX. TypeScript provides different transpile options, react for the pre-17 transpile and react-jsx for the transpile for versions 17 and up. That also is confusing and I always have to look up which is which.

Pre-17-JSX

In React until version 16, JSX code used a createElement factory. Imagine the following code:

function GreeterComponent({name}) {
  return (
    <div>
      <h1>Hello {name}</h1>
      <p>Have a nice day!</p>
    </div>
  );
}

In React until version 16, it gets transpiled to

function GreeterComponent({name}) {
  return React.createElement('div', null, 
    React.createElement('h1', null, `Hello ${name}`),
    React.createElement('p', null, 'Have a nice day!')
  );
}

In order to work with frameworks other than React, you can configure to use a JSX factory other than React.createElement. Commonly, h is used as a name:

/* Transpilers like Babel support setting the JSX factory via an inline comment: */
/* @jsx h */

function GreeterComponent({name}) {
  return h('div', null, 
    h('h1', null, `Hello ${name}`),
    h('p', null, 'Have a nice day!')
  );
}

React 17 and up

As mentioned, React 17 had a breaking change regarding JSX.

The same GreeterComponent now relies on an external _jsx helper. In theory, this can help decoupling JSX components from React so you don't need to import React anymore as a peer dependency anymore when building a component library (I'd appreciate that if that's the overall Roadmap but I'm not a React core team member).

The same GreeterComponent transpiled looks like this:

function GreeterComponent({name}) {
  return _jsx('div', {children: [
    _jsx('h1', {children: [`Hello ${name}`]}),
    _jsx('p', {children: ['Have a nice day!']})
  ]})
}

One advantage of the breaking change is that it is more decoupled from React, as it doesn't rely on React.createElement by default anymore. Maybe it is as a try by the team to get this adopted into the ECMA-262 specification. One disadvantage is the breaking change, I'm not sure whether that would have been necessary or what the advantages are.

Maybe it's to make the syntax with the children property more similar to React's API.

The disadvantages of the breaking changes dominate my opinion about it. Codepen for example still has the React 16 transpilers in place. Also, there are libraries which didn't consider the breaking change and now you need glue code to make it work. So my feelings about it are quite mixed.

Creating a data structure from JSX

In my last article, I used a very plain JSX factory which converts the JSX code into a basic JavaScript tree structure:

function h(tagName, attributes, ...children) {
  return { tagName, attributes, children };
}

Alternatively, you could output JSDON. This could directly work with linkedom, a DOM API which could be used server-side. It is very performance-optimized and uses a linked-list data structure rather than a tree.

I like the idea of just having some JS objects describing components. However, one thought that did come to my mind was: it's over-engineered. I'm using a transpiler to convert an XML-like syntax into JavaScript just to output HTML. I could just use <template> instead.

Further Resources

Paul Everitt has built an Eleventy plugin for JSX which looks pretty cool. I need to look into it.

Also, the official React documentation is worth a look.

Still, there are certain use-cases where I need to generate markup on the client-side from time to time, usually everytime where I need JavaScript anyway for a certain functionality.

Code Example

An example where I recently used JSX was for modal dialogs in my Boulder Dash clone.

In that project, I used JSX together with web components. This way, web components start looking very similar to React class-level components, see my game menu component.

A shortened version of this component is below:

import { h, fragment, renderTree } from '../utils/jsx-factory';

export class GameMenu extends HTMLElement {

  static register() {
    customElements.define('game-menu', GameMenu);
  }

  gameMenu: HTMLDialogElement|null = null;
  menuButton: HTMLButtonElement|null = null;

  render() {
    const currentURL = document.location.href;
    renderTree(this,
      <>
        <button class="burger" aria-controls="gameMenu" aria-label="open menu"> 
          <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
            <rect x="1" y="1" width="14" height="3" />
            <rect x="1" y="6" width="14" height="3" />
            <rect x="1" y="11" width="14" height="3" />
          </svg>
        </button>
        <dialog class="game-menu flow" id="gameMenu">
          <h2>Menu</h2>
          <form method="dialog">
            <button id="buttonReturnToGame" class="button">Return to game</button>
          </form>
          <a href={currentURL} class="button">Restart game</a>
          <a href="/" class="button">Back to main menu</a>
        </dialog>  
      </>
    );
  }

  connectedCallback() {
    this.render();
    this.menuButton = this.querySelector<HTMLButtonElement>('.burger')!;
    this.gameMenu = this.querySelector<HTMLDialogElement>('.game-menu')!;
    this.menuButton.addEventListener('click', this.onClickButton);
  }

  disconnectedCallback() {
    this.menuButton?.removeEventListener('click', this.onClickButton);
    this.innerHTML = '';
  }

  onClickButton = () => this.gameMenu?.showModal();
}

The methods connectedCallback and disconnectedCallback are quite similar to the React lifecycle methods componentDidMount and componentWillUnmount.

One major difference to React is the fact I'm using class attributes rather than className. React chose to do so as class and for are reserved JavaScript keywords. Apparently, it works fine with class attributes so I prefer to stick to HTML as close as possible.

You could add certain transformations in your own JSX implementation to make both class and className work, but I decided to not do that.

I also kept the event handling separate and just went with using addEventListener. With some additional effort, we could also add support for adding event handlers in a declarative way, like React does.

Setting up JSX for TypeScript

You can enable JSX for TypeScript by editing the tsconfig.json by setting a couple of options.

{
  "jsx": "react",
  "jsxFactory": "h",
  "jsxFragmentFactory": "fragment",
}

There are multiple different types of JSX implementations. I'm using the legacy JSX factory implementation for now which was used in React up to version 16.

React version 17 introduced a new kind of JSX factory which I don't use yet. I will cover the differences of the old and new JSX in a follow-up article.

Providing an implementation for the JSX factory

In order to make the JSX factory work, we need to provide implementations for the h() function and also for fragment.

Im my case, h() returns an object using a recursive DOMTree interface. It describes the structure of the generated JSX element.

export interface DOMTree {
  tagName: string;
  attribs: Record<string, string>,
  children: DOMTree[]
}

This way, the implementation for h() and fragment is pretty straightforward:

const svgNS = 'http://www.w3.org/2000/svg';

export const fragment = 'fragment';

export function h(
  tagName: string, 
  attribs: Record<string, string>, 
  ...children: DOMTree[]): DOMTree {
  return {
    tagName, attribs, children
  };
}

In a former version of my h() implementation, I created actual dom nodes directly via document.createElement instead of returning a data structure.

But in order to make inline SVG code work, it is important to switch to the XML namespace pointing to http://www.w3.org/2000/svg as soon as there is an <svg> tag, so my nodes need to know about their parent elements.

As a basic solution, I created a recursive renderTree function that takes care of that, using the element.namespaceURI property to retrieve the current XML namespace.

Additionally, support of fragments (using <></> in JSX) are made possible via the DocumentFragment-API.

const svgNS = 'http://www.w3.org/2000/svg';

/**
 * Render a DOM structure
 * 
 * @param node the container element where the DOM tree is appended to.
 * @param tree the DOM structure to be created
 */
export function renderTree(node: Element, tree: DOMTree) {
  const namespace = tree.tagName === 'svg' ? svgNS : node.namespaceURI;
  let el: Element|DocumentFragment;
  if (tree.tagName === fragment) {
    el = new DocumentFragment();
  } else {
    el = document.createElementNS(namespace, tree.tagName);
    for (const [attrib, value] of Object.entries(tree.attribs || {})) {
      el.setAttribute(attrib, value);
    }
  }
  for (const child of tree.children) {
    if (typeof child === "string") {
      el.appendChild(document.createTextNode(child));
      continue;
    }
    renderTree(el instanceof DocumentFragment ? node : el, child);
  }

  node.appendChild(el);
}

Providing JSX type definitions

Finally, you need to declare a JSX namespace in a type declaration file, suffixed .d.ts.

Be careful with the naming of the files. When the factory is in jsx.ts, don't name the type definition file jsx.d.ts as there may be conflicts.

declare interface DOMTree {
  tagName: string;
  attribs: Record<string, string>;
  children: DOMTree[];
}

declare namespace JSX {
  interface Element extends DOMTree {}
  interface Attributes {
    [attrib: string]: string;
  }

  interface IntrinsicElements {
    [elem: string]: Attributes;
  }
}

Final thought

A final thought I had when I was about to finish up this article was: can we also use it server-side?

You can make use of your web component code node.js by using ts-node. This way, you can use it in an express application or in a static site generator such as Eleventy. A nice buzzword for that would be "isomorphic typescript" 🥳.

When it comes to node applications, you often still work a lot with the require() notation for importing dependencies, aka the CommonJS module system (including Eleventy stable as of current). Importing a `.tsx`` file inside node is a bit trickier:

require('ts-node').register({lazy: true, esm: false, moduleTypes: {
  'src/**/*.{ts,tsx}': 'cjs'
}});

// Then, you can use require with your typescript files:
const { h, fragment } = require('./src/utils/jsx.ts');
const { MyComponent } = require('./src/components/my-component.tsx');

For rendering the component server-side, you will need a DOM implementation. JSDOM or LinkeDOM will do. I feel I should also write an in-depth article about this.

But what about testing?

Testing might still be one of the reasons why people choose a framework like React rather than working with the native web components.

But it turns out testing web components is not too complex. All you need is a test runner of your choice and a DOM API. There you have several options:

• run the tests in a real browser, or a headless one
• use a console-based test runner with a (fake) DOM library

Using the node.js test runner

As I learned via the talk by Sebastian Schürmann, node.js comes with its own integrated test runner. By default, node --test runs all files in the project which are suffixed with .test.js, .test.cjs and .test.mjs.

For this article, I've created a test project with a password-input web component as a demo: wctest.

The test is using the describe and it-syntax which can be imported from "node:test".

In order to be able to run DOM APIs inside my test, I have to emulate it for my test environment. I'm using linkedom which is a fast implementation based on JSDON and linked lists.

It works like this:

import { parseHTML } from 'linkedom';

const {
  window, document, customElements,
  HTMLElement, Event, CustomEvent
} = parseHTML(`
  <!doctype html>
  <html lang="en">
    <body>
    </body>
  </html>
`);

It even comes with the customElements API so this works nearly out of the box. The only tricky thing might be the fact I won't get global namespace pollution, which is normally a good thing, but my modules to be tested need them in the global namespace.

So, the workaround I'm using is to put the APIs consumed into the global namespace and then do a dynamic import of my module in the test setup:

describe('password-input component', ()=> {
  let window, document, customElements, HTMLElement, DocumentFragment, PasswordInput, Event;

  before(async () => {
    window = global.window = parseHTML(`<!DOCTYPE html><html><head></head><body></body></html>`);
    DocumentFragment = global.DocumentFragment = window.DocumentFragment;
    document = global.document = window.document;
    customElements = global.customElements = window.customElements;
    Event = global.Event = window.Event;
    HTMLElement = global.HTMLElement = window.HTMLElement;

    const module = await import('./password-input.js');
    
    PasswordInput = module.PasswordInput;
    PasswordInput.register();
  });
});

Alternative: jest

A more common choice to test web components is to use jest. I haven't prepared a special demo for this article, but I did this in the past with my shader-art web component, which is for a lightweight embedding of shader animations into websites while respecting "reduced motion" settings of your operating system.

You can configure jest to use JSDOM which allows you to use DOM-APIs. One essential configuration option you have to specify in your jest.config.js is testEnvironment: 'jsdom'.

Additionally, you can also specify how jest would handle further things, which could also impact your test execution time. For testing canvas2d graphics, you can npm install canvas and jsdom will use that to emulate the canvas API. That would even allow you to do some visual regression testing.

When emulating the canvas API in your test, you may also want to work with images. So, another setting that comes into play is resources: 'usable', which is configured in the testEnvironmentOptions inside the jest.config.js.

module.exports = {
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    resources: 'usable',
  },
}

For my shader-art component, I chose to use a webgl mock for jest which you can install via NPM and specify it via setupFiles: ['jest-webgl-canvas-mock'] inside the jest.config.js.

Further approaches?

For now, I decided for me that those above two approaches are enough for me for now. I'm would be excited to explore other approaches which may involve using a headless browser and/or cypress. If you have a demo project or want to talk about it with me, feel free to reach out. 💖

A common misconception is that people often think of WebGL as a 3D engine, but it is in fact a rasterization engine for drawing points, lines and triangles.

This can be used as building bricks for creating a 3D engine. Actually there are a number of 3D engines implemented on top of WebGL, like three.js or babylon.js.

WebGL and OpenGL

WebGL is based on OpenGL ES, providing a thin JavaScript layer over the OpenGL ES API. It comes in different versions, basically WebGL 1 (based on OpenGL ES 2.0) and WebGL 2 (based on OpenGL ES 3.0).

On Safari 14 and older or Internet Explorer, only WebGL 1 is available. WebGL 2 removes some limitations of WebGL 1.

The tech people said to me "you don't need to support WebGL 1 anymore" but Lea is more into making things as inclusive as possible and so I think I should stick to WebGL 1 as I don't really touch the features of WebGL 2 in this article anyway. Also, there is a great in-depth site on WebGL 2. Besides that, there also is a great site on WebGL 1 which goes more in-depth than this article.

It runs on the GPU

WebGL is a low-level graphics library, which provides an API for running programs on the GPU.

• Programs consist of a pair of functions, called shaders.
• Shaders are written in a C-like language, called GLSL (GL Shader language).
• There is a Vertex Shader and a Fragment Shader.
• Most of the WebGL API is about setting up the state for the shaders and passing data from JavaScript to WebGL

Vertex Shaders

The job of the Vertex shader is to receive data from a buffer and to calculate vertex positions based on that data. Based on the positions it returns, WebGL can then rasterize certain primitives, like points, lines or triangles.

You can imagine the vertex shader as a function that takes a data record and returns a position. A common use-case of the vertex shader is to take a 3D coordinate and apply a perspective projection, for example.

Fragment shaders

When rasterizing these shapes (filling triangles with pixels), the fragment shader is run. This is done in a highly parallelized manner. For each fragment(=pixel) of the shape, the fragment shader is run in parallel.

The fragment shader is like a function that takes a number of arguments like the fragment position (where inside the shape am I?) and returns a color based on that.

It works a lot like tixy.land, where you have a function that is executed for each dot in a dot matrix, taking parameters like the x,y coordinate, the time value and the pixel index and return a value representing the dot size and color in a dot matrix.

Drawing a triangle

One of the most straightforward WebGL programs is drawing a triangle using a constant color.

We'll provide buffer data for 3 points, and the vertex shader will be doing nothing else but directly returning the data without any further calculation. For each record in the data, the vertex shader is run to calculate a vertex position, spanning up a triangle.

There are several draw modes available in WebGL: shall we draw points, lines, triangles or a strip of triangles? We'll focus on triangles in ths article.

Code for the Vertex Shader

precision highp float;
attribute vec4 position;

void main() {
  gl_Position = position;
}

The vertex shader takes a record from buffers through an attribute. In this case, we are only using a position attribute, which is directly passed to the global gl_Position.

The coordinates passed to gl_Position are like in a carthesian coordinate system with (0, 0) in the center, (-1, -1) on the bottom left corner and (1, 1) on the top right corner.

Code for the Fragment Shader

precision highp float;

void main() {
  // return red. 100% red, 0% green, 0% blue, 100% alpha
  gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0); 
}

The fragment shader sets the global gl_FragColor to a constant vec4 value. The components of the vec4 vector represent red, green, blue and alpha values.

Another global variable available is gl_FragCoord, a vec2 value pointing to the current coordinate of the pixel being processed.

GL Shader Language

As you may have noticed, glsl looks like a C-like programming language. It is. Most primitive types as in C are available (most importantly int, float, double). In addition to that, we have additional types for vectors (vec2, vec3, vec4, or their integer companions ivec2, ivec3, ivec4) and matrices (mat2, mat3, mat4, ...). One nice perk of GLSL is: things like matrix multiplication is built-in, just use the * operator.

On my website, I have a little GLSL overview which should help you getting started: https://lea.codes/webgl/glsl-overview/

In WebGL 1, you may face the limitation that the break condition of for-loops only work when a constant condition is used, as in for (int i = 0; i < 10; i++) {}. Using another dynamic variable for the break condition (as in i < j) is not allowed. This limitation is removed in WebGL 2.

The full working demo

Here's the full code. I'm using a shader-art web component to abstract away WebGL a bit so we can focus on the shaders.

Passing data from the vertex shader to the fragment shader

In the next demo, we'll draw two triangles filling the whole viewport of the canvas. Alongside with the position buffer, we'll also provide a UV buffer, which is often used for texture coordinates. So, the top left corner is at (0, 0) and the bottom right is at (1, 1).

The UV coordinates are received in the vertex shader as a 2D, vector: attribute vec2 uv. These can be passed over to the fragment shader through a varying variable. A common convention is to prefix varying variables with v, like vUV.

Additionally, these values are not only just passed over from the vertex to the fragment shader, but also interpolated between the edges of the triangle shapes.

This way, we can create a gradient. In the example, the fragment shader calculates a color based on the interpolated UV coordinates, using red as a constant 100% value, green as the uv.x value, blue as the uv.y value.

In this case, it would also be possible to calculate the uv coordinates from the position, but that's only trivial when dealing with a rectangle. With having additional UV coordinates, we could shift the positions in the vertex shader a bit (in a way there are no right angles anymore, imagine a perspective projection) and the uv vector still provides us with correct values.

Passing data from JavaScript to shaders

You can use uniform variables to pass data from JavaScript to your shaders. The <shader-art> web component passes a uniform vec2 resolution uniform and a uniform float time to your shaders which you can use both in the vertex shader as well as in the fragment shader. The resolution uniform holds a 2d vector containing the absolute pixel resolution of the canvas and is useful for aspect ratio correction, eg. whenever you want to draw perfect squares and circles within your shaders. The time uniform holds the amount of microseconds passed and can be used for simple animations.

With the time value, you can start to get create animations similar to in tixy.land.

The demo below shows an animation, feeding a noise function with xy-coordinates and a time value, with the noise function is being combination of sine and cosine functions. This already creates a beautiful effect.

Migrating to WebGL2

From the shader-side, it's basically this:

• Prefix your shaders with #version 300 es
• attribute variables in the vertex shader are declared as in, eg. in vec4 position;
• varying variables in the vertex shader are declared as out instead, eg. out vec2 vUv;
• varying variables in the fragment shader are declared as in instead, eg. in vec2 vUv;
• there's no gl_FragColor anymore in the fragment shader, declare an out vec4 fragColor; and use that (name it as you like)

From the JavaScript-side, you will call canvas.getContext('webgl2') instead of canvas.getContext('webgl') and you will receive a WebGL2RenderingContext which is mainly backwards-compatible with WebGLRenderingContext. The <shader-art> component takes care of that for you as soon as it sees the #version 300 es pragma.

Where to go from here

Feel free to take the code and play around with it. All code is licensed under the MIT license (see LICENSE).

You are not tied to the <shader-art> web component I created for educational purposes. You can re-use this knowledge in any webgl framework like THREE.js, PIXI.js, P5.js and more. I've created a repository with a couple of webgl templates using different frameworks: https://github.com/learosema/webgl-templates.

If you like to learn all the things about shaders, have a look at https://thebookofshaders.com/. Also, check out https://iquilezles.org/.

If you love to learn all the details about WebGL, have a look at webglfundamentals.org. Also, I shared a lot of information about webgl on my personal website, lea.codes.

Also, a definite recommend is the course threejs-journey.com by Bruno Simon, especially if you prefer not to dive too deep into WebGL internals and shaders and focus on working with a fully fledged 3D engine and doing content creation.

As <style> tags would then be put into the body, I added a html transform rule which moves those <style> tags from <body> to <head>. Although browsers seem to tolerate style tags inside <body>, it would not be valid HTML.

Those html transforms are processed in my Eleventy project at build time using linkedom, which is a lightweight and fast DOM implementation. The code for it is put into a separate eleventy config file which can be loaded into the main configuration file via eleventyConfig.addPlugin.

Using LinkeDOM is pretty straightforward, you have a parseHTML function where you pass-in a string of HTML code and you will get a DOM API back to work with, containing { document, customElements } and more.

So, moving a style tag from head to body on the server-side looks similar to how you would do it in browser-side JavaScript:

// Moves style tags from body up to the head.
module.exports = function ({document}) {
  document.body.querySelectorAll('style').forEach(style => {
    style.remove();
    document.head.appendChild(style);
  });
};

For embedding the demos into my articles, I used a tab widget inside a <figure> element, but that widget shouldn't be included into the rss feed, so I only put links to the demos and added a transform rule which adds the tab widget into the blog articles on the website.

The tab widget follows the pattern of the Example of Tabs with Manual Activation of the ARIA Authoring Practices Guide (APG).

Below is an example of such a demo embed.

In a next iteration, I could maybe separate the code into HTML/CSS/JS tabs, similar to what you know from embeds like Codepen or jsfiddle.

The code

This needs some clean up, I could imagine putting that into an Eleventy plugin. Right now it's sprinkled over all of the code base, but I coded that while I was in hospital during my awake times, only having my iPad with me, laying most of the time in a sickbed.

Links to the code:

• Layout file for demos
• Eleventy demo-Shortcode for inserting figures with link and description
• Inserting tab widgets into the figures at Eleventy build time
• Creating Source Code views (mainly in order to have something like view-source links that also work on iPad)
• Clientside JS for the tab widget

Yesterday, the law draft for the promised gender recognition act (aka Selbstbestimmungsgesetz or self-determination act) was leaked. Sadly, the main focus weren't trans people but anti-trans talking points. TLDR it doesn't deserve to be called self-determination act.

The main concern of the gender recognition act reform in Germany (so called #selbstbestimmungsgesetz) should have been how to remove discrimination and make life easier for trans people. But in fact the law drafter's main concern was how to prevent potential abuse of the law through men, which is a talking point mostly driven by the far-right and anti-trans activists.

I won't share the far-right news site where the leak of the law appeared but instead a friendly source.

The fear of potential abuse is spread across the whole law text. Improvements for trans people were not the focus. Formerly, 2 psychiatric assessments were necessary to change your name and gender marker, you had to answer very intimate questions and you have to pay about 2000€ or more for it. This is no longer necessary, and to be fair, this is a great improvement. But in return, the new law in its current form would worsen the rights of trans people drastically, affecting all areas of everyday life.

There is a waiting period of 3 months added to the law draft. After you've changed the name via the law, you have to wait 3 more months until the name and gender marker is corrected. It is incapacitating and in direct contrast to self-determination. It is also endangering, as conversion therapy during this period can forcibly drive trans people to revoke the declaration.

After the name and gender becomes valid, a further correction of the name and gender marker is blocked for a year. In the former law, there wasn't a waiting period. Intersex people who were able to skip the psychiatric assessments through the 45b law will also have to wait 3 months then, which is a deterioration to their current situation.

In case of war and a return of conscription, the new law wouldn't allow changing the name and gender as it could potentially be abused by men who want to escape from military service.

Another concerning part of the new law is §13, which states that the law should be re-evaluated in 5 years. We expect to get a conservative–right government in 5 years. There is an acute danger that the law could then be repealed by the next government.

A big anti-trans talking point that made it into the law text is the narrative about men abusing the law in order to invade women's spaces, such as changing rooms, showers and women's sauna. The new law references domiciliary rights. It's a guideline of how a sauna provider for example can deny a trans person entrance if they see the intimacy of other guests affected. Usually, the equity law (AGG) prevents denying people entrance just because of their look or their genitals.

Also, this point has nothing to do with reality but is mostly driven by far-right and anti-trans people. In fact, I haven't been in the sauna for many years, like many other trans women. Trans people usually don't bother other people, they just want to live their life. But it's often the case we have to fear harassment from anti-trans people. The last time I've been in a mixed sauna, I was harassed by men in the mixed changing room (unfortunately, there was a lack of single cabins for changing clothes).

Conclusion

In the end, it's sadly a very bad law draft that doesn't improve the situation for trans people but makes it worse, affecting all areas of life. Trans women are women and trans men are men, but only if they conform and only if they don't affect cis peoples lives in any way. It may be even unsure if I can keep my name and gender after the law is re-evaluated by the conservatives.

Germany is a shit country. After 16 years of having a right-conservative government with the CDU, we finally had a government without the CDU (aka red-yellow-green ampel coalition). That is an opportunity to finally make necessary reforms possible after the CDU blocked it for 16 years. Especially abortion rights and trans rights.

Unfortunately, we have the FDP in the government and they are blocking everything progressive because they would love to form a coalition with the conservatives in the next legislation period. The conservatives still have a lot of influence through the federal countries and overall they are gaining popularity again, so it's expected we're going to get the conservatives in the government in the next legislation. Hopefully not for another 16 years.

But most importantly, it's better to stay optimistic. It's still a draft. I still hope the paragraphs about the waiting time, the reference to domiciliary rights and the paragraphs about potential abuse of the law get dropped, either while finalizing the law or afterwards through the constitutional court.

I would like to see trans organizations and also Sven Lehmann and others from the green party speaking up.

A common JavaScript implementation for pseudorandom numbers is available in a gist by @blixt.

I wanted to use that in Eleventy, so I added a prng.js file inside my data directory.

prng provides a prng.init(12345) function to provide a seed value, which you can use from Nunjucks/Liquid via double brackets.

To generate random numbers, prng.js provides a random function and also a randInt function.

• random generates float values between 0 and 1 (exclusive 1).
• randInt(a, b) generated integer values between a and b (inclusive b)
• curve() is a method to generate a bunch of random coordinates for SVG curve paths.

There is one little pitfall with this. random is an impure function, which means it is not purely dependant on function parameters but relies on a variable outside the function scope. Before I implemented prng.init as a function, it was just a property. But there's a special thing when using Eleventy as a dev server: it keeps the internal state of variables between builds. Using a function instead to initialize the seed value ensures the seed value is always initialized with the desired value on every build.

In order to provide the seed from frontmatter data, it is required to pass that also to the prng.init function.

The code for generating the waves is here.

The result looks like this:

The process for auto-generating the preview images is described in detail by Bernard Nijenhuis and also integrated into eleventy-excellent by Lene Saile.

I also added linkedom for dom-like html transforms.

Credits for the automated checks and transforms go to Vadim Makeev

HTML Validator

For validating HTML, I'm running the Nu HTML Validator against the dist directory. Validating HTML helps catching mistakes I might have otherwise missed. It also catches some accessibility bugs, like an aria-labelledby pointing to an invalid id.

I installed it via npm i -D vnu-jar and added an npm script for checking the html:

{
  "scripts": {
    "lint:html": "java -jar node_modules/vnu-jar/build/dist/vnu.jar --skip-non-html --filterfile .vnurc dist"
  }
}

In the filter file, you can specify regular expressions to ignore certain errors. I added the role about adding the list role on unordered lists, because Safari removes the role it when you add list-style: none to the css.

The .list. role is unnecessary for element .ul.\.

This GitHub action executes these check on every commit.

Post-processing HTML

This blog is built with eleventy. Eleventy provides transforms as a way to post-process your output files.

In order to efficiently work with HTML, it would be cool to have a familiar API for manipulating the HTML structure, like a DOM API. A popular one for this use-case is JSDOM. I'm using Linkedom which has basically the same API but is more lightweight and also faster. Additionally, it provides possibilities to serialize dom trees to JSON, which is nice.

The flow for post-processing the HTML is to parse the HTML output via Linkedom, which returns a dom object where I can do all the things I know from browserland-JavaScript like dom.document.querySelector or dom.document.appendChild. Afterwards, I can return it back as HTML via document.toString().

The code for this is here: HTML transform configuration for Eleventy

For now, I just added a transform that adds ids for headlines, making headlines and sub-headlines linkable. Another potential use case for this kind of transforms is to also add additional automated accessibility checks. Check the document structure, test if everything has accessible names and check image descriptions, for example.

Another missing feature I plan to add through this is the recognition of external links and maybe open them in a new tab (I'm a bit divided on this, but when I do, I should also convey the information the link opens a new tab).

ESLint

ESLint is a tool to check my JavaScript code for common pitfalls. The configuration is pretty straightforward. All I did here was to npm install eslint, provide a basic configuration file and add an npm script to my package.json:

{
  "scripts": {
    "lint:js": "eslint eleventy.config.js src/assets/js"
  }
}

Additionally, I've set up a GitHub action for it which is run on every pull request and push to main.

Stylelint

Same as above for stylelint. I'm using a minimalistic stylelint configuration to avoid the most common pitfalls. I have to find out for myself which configuration works best for me. For now I went with stylelint-config-recommended and I have also set up a github action for this.

Semantic Release

I'm using semantic-release for version management. It automatically takes care of creating release download files and adding git tags.

To use it, it assumes a certain commit message structure. According to prefixes, version numbers are counted up and every release is shown on the GitHub repo page of this blog, including a Changelog in the description.

Fixes (all commits prefixed with fix:) lead to a minor version upcount. Features (all commits prefixed with feat:) lead to a middle version upcount. If you add "BREAKING CHANGE" to the commit description, this leads to a major version upcount. When doing a breaking change, also provide upgrade information in the breaking change.

For now, I just publish to GitHub, not to NPM (thus the private field in the package.json).

To set it up, all I had to do was to npm i -D semantic-release, setup the repository URL in the package.json, setup a github action and set the permissions for actions inside my organization to read/write access.

I mainly used semantic-release for library code, not for websites yet. So this is more of an experiment, I don't know yet if it is too useful.

Further improvement

Of course, there is room for further improvement. One thing to look into are automated accessibility checks out there, like pa11y. There's a lot of stuff I have to experiment with and figure out what works best for me. Especially the html validation was very insightful and helped identifying some issues in the document structure, but I might not need it on every commit.

It is based on eleventy-excellent by Lene Saile. I learned a lot of new things by studying her work. It's indeed excellent.

Learnings

• Kudos to Andy Bell and his talk about building excellent websites that just work for everyone.
• You can organize your eleventy configurations by splitting them up in multiple config javascript files
• CSS and JS as first-class citizens in Eleventy
• All the SEO stuff, this is really great. It was also a bit overwhelming to me as I never really had in-depth touch points with SEO
• Kudos also to the SEO Cheat sheet by 9elements, it helped me a lot getting the basics.
• Using pseudo random numbers in Eleventy where you provide a seed and always get the same sequence of random numbers.
• Reset CSS by Elly loel
• lowering specificity with :where
• I learned about CSS Layers, making lowering specificity with :where not necessary anymore 😅
• There's this new rust-based lightningcss which can minify, autoprefix according to a browserslist :)

Things left to improve

1. The theme switcher is based on JavaScript, the fallback for now is to not provide theme options but respect the user's color scheme preferences. Also, this can cause a flash in the first contentful paint so a server-side solution might be better (there's an Eleventy Edge example I have to look into).

2. Automatic accessibility checks. There's a netlify plugin I didn't manage to get working yet.

3. I didn't get too comfy with Tailwind and using that as design tokens yet.