DEV Community: Till Sanders

Automatically combine your scattered documentation with a few lines in GitLab CI

Till Sanders — Mon, 28 Feb 2022 13:00:27 +0000

Our documentation lives in scattered Readme's

At FinanzRitter, we have a lot of repositories. Some do small things, some do big things. All are documented in Readme files, written in Markdown. That works really well for us, because it allows us to keep the documentation where the code lives. However, when we're onboarding new developers we struggle to get them up to speed because:

all the information is scattered and we don't have much documentation that would explain where everything is and how it connects to work together.
We're also missing pieces on why we structured things a certain way.
And lastly, we have no place for things that don't really belong anywhere: code snippets, how-tos etc.

We need a system to combine all Readme's and a little more

With this struggle, we set out to find a solution.

We don't want to separate our documentation from our code base.
We don't want to maintain the same documentation in two different places.
We don't want to put a lot of extra work into it.
We do want the ability to add documentation that does not belong to a specific repository but rather explains overarching concepts.
We do want to have one tool to rule them all. One place where everything comes together.

Why we chose Outline

I'm not affiliated in any way with Outline.

Outline is, as they put it: „Your team’s knowledge base“. It's an online documentation tool built on the Markdown syntax. We chose it over competitors like Confluence, Notion and Slite because Outline is:

simple, easy to use and minimalistic in design. It does one thing and does it well.
open source (not strictly FOSS), built in public and can be self-hosted.
has a solid API.
has a fair price structure starting at 10 USD / month for 10 users (not per user)

Using the API to push Readme's to Outline

Outline supports collections (we have, for example a collection for frontend documentation, for backend documentation, infrastructure and onboarding). Collections contain pages and subpages. So you have plenty of options to organize things.

We integrated our Readme's into Outline using their API and a job in our GitLab pipelines. The pipeline will take the contents of the Readme and push them to the Outline API, overwriting a given page completely. With a little more work it should also be possible to only overwrite a certain section of a page, but we opted for completely overwriting them for ease-of-use and safety.

So for example, our 'Frontend' collection contains a page called 'Data Management', explaining the overall concept of handling data on the client. It has three sub-pages, one for every repository we have that plays a role in managing the data. Those are updated automatically to mirror the Readme's on GitLab:

Frontend (Collection)
 → Data Management (Page, written in the Outline editor)
    → DataCollection (Subpage, synchronized from the repo's Readme on GitLab)
    → DataStore (Subpage, synchronized from the repo's Readme on GitLab)
    → DataVersion (Subpage, synchronized from the repo's Readme on GitLab)

How it works

We add a new document stage to our GitLab CI pipeline, as well as a document job. This should run after a release job.
This job reads the README.md from your repository. And replaces the headline (which is expected to be # Your Repository) with a warning: „This page automatically mirrors the documentation of *Your Repository. Don’t make changes here or they will be lost with the next release.”* This marks the page as being automatically mirrored to Outline and prevents us from loosing manual changes. We don't have a two-way synchronization here!
Lastly, we sent the modified Markdown inside a JSON object to the Outline API.

Setting up the integration

1. Create a new page in Outline

Create a new page / subpage in Outline and collect its alias from the URL. For example, an alias might look like this:

how-to-set-up-outline-integration-nkOq0DuntG

2. Get an API Token

Create an API token in the settings: https://your_organization.getoutline.com/settings/tokens and save it to your GitLab repository or group as a new CI environment variable. We're naming it OUTLINE_AUTH_TOKEN. It will now be available to your job. You should also make it protected. If you do so, make sure the job is only running on protected branch- or tag-pipelines or it will fail because of the missing API token.

3. Add the job to your pipeline

Add the following job at the end of your .gitlab-ci.yml:

document:
  stage: document
  before_script:
    # depending on your base image, you probably need to install jq
    - apt update && apt install -y jq
  script: |
    ORIGINAL=$(cat README.md)
    WARNING=':::info
    This page automatically mirrors the documentation of [Your Repository](https://gitlab.com/your_username/your_repository). Don’t make changes here or they **will be lost** with the next release.
    :::
    \'
    DOCUMENT=$(echo "${ORIGINAL/\# Your Repository/$WARNING}" | jq -Rs .)
    curl https://your_username.getoutline.com/api/documents.update \
      -X POST \
      -H "authorization: Bearer $OUTLINE_AUTH_TOKEN" \
      -H 'content-type: application/json' \
      -H 'accept: application/json' \
      --data-raw "{\"id\": \"your_page_alias\", \"text\": ${DOCUMENT}}"

Make sure to adapt the job to your repository. You need to replace:

The name (Your Repository) and URL of your GitLab repository (https://gitlab.com/your_username/your_repository)
The sub-domain or URL of your Outline instance (https://your_username.getoutline.com)
The page alias (your_page_alias)
Possibly the name of your Readme. We use README.md.

Also, the rules or only/except (depending on what you are using) should match the configuration of your release job(s). So the documentation is only published when a release has been built.

You also might want to add allow_failure: false to the release job(s), if they have a manual trigger. Otherwise, the document stage will run regardless of their success.

Caveats

Outline has a feature that allows 'Collaborative editing' in real-time with multiple people. It is disabled by default (February 2022) and can be enabled in the Features section of the settings. If active, the integration does not work. I haven't digged deeper into this. Maybe someone has a solution?
Using the script above, you can only publish one Markdown file. If you have multiple, you need to add multiple jobs or adapt the script accordingly.
This is currently GitLab-only. It sure would be nice to have A GitHub Action for other folks. If someone creates one, please let me know!

Feedback for Outline

Your API documentation is good, thank you! Maybe it can be improved regarding the collaborative editing?
Your WYSIWYG editor often does not behave as I'm used to, especially in regards to lists. It's not buggy, but it could use some fine-tuning.
It would be amazing to have an integration like this natively!
Your design is really clean, I enjoy using Outline very much!

Let's stop using [a-zA-Z]+

Till Sanders — Mon, 08 Mar 2021 19:27:20 +0000

If you, like me, regularly (see what I did here?) validate alphanumeric fields using Regex, you probably learned to do it like this:

'Till'.match(/[a-zA-Z0-9]+/gu)

This is technically correct, of course. And it's what most validation libraries will do when you tell them a field is alpha / alphanumeric / etc.

However, I have a problem with this approach and a lot (!) of other people do, too. Because I'm from Germany. More specifically, from a town called Lüdenscheid. And Lüdenscheid won't match the regular expression above because of the Umlaut. Same applies for languages like French, Spanish, Czech, just to name a few.

So how can we as developers be more inclusive towards languages other than English? Do we have to include all possible variations of the latin alphabet? That's a common suggestion, but of course, it doesn't scale well.

Luckily, Unicode has us covered:

'Lüdenscheid'.match(/[\p{Letter}\p{Mark}]+/gu)

The \p flag allows us to pick a so called Unicode Character Category. In Unicode, all characters are sorted into categories that we can use in our regular expression. The Letter category includes letters from all kinds of languages, not just A-Z. But it does not include, e.g. <, >, + or $ which is important for security. The Mark category – as lionelrowe pointed out in the comments (thanks) – contains combining marks. In Unicode, a letter like ü can be either one or two combined code points. So depending on how the character is coded, we need the Mark category.

More details on the Mark category

If we omit the Mark category and run the following Regex: 'Lüdenscheid'.match(/[\p{Letter}]+/gu) it will match Lüdenscheid, if the ü is encoded as a single character. On the other hand, if the ü is encoded as a letter-mark-combination (u + ̈), the regex will only match Lu, because it will stop at the ̈ mark.

Browser support

Browser support for this feature is good, IE (not Edge) being the only exclusion.

Bonus

// Match only letters
'Lüdenscheid'.match(/[\p{Letter}\p{Mark}]+/gu)

// Match letters and spaces
'Pražští filharmonici'.match(/[\p{Letter}\p{Mark}\s]+/gu)

// Match letters and hyphens
'Île-de-France'.match(/[\p{Letter}\p{Mark}-]+/gu)

// Match letters hyphens and spaces
'Île-de-France'.match(/[\p{Letter}\p{Mark}\s-]+/gu)

Tell us what you don't know!

Till Sanders — Sun, 07 Feb 2021 18:59:25 +0000

Too often do we take part in discussions about topics we actually don't no much about. Especially on the internet. And especially during the pandemic. I would have loved to have heard the following sentence more often: "I do not know".

We're all experts at something, but none of us are experts at everything. So please join me in this little practice of telling us – but even more importantly yourself – what you no nothing about.

This can be something you still want to learn but also something you will probably never learn. This can be about programming, obviously, but doesn't have to be.

Bonus challenge

As a bonus, think about people who do have the skills you find yourself missing. Or think about people, maybe your colleagues, that you believe are more successful than you are. Focus on your feelings towards them. Do you admire them? Or do you maybe also experience some envy? Just ponder on these emotions for a while and see how they mix. Simply being aware of these feelings will help you become more professional. Just acknowledge that you don't know everything. There will always be someone who can do something better than you can. And that's okay. It's perfectly fine.

Allow yourself to be passionate about your work but aim for a professional detachment. You are not your work.

Deploy Nuxt.js on DigitalOcean App Platform in 5 minutes or less

Till Sanders — Wed, 03 Feb 2021 00:52:03 +0000

I recently find myself deploying more and more projects using the DigitalOcean App Platform because it is so damn quick. I love writing Dockerfiles and deploy my containers to a Kubernetes cluster, but with a Platform-as-a-Service solution such as AWS Elastic Beanstalk or the aforementioned solution by DigitalOcean which is even easier to use, I feel like I really don't need to. I've used Elastic Beanstalk in the past, but the pricing always was a bit too high for small projects. With the great usability and pricing of the DigitalOcean App Platform, I started deploying side-projects there. Today I tried deploying a Nuxt installation to App Platform for the first time and found a small hurdle, that somehow wasn't really documented in any tutorial. So here we go!

I assume, that you have basic devop knowledge, including DNS servers, environment variables, and stuff.

1. The container

That's easily the best part. You don't need one, because you can use the default Node container provided to you by DigitalOcean 👍

2. The repository

DigitalOcean App Platform deploys your apps right from their respective git repositories. So, assuming you already have a Nuxt.js project in a GitHub or GitLab repository, you can jump right in: Go to your DigitalOcean Admin Panel

3. Set up your DigitalOcean App

Hit the big green 'Create' button and start creating a new 'app'.
Connect your GitHub or GitLab account if you haven't already. Select the repository containing your Nuxt.js project below and click 'next'.
Choose a name and region and proceed to the next step. Here, we have a few settings to make. DigitalOcean should have detected the Node environment.
We want to deploy it as a Web Service.
You can set the environment variables if you need any.

4. Getting health checks right

This is the only problem I stumbled upon. To get health checks working, we need to change the default run command:

The build command should be npm run build – fine!
The run command should be npm start by default, but we need to change it to npm start -- --hostname 0.0.0.0
The default Nuxt.js port is 3000 so we need to either change the port in the app platform setting, or set the run command to npm start -- --hostname 0.0.0.0 --port 8080. Chose what you like better. I went with 3000.

5. Set up your domain

Finish the setup and wait for the deployment to complete. With the health checks set up properly, there shouldn't be any issues. Once that is done, you can make more adjustments to your app settings, like connecting your domain.

I hope this was helpful 🚀

I'm tired of building APIs

Till Sanders — Sat, 23 Jan 2021 17:22:06 +0000

There. I said it. Building APIs is getting harder. When I first started building services with Laravel 3, things were different, simpler, more enjoyable.

So what changed?

Authentication got more complex

Easily the biggest hurdle when building an API is authentication. Back in the days I would simply generate an API key and be done with it. Now we're shifting to microservices and JWT before most people even understood the complications of that. Getting authentication right (secure + easy to use) has gotten so hard, that I would not recommend anyone to build their own. It just takes too long and you'll probably get it wrong anyway. So we're using services like Keycloak or Auth0 that introduce their own kind of complexities (deployment, data privacy, et cetera).

How to deploy a free Auth0 alternative to DigitalOcean in 5 minutes

Till Sanders ・ Jan 18 ・ 4 min read

#devops #security #webdev #selfhosted

Authorization is complex (still)

This has always been difficult. There are systems and libraries ready to go and they're great. My problem with most authorization solutions is though that they have users and roles and groups, but no concept of ownership. Oftentimes I want to authorize an action depending on who a given object belongs to.

REST vs. GraphQL

I was very content with REST. It just made a lot of sense. But now, all I can see are the problems it has compared to GraphQL which is so great on the client side and such a pain on the server side. At this point they both feel like a bad choice.

SQL vs. NoSQL

Same as with REST. MySQL felt so logical to me. But when you're designing a slightly more complex data structure, you end up with lot's of tables, very quickly. Most of the time this also leads to more models, more APIs, more tests, etc. MongoDB on the other side is so much fun when it comes to nested objects. But somehow I still feel uneasy leaving normalized data and my neatly organized migrations behind.

Too big frameworks vs. too small

Laravel is great! But it also became a bit overwhelming. It has always felt magical, but also difficult to understand what's going on behind the scenes. I don't think it has become harder to understand or to learn, there is just more of it. Sometimes I would prefer it to be a little smaller. That's when I look at Node.js frameworks like Adonis, Nest or Fastify. I feel like I can make more choices there. With frameworks like Fastify I can come up with my own architecture, which I really enjoy. But I'm missing a solid authentication solution in the Node.js world.

Testing

I'm actually not sure if testing just wasn't a thing in Laravel 3, or if my junior dev ass just ignored it, but I didn't do any automated testing. Nowadays I do, of course, and I wouldn't stop doing it, but testing APIs feels so repetitive and time consuming. I need tests, but when I'm working on a side-project I would rather work on the actual software.

Deployment

I used to just synchronize my code to some server using Transmit. I even recall writing a very angry e-mail to ExpanDrive once because it messed up my files, which was a great pain because I wasn't using Git back then. But aside from that deployment was simple. Today containerization makes deployment so much better and so much more complicated at the same time. I love it and it scares me at the same time.

Casting and DTOs

With Laravel 3 I would simply return an object I got from the database, it would then be converted to JSON automatically and wrapped in an HTTP response. And while that still works, of course, I now find myself writing DTOs for every model, at least for Create and Update, sometimes for more specific actions. I also spend time casting some properties back and forth because JSON is quite limited when it comes to typing.

Security & Law

CORS. CSRF. HTTP-only cookies. CORS. SSL certificates. GDPR and other privacy laws. CORS.

Conclusion – I'm the problem.

Yes, many things changed and many got more complicated. But there are also a lot more tools and platforms to chose from. Great things happened that made my work a lot easier (like Chrome DevTools or Directus). So what's really the problem here? I'm afraid after all these years I simply got to a point on the learning curve that is high enough to see all these things properly.

When I started web development I simply couldn't see many of these issues. And now that I do, I cannot ignore them. And sometimes, yes, that is tiring. Becoming more professional at what you do doesn't mean it's getting any easier. You just get better at doing it.

Copyright of the title image belongs to the BBC.

How to deploy a free Auth0 alternative to DigitalOcean in 5 minutes

Till Sanders — Mon, 18 Jan 2021 19:35:57 +0000

Many of you might have already used a service like Auth0 to hand-off user authentication and authorization to a dedicated service. I think this is a sane solution to the ever-growing problem of getting authentication right. Technologies like OAuth and JWT sound great, but they are very easy to get wrong with mistakes that are very hard to discover. Also, implementing authentication again and again is hardly fun. So, Auth0 or Firebase are nice solutions to hit the ground running, but some projects (or budgets for that matter) require self-hosted solutions, like Keycloak.

Keycloak as a free, self-hosted authentication server

As the project describes itself, Keycloak is an "open source identity and access management [tool] for modern applications and services", which allows you to "add authentication to applications and secure services with minimum fuss. No need to deal with storing users or authenticating users. It's all available out of the box. You'll even get advanced features such as User Federation, Identity Brokering and Social Login.".

Why would you want this?

Save money in the long run. Auth0 starts at 23 USD / month for 1.000 users.
Building your own solution is hard. Very. And not nearly as good.
Login + Registration for a new service set up in minutes.
E-Mail verification is built-in.
2FA is built-in.
Social logins for sites like Facebook, Twitter, LinkedIn, Instagram, GitHub, GitLab – only a few clicks away.
Bring your own theme!
Use as a SSO (Single Sign On) solution for multiple services
Connect to existing LDAP or Active Directory services

If I wanted to build something like this, it would take me months and I still wouldn't know it's safe.

Sounds great? It is. Let's give it a spin, shall we?

Deploy to DigitalOcean App Platform

Recently, DigitalOcean launched the PaaS solution, called DigitalOcean App Platform. Since we want to take the hassle out of authentication, this seems like a perfect fit to deploy our own authentication server.

I assume, that you have basic devop knowledge, including DNS servers, environment variables, databases, docker, and stuff.

1. The container

Luckily, Keycloak provides a container, optimized and ready to go. It's rather new and called 'keycloak-x'. You can read more about it here. And more about it's configuration here.

2. Your repository

DigitalOcean App Platform deploys your apps right from their respective git repositories. You can provide a Dockerfile or use the readily available environments provided by DO. Since we already have a container, you can go ahead and create an empty repository for this project on GitHub or GitLab. All you need in this repository is a simple Dockerfile:

FROM quay.io/keycloak/keycloak-x

3. Set up a database

You can configure a development database in step 4, create a new database in an existing database server, or create a new database server now.

Sign into your DO account and create a new database server. We will use MySQL in this example. Configure your cluster as you like. We're going with the smallest configuration. Once your database server is deployed, add a new database called keycloak and a new user, also called keycloak. Copy all credentials for the next step.

4. Set up your DigitalOcean App

Hit the big green 'Create' button and start creating a new 'app'. Connect your GitHub or GitLab account if you haven't already. Select the repository below and click 'next'. Choose a name and region and proceed to the next step. Here, we have a few settings to make. DigitalOcean should have detected the Dockerfile. We want to deploy it as a Web Service with the following environment variables:

KEYCLOAK_ADMIN=yourusername
DB_VENDOR=mysql
DB_ADDR=
DB_PORT=
DB_DATABASE=keycloak
DB_USER=keycloak
DB_PASSWORD=
KC_PROXY_MODE=edge
KC_METRICS_ENABLED=true
KC_HTTP_ENABLED=true
KC_HOSTNAME_FRONTEND_URL=https://auth.example.com/
KC_HOSTNAME_ADMIN_URL=https://auth.example.com/

Of course, make sure to provide the correct details for your database connection and set your own keycloak username and a strong password. Note that we're disabling https here since the SSL connection will be terminated by DO. Also, make sure to add a trailing / to the hostname urls!

Port is 8080 and health checks should work fine with TCP.
(Actually, although health check urls are enabled using KC_METRICS_ENABLED, I didn't manage to get HTTP health checks working yet. So if you see something that I didn't, please leave a comment.)

Go ahead and deploy!

5. Configure your very own keycloak server

By now, your keycloak instance should be up and running. I would recommend adding another domain in the settings of your DigitalOcean app. You don't have to, though. Just make sure KC_HOSTNAME_FRONTEND_URL and KC_HOSTNAME_ADMIN_URL match your generated or custom domain and your DNS servers are configured accordingly.

You can access your installation under the assigned or your custom domain. Simply log in with your admin credentials.

If you need some help getting started with keycloak, I can recommend this video: https://www.youtube.com/watch?v=duawSV69LDI

Also, I had a problem where I couldn't access the login screen of the realm I created in keycloak. All I ever got was an alert that keycloak could not be initialized and a 403. It turned out eventually, that I needed to set the Web Origins setting of my client to a wildcard: * to allow access from any origin. But that was simply a beginner's mistake.

Hope you had an easy time following along. Leave a comment below and tell me how it went and what you're planning to do with it!

ESLint not working in VSCode? Help build a troubleshooting checklist!

Till Sanders — Mon, 11 Jan 2021 19:35:33 +0000

I spend far too much time fighting configuration issues in my toolchain. Most issues I even encounter frequently. Help me build a troubleshooting checklist. Simply add other possible configuration mistakes in the comments and I will add them to the article.

Start here

Did you run `npm install`?

Stupid, I know. But I forget to do this quite a lot when coming back to a shared project.

Did you try turning it off and on again?

Sometimes it helps to restart VSCode and I've even had problems that were solved with restarting my computer, though that is rather rare and might also have been related to the TypeScript server.

Did you install ESLint + Plugins + Presets?

Take a look into your eslintrc configuration file and make a list of all plugins and presets. Than make sure, they as well as ESLint itself are in your projects devDependencies.

Is your npm script set up?

Do you have a lint script in your package.json?

  "scripts": {
    "lint": "eslint --ext .js --ignore-path .gitignore ."
  }

Did you tell ESLint, which directory to lint?

I recently encountered a project where the lint script in the package.json was missing the dot at the very end which tells ESLint to start linting in the same directory as the configuration file is in. This was not easily detected, since ESLint didn't throw any warning but just quit silently.

Did you make sure, ESLint is linting the correct file extensions?

In case you're using TypeScript, Vue.js or other non-standard JavaScript files, make sure to tell ESLint about your file extensions by using the --ext flag like so --ext .js,.ts,.vue.

Do you have more `.eslintrc` configuration files?

Since .eslintrc configuration files automatically extend configuration files in higher directories, this can cause weird issues. Make sure you don't have any additional configuration files anywhere in your project or in the directories above, that you are unaware of. Sometimes, I accidentally scaffold a project in my home directory and forget to delete the hidden .eslintrc.js.

When looking for more .eslintrc files, remember, that they might be invisible to your file explorer. Use ls -a to show hidden files in your terminal.

Additionally, you can stop ESLint from searching further up the directory tree by adding the root option to the .eslintrc in your project root directory:

{
    "root": true
}

Learn more about Configuration Cascading and Hierarchy in the official documentation.

Do you have the ESLint plugin installed and enabled in VSCode?

Maybe you've just set up a new VSCode installation or something's gone wrong syncing your settings. Make sure, the ESLint plugin is installed and also enabled in VSCode.

Did you set up library execution?

The ESLint plugin requires permission to execute the local ESLint installation from your node_modules. Open the command palette (Ctrl / Cmd + Shift + P) and select ESLint: Manage Library Execution to open the dialog for your project and confirm with 'Accept'.

Did you maybe disable the rule you're testing?

Sometimes we mess projects up. Some might use Standard JS, others the AirBnB preset. Some projects disable certain rules. Make sure, you're not testing a rule that isn't even enabled.

Are you having trouble with the TypeScript integration?

Make sure to install the TypeScript plugin and configure it accordingly: https://github.com/typescript-eslint/typescript-eslint

Do you have confusing overrides?

You might have added some overrides (note: not 'overwrites' – another mistake I made once) for test files or similar. Remove them from your config for a minute to see if that changes anything.

Is the ESLint plugin configured as expected?

Open your VSCode preferences and search for ESLint. There's a host of settings, so make sure, they are all set as you want them to.

Most important:

Validate: Should contain all languages you want to lint
Node Path
Run: Wether to run on save or continuously

Also, be aware, that you might have accidentally overwritten these settings for your workspace or even only one project in your workspace. You can access these overwrites from the VSCode settings panel by simply clicking on 'Workspace' or 'Folder' below the search bar.

Nothing is helping? How to find the solution yourself!

Update all ESLint related dependencies

Maybe you've stumbled upon a bug and maaaaybe it has already been fixed? Use npm outdated to find outdated dependencies in your project and just try to update ESLint, your plugins and presets. If you've installed ESlint globally, take care to use the correct installation.

Are your plugins and presets still maintained?

Some plugins or presets might not get any updates. Take a look at their repositories and issue trackers. Maybe someone there is even experiencing the same problems?

Is the message you're seeing even coming from ESLint?

The origin might also be in other tools like TypeScript or Prettier. You can see which tool is generating the message in VSCode at the end of the message in round brackets.

Take a look at the output panel in VSCode

Open the command palette by pressing Ctrl / Cmd + Shift + P and select 'ESLint: Show Output Channel'. If ESLint throws any errors, they should appear here. That's always a good starting point for further debugging.

Try setting up your ESLint config from scratch

Remove everything ESLint related and start from scratch using the eslint --init command that helps you set everything up.

Add your own troubleshooting tips in the comments!

I will add them to the article so whenever you encounter something new, make sure to leave a comment ;)

Boy, was it hard to implement proper keyboard shortcuts

Till Sanders — Sun, 10 Jan 2021 02:14:48 +0000

I'm currently implementing a complete redesign of our primary administration interface. This web application is used by our customer service every day to read, write and process heaps of information and complex data structures. When you're designing an interface for such trained users, priorities shift a great deal. These users prefer speed over simplicity, so you start to seriously optimize things like navigation. And the easiest, maybe even the most important way to speed up navigation is by providing keyboard shortcuts. Most websites don't really use custom keyboard shortcuts because they take too much time to learn. But for users who spend many hours a day working with a web application, keyboard shortcuts are indispensable. And so my journey began...

TL;DR

I built a polyfill for the accessKeyLabel property that reveals the keyboard shortcut assigned by the browser and based on the accessKey property assigned to an interactive element. Browsers use different shortcuts for this and the accessKeyLabel property is the best way to improve the discoverability of custom shortcuts in web applications. Native support is missing in Chrome, IE and Edge. My AccessKeyLabelPolyfill is bridging the gap with less than 1 KB. GitHub | Demo

Using the `accesskey` property to quickly add keyboard shortcuts

Since HTML 4, we've had the power to add custom keyboard shortcuts to our webpage using the accesskey property.

<button accesskey="d">Do crazy stuff</button>

Simply by adding this property to a button, I've set up a keyboard shortcut. In most browsers, pressing Ctrl + Alt + D will now trigger this button. Great! So I just added this to a number of buttons in our application and called it a day? Unfortunately not. See, what modifier keys (Ctrl, Alt, Shift, etc.) will be combined to a shortcut is not standardized. And I wish that was the only problem.

Browsers don't use the same key to make the shortcuts

So, as I said, most browsers use Ctrl + Alt. At least on macOS. Except for Firefox before version 14. Back then, it only used Ctrl. On Windows, the same browsers generally use only the Alt key. Except for Firefox, which seems to strive for cross-platform consistency. Nice. These are, however, only the browsers whose behaviour was documented on MDN. As you know there are loads more. And at least some even allow to customise their behaviour. This means that the actual shortcut depends on the browser, it's version, your operating system and possibly your personal settings. But don't worry, it get's worse.

Users are unaware of keyboard shortcuts on websites

Let's face it. Most people are completely dumbfounded when it comes to keyboard shortcuts. If you're ever trying to impress people, just show them the Tab key. But when they're working with the same application every day, we should try to educate them to help speed things up. So now that we have keyboard shortcuts thanks to accesskey, how can we make them easily discoverable?

Proven technique to indicate keyboard shortcuts

For some reason, I'm seeing this technique less and less in modern systems – probably due to aesthetic reasons. But it has been around for decades and I doubt that it get's any more elegant than this. The idea is simple and every little as space-saving as it is helpful: just underline the character that is the access key.

<button accesskey="d"><u>D</u>o crazy stuff</button>

By using a consistent scheme (like Ctrl+ Alt / Alt) and underlining the access key, we give users a subtle hint or reminder which character provides access to a specific action. Neat.

Underlining the access key is not enough

We surely can improve the discoverability of our shortcuts even more. Right now, the biggest issue is that users are probably unfamiliar with the default keyboard shortcut of their browser. So why don't we add a small reminder. For big buttons with enough space, we could add a small text below. For others, we could add tooltips or use the title attribute.

<button accesskey="d">Do crazy stuff</button>
<small>Hint: Use Ctrl + Alt + D to quickly access this button!</small>

Great! But as we learned in the beginning, browsers use different modifier keys for our shortcuts. How do we handle this?

The `accessKeyLabel` API reveals the exact shortcut

Thankfully, the accessKeyLabel API of HTML 5 will tell us the exact keyboard shortcut the browser assigned to our button. That's great! We can access this property in a Vue.js component and add it to our hint easily. No magic required.

Chrome does not support `accessKeyLabel`

Well, I must admit – I didn't see that one coming. While accesskey is supported perfectly, Chrome, Internet Explorer (okay, no surprise...), Edge, Safari for iOS < v13 and more don't (yet) support accessKeyLabel. That's a bummer. Firefox and Safari for macOS however, have good support. But it's still not enough to rely on.

Use my polyfill

As it turns out, there is a ticket in the bug tracker of the chromium project that's been calling to add support for the accessKeyLabel property since 2014. Unfortunately, other things seem to have a higher priority, so until native support arrives in all major browser, we need a polyfill.

What is a polyfill?

A polyfill is a script that patches native functionality that has not yet arrived in certain browsers or will not arrive because of old age. Polyfills generally aim to provide the exact same functionality and API as the original specification. Some things, however, can only be partially implemented using polyfills. What's great about polyfills is that they allow us to use new technologies without needing to worry too much about "older" browsers. The disadvantage is, of course, that we're adding more code to our website that might slow it down a little bit more. That being said, most polyfills are actually quite small.

My search for a polyfill was surprisingly unsuccessful. I stumbled upon a jQuery plugin, but wanted something vanilla JavaScript.

Sometimes, to provide great user experience and accessibility, you have to go to great lengths. I tend to do that. So here is my very first polyfill. It is vanilla JavaScript and weighs under 1 KB:

tillsanders / access-key-label-polyfill

Polyfills the accessKeyLabel property to improve discoverability of native keyboard shortcuts for your website. Tiny and dependency-free.

AccessKeyLabelPolyfill

Polyfills the accessKeyLabel property to improve discoverability of native keyboard shortcuts for your website. Tiny (< 1KB) and dependency-free.

With the accesskey HTML property you can easily provide keyboard shortcuts for the buttons of your web application.

<button accesskey="D">Do crazy stuff</button>
<!-- Can be activated using Ctrl + Alt + D -->

Sadly, most users don't even know these shortcuts can be used, even if the web developer provided them. To make these shortcuts more discoverable you might decide to use the title property, a tooltip or some other UI element to display the keyboard shortcut.

<button accesskey="D">Do crazy stuff</button>
<small>Hint: Use Ctrl + Alt + D to quickly access this button!</small>

A good idea, but browsers use different combinations of modifier keys. But…

View on GitHub

Installation and usage of the AccessKeyLabelPolyfill

You can install the polyfill using npm or yarn:

npm i access-key-label-polyfill
# or
yarn add access-key-label-polyfill

And then import and execute like this:

import installAccessKeyLabelPolyfill from 'access-key-label-polyfill';
installAccessKeyLabelPolyfill();

Reading the `accessKeyLabel`

I integrated this into a Vue.js button component that also has some neat methods to automatically underline the first occurrence of the accessKey in the button caption, but you might use it any way you like. You can read the documentation of the accessKeyLabel property on MDN, because the API of the polyfill is exactly the same. But it's quite simple, so here is an example:

const label = document.querySelector('#button').accessKeyLabel;

The polyfill will first check if accessKeyLabel is supported natively and exit if so. Otherwise it will try to detect the browser and operating system and return the correct keyboard shortcut as a string that can be displayed in a <small> tag, a tooltip, or the title attribute. Get creative!

If you're using the polyfill with Vue.js, React, Svelte, Angular or other frameworks, remember to only load it once!

Try the demo!

You can visit the demo to try the plugin right in your browser. The demo will also tell you wether the polyfill detected native support or not. Try the demo!

The state of keyboard shortcuts in web applications

Today's odyssey into the accessKeyLabel property revealed to me the many issues we face regarding shortcuts in web applications. Not only are the shortcuts not standardised and support for the simple accessKeyLabel API is missing in most browsers, but I was unable to discover the shortcut in Chrome for Android. Maybe I was due to a lack of a proper Android tablet for testing or maybe accesskey is simply not supported. To me, it's unclear how access keys might interfere with screen readers, browser shortcuts or even other applications. There is also no standard on how browsers handle conflicting access keys. But what's easily the biggest issue is usage. It is rare to see a web application use these features, even the complex ones that would benefit greatly from it. By taking the time of writing and publishing this polyfill, I hope to make keyboard shortcuts in web applications more accessible to you all by bridging the gap in browser support.

DEV Community: Till Sanders

Automatically combine your scattered documentation with a few lines in GitLab CI

Our documentation lives in scattered Readme's

We need a system to combine all Readme's and a little more

Why we chose Outline

Using the API to push Readme's to Outline

How it works

Setting up the integration

1. Create a new page in Outline

2. Get an API Token

3. Add the job to your pipeline

Caveats

Feedback for Outline

Let's stop using [a-zA-Z]+

Luckily, Unicode has us covered:

More details on the Mark category

Browser support

Bonus

Tell us what you don't know!

Bonus challenge

Deploy Nuxt.js on DigitalOcean App Platform in 5 minutes or less

1. The container

2. The repository

3. Set up your DigitalOcean App

4. Getting health checks right

5. Set up your domain

I'm tired of building APIs

So what changed?

Authentication got more complex

How to deploy a free Auth0 alternative to DigitalOcean in 5 minutes

Till Sanders ・ Jan 18 ・ 4 min read

Authorization is complex (still)

REST vs. GraphQL

SQL vs. NoSQL

Too big frameworks vs. too small

Testing

Deployment

Casting and DTOs

Security & Law

Conclusion – I'm the problem.

How to deploy a free Auth0 alternative to DigitalOcean in 5 minutes

Keycloak as a free, self-hosted authentication server

Why would you want this?

Deploy to DigitalOcean App Platform

1. The container

2. Your repository

3. Set up a database

4. Set up your DigitalOcean App

5. Configure your very own keycloak server

ESLint not working in VSCode? Help build a troubleshooting checklist!

Start here

Did you run npm install?

Did you try turning it off and on again?

Did you install ESLint + Plugins + Presets?

Is your npm script set up?

Did you tell ESLint, which directory to lint?

Did you make sure, ESLint is linting the correct file extensions?

Do you have more .eslintrc configuration files?

Do you have the ESLint plugin installed and enabled in VSCode?

Did you set up library execution?

Did you maybe disable the rule you're testing?

Are you having trouble with the TypeScript integration?

Do you have confusing overrides?

Is the ESLint plugin configured as expected?

Nothing is helping? How to find the solution yourself!

Update all ESLint related dependencies

Are your plugins and presets still maintained?

Is the message you're seeing even coming from ESLint?

Take a look at the output panel in VSCode

Try setting up your ESLint config from scratch

Add your own troubleshooting tips in the comments!

Boy, was it hard to implement proper keyboard shortcuts

Using the accesskey property to quickly add keyboard shortcuts

Browsers don't use the same key to make the shortcuts

Users are unaware of keyboard shortcuts on websites

Proven technique to indicate keyboard shortcuts

Underlining the access key is not enough

The accessKeyLabel API reveals the exact shortcut

Chrome does not support accessKeyLabel

Use my polyfill

Did you run `npm install`?

Do you have more `.eslintrc` configuration files?

Using the `accesskey` property to quickly add keyboard shortcuts

The `accessKeyLabel` API reveals the exact shortcut

Chrome does not support `accessKeyLabel`

Reading the `accessKeyLabel`