Forem: Fotis Papadogeorgopoulos

HTTPS for Local Sites

Fotis Papadogeorgopoulos — Mon, 27 Jul 2020 12:11:29 +0000

I recently set up pi-hole, a local DNS sinkhole. It redirects lookups for ad-related domains into the void (and any other domain, via a blocklist). This post is not about pi-hole itself though. Rather, it is about adding HTTPs to the local interface.

Let’s define the problem better. The pi-hole runs on a Raspberry Pi, on the local network. It does not listen on the public internet, and its port is not exposed to it. Pi-hole offers an admin interface as a web UI. It is available locally, under its IP address, or a domain that you can configure locally. I would like to have HTTPS, because accessing sensitive data over an unencrypted connection, local as it may be, seems icky.

In order to enable HTTPS, we need some kind of domain, and a certificate for that domain. We also do not want to go for a self-signed certificate solution.

We thus have to solve the following:

Getting a domain to point to our IP
Getting a certificate for that domain
Auto-renewing that certificate when it expires

I will stress the automation part. Historically, I have been really bad at remembering to update certificates, or restart servers after certificates auto-renew. You might have more consistency than I do!

Getting a domain

I decided to use a sub-domain of fotis.xyz, in this case pi-hole.fotis.xyz.

We could then resolve it via a DNS record to our local IP address, or do it per-device via a hosts file. I went with the hosts file, because I only really administrate the pi-hole through my laptop, and I can always access the admin via IP from other devices (albeit unencrypted). This solves the domain issue.

Worrying about DHCP leases and changing IP for the pi-hole is out of scope for this post :)

Getting a certificate for that domain

This is the interesting part, where I had gotten stuck in the past. I want to use LetsEncrypt, because they are awesome LetsEncrypt uses a mechanism called ACME (Automatic Certificate Management Environment) to issue challenges, that the server must answer to prove that you own the domain.

The “regular” challenge mechanism, that I was familiar with at least, is over HTTP. The client uses a well-known address like http://<YOUR_DOMAIN>/.well-known/acme-challenge/<TOKEN> to place the challenge token, which LetsEncrypt then validates. This process can be manual or automated, for example with plugins for popular servers, such as Apache and Nginx.

However, this does not work for sites that are resolved locally. For example, my local Raspberry Pi only listens on local addresses. The HTTP port 80 is not exposed to the internet. An HTTP ACME challenge would fail, because the pi cannot be reached. It also means I must resolve the domain to the local address at a public DNS level, instead of locally.

That’s when I found the DNS Challenge mechanism. The ACME client makes the request, and gets a challenge token to place in a TXT DNS record (e.g. TXT for _acme-challenge). LetsEncrypt then validates the presence of that record, to verify our control. This is promising, because the Pi can communicate outwards, and nothing needs to connect to its HTTP port!

Automation

Now, you could copy this TXT record manually, but that sucks for the short renewal period of LetsEncrypt. Historically, as I mentioned, I have been bad at staying on top of it.

Surprise! Most DNS providers offer an API these days, to add records and so on. So you can perform the addition of the TXT record as part of the challenge pipeline, with some artisanal scripting. This verifies that you have control of the domain, without caring about the ip it resolves to (or that ip needing to be listening on the internet).

To avoid artisanal scripting, and make this reproducible, I used acme.sh, an ACME client for the command line. I have used Certbot in the past, but I was a bit lazy about managing Python this time around! acme.sh has integrations to many DNS providers, including the one I use, DNSimple.

<h3>Warning</h3>
 <p> This has some security implications, such as your web server having access to editing DNS. Depending on the granularity of the API tokens, this can be dangerous!</p>

The LetsEncrypt documentation outlines the pros and cons of each challenge type.

This post by Joona Hoikkala on the EFF blog discusses different mitigation strategies.

A more applied example

The following is a guide (mostly to myself) about setting this up with pi-hole specifically.

Install acme.sh

First, install acme.sh via their instructions. I used the “pipe to shell” method, but I know not everyone likes that. Remember to restart the terminal session for it to appear in the PATH.

Set up lighttpd

We must respond to the host name that we define (e.g. pi-hole.fotis.xyz) from our Raspberry Pi. pi-hole uses lighttpd for the HTTP UI already, so it made sense to me to reuse it.

I added the following file under /etc/lighttpd/external.conf, adapted from Scott Helme’s post on pi-hole.

# Install this under /etc/lighttpd/external.conf
$HTTP["host"] == "pi-hole.fotis.xyz" {
  # Ensure the Pi-hole Block Page knows that this is not a blocked domain
  setenv.add-environment = ("fqdn" => "true")

  # Enable the SSL engine with a LE cert, only for this specific host
  $SERVER["socket"] == ":443" {
    ssl.engine = "enable"
    ssl.ca-file =  "/home/pi/cert.pem"
    # This file does not come right off acme.sh, it is merged from the two files
    ssl.pemfile = "/home/pi/merged.pem"
    ssl.honor-cipher-order = "enable"
    ssl.cipher-list = "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"
    ssl.use-compression = "disable"
    ssl.use-sslv2 = "disable"
    ssl.use-sslv3 = "disable"
  }

  # Redirect HTTP to HTTPS
  $HTTP["scheme"] == "http" {
    $HTTP["host"] =~ ".*" {
      url.redirect = (".*" => "https://%0$0")
    }
  }
}

Getting the certificate

Now we must get the certificate. We want to use the DNS challenge mode of acme.sh.

We first get a token from DNSimple (this will vary on your provider).

I stored it in a .env file locally on the server:

export DNSimple_OAUTH_TOKEN="sdfsdfsdfljlbjkljlkjsdfoiwje"

I then sourced that file, to export the variables on the CLI:

source .env

Finally, we are ready to issue the ACME challenge, and hopefully acme.sh will do the rest, including editing the DNS records:

acme.sh --issue --dns dns_dnsimple -d pi-hole.fotis.xyz

Once it is set up, acme.sh handles auto-renewal via a cron job. No more email snoozing, yay!

Installing the certificate

acme.sh will store the certificates in its internal folders (under /home/pi/.acme-sh). We are not supposed to rely on that structure, so it provides an --install-cert command to move the certificates to the correct place.

I used the following command

/home/pi/.acme.sh/acme.sh --install-cert -d pi-hole.fotis.xyz \
    --key-file       /home/pi/key.pem  \
    --fullchain-file /home/pi/cert.pem \
    --reloadcmd     "cat /home/pi/key.pem /home/pi/cert.pem > /home/pi/merged.pem && sudo service lighttpd restart"

Some things to note here. First of all, the home/pi/key.pem and /home/pi/cert.pem locations are meant to match the location where lighttpd expects them. I was confused by the terminology of acme.sh and of lighttpd, so I just named them in a way that made sense to me!

The “reloadcmd” argument is the tricky bit. It will run whenever the new certificate is installed, to prompt the server to use it. This command depends on your server. In my case, lighttpd needs the private key and chain file to be merged , so I do this as part of the setup script.

Hosts resolution

I edited the hosts file (/etc/hosts) on my own machine, to point the domain pi-hole.fotis.xyz to the known IP address of the pi-hole.

# Replace x.x with your local address :)
192.168.x.x pi-hole.fotis.xyz

I can now visit pi-hole.fotis.xyz locally, and see it secured, hooray!

Wrapping up

I hope this short guide on setting up HTTPS for local sites was useful! In addition to security, many modern browser APIs require HTTPS to function, so I suspect I will be using it again in the near future. Did I miss anything? Have you had a different way of doing this? Get in touch, and let’s talk!

A toLocaleString Mystery

Fotis Papadogeorgopoulos — Fri, 24 Jul 2020 07:10:50 +0000

Recently, at work, one of our tests started failing. Our site is available in 11 languages, and the months for Azerbaijani (with the Latin script) had inconsistent capitalisation!

After investigating, and a little bit of good guessing, it turned out to be an issue with the localisation data in the browser and Node themselves.

This post digs into how I went about investigating that issue, with entirely too many diversions along the way. I hope it gives you a fun insight into how localisation data ends up in JS APIs, and how to spot errors!

Numeronyms

Internationalisation and Localisation are commonly referred to as i18n and l10n respectively. These are called numeronyms, representing the start and end letters, as well as the number of letters omitted. For example, i - 18 letters - n.

Numeronyms can be useful as a short representation and provide more accurate terms for web search. For the purposes of this post, I'll type them out long-form, but I wanted to point it out in case you run into it in the links.

One day, I might shorten my name to Fotis P16s...

The bug

Let’s frame the problem.

We have a function that provides a list of months (in the Gregorian calendar), localised for one of the languages and scripts that we support. For English US, that would be “January, February, March…”.

JavaScript environments, whether web browsers such as Chrome and Firefox, or Node, provide a set of APIs for localisation and internationalisation. Two common ones are the Intl namespace of APIs, and the Date object with its toLocaleString method. We use toLocaleString specifically to get a localised month, for each month of the calendar.

However, the result of calling those APIs can vary depending on the data that each browser has available.

Because that possibility can sometimes be unexpected (especially for people that have not worked with multiple languages or scripts before), last year we added a series of tests to verify the localisation of months.

Then, at some later point, our tests started failing:

AssertionError: expected [ Array(12) ] to deeply equal [ Array(12) ]
+ expected - actual

[
-  "yanvar"
+  "Yanvar"
    "Fevral"
-  "mart"
+  "Mart"
    "Aprel"
    "May"
    "İyun"
    "İyul"
    "Avqust"
    "Sentyabr"
    "Oktyabr"
    "Noyabr"
-  "dekabr"
+  "Dekabr"
]

In other words: the months for Azerbaijani with the Latin script, Yanvar (January), Mart (March) and Dekabr (December) were lower case, while all the other months were capitalised.

First step, checking our own function

Before going down the path that the data might be wrong, let’s make sure that our own function is not doing anything absurd.

The function itself is provided below, a small wrapper around calling toLocaleString for 12 Dates.

function getArrayOfMonths(localeTag) {
  // Months for Date are 0.=11
  const months = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11].map((month) => {
    const dateobj = new Date(1970, month, 15);
    return dateobj.toLocaleString(localeTag, { month: 'long' });
  });
  return months;
}

(There are subtleties to getting a list of months this way, which may make the results wrong or unidiomatic. In our use, those are fine, but I am listing an example with noun cases at the end of the article.)

Running this function in Firefox and Node (with localisation data, more on that later!) brings up the same results:

// Node
// NODE_ICU_DATA=node_modules/full-icu node    
// Welcome to Node.js v12.16.3.

> console.log(getArrayOfMonths('az-AZ'));

[
  'yanvar',   'Fevral',
  'mart',     'Aprel',
  'May',      'İyun',
  'İyul',     'Avqust',
  'Sentyabr', 'Oktyabr',
  'Noyabr',   'dekabr'
]

// Firefox

> console.log(getArrayOfMonths('az-AZ'));

Array(12) [ "yanvar", "Fevral", "mart", "Aprel", "May", "İyun", "İyul", "Avqust", "Sentyabr", "Oktyabr", … ]

Firefox and Node having the same inconsistent capitalisation was already tipping me off. They are different engines, so them processing the data in the same odd way seemed too good to be a coincidence.

Chrome only prints out English months, but that is as-intended, because it does not support Azerbaijani in Intl/toLocaleString yet, and I did not specify a fallback.

Finding if a locale is supported with Intl

The Intl family of APIs is really powerful. They have a bunch of namespaces and constructors to account for different lingustic artefacts and locales. For example, there is Intl.DateTimeFormat for formatting dates and times (day month year? month day year? fight!).

One useful function is Intl.DateTimeFormat.supportedLocalesOf. It takes an array of locales as BCP 47 language tags, such as en-GB (English as used in Great Britan) or el-GR (Hellenic/Greek as used in Greece) as an argument, and returns an array of the ones that are supported:

> console.log(Intl.DateTimeFormat.supportedLocalesOf(['az-AZ', 'en-GB', 'el-GR']))

['az-AZ', 'en-GB', 'el-GR']

Here I would go on a tangent about locales being a complex interaction of languages, regions and scripts, but this post has already too many diversions, and I don’t feel qualified to give you good examples.

To account for these interactions, BCP 47 tags have optional components for scripts, region or country codes, variants, and also reserved extensions. I found this article from MDN on locale identification useful for a short explanation.

Azerbaijani (as far as my searching shows, I might be wrong) has both a Latin and Cyrillic script. Those would be az-Latn-AZ and az-Cyrl-AZ respectively. As far as I can tell, az-AZ defaults to Latin, but I am not sure if that is an artefact of a specific data source.

A past Chrome bug with supportedLocalesOf

When I started seeing issues with Azerbaijani in particular, I was already on my toes about issues with data.

About a year ago, we had run into a bug with Azerbaijani and Chrome, which claimed it supported it via supportedLocalesOf, but would give placeholder months.

In particular, this was the behaviour from this function back then (circa July 2019):

> Intl.DateTimeFormat.supportedLocalesOf(['az-AZ']);

['az-AZ']
// Means it is supported

> getArrayOfMonths('az-AZ')
[M0, M1, M2, M3, ... M11]

In other words, ‘az-AZ’ was purportedly supported, but the months were these odd M0 to M11 months, which seemed like internal placeholders. If Azerbaijani was unsupported, I would expect supportedLocalesOf to not report it, and also the months to be in English GB (because that is my system locale, and I did not specify a fallback).

After double- and triple-checking with colleagues and different platforms, I filed a bug in Chromium, and it was confirmed! It was eventually fixed, and supportedLocalesOf reports Azerbaijani as unsupported.

Long story short, Azerbaijani being unsupported indicates to me that the localisation data might be incomplete. I have referenced “the data” multiple times now; let’s dive into what that data is, and where it comes from.

Localisation data: ICU, CLDR, oh my!

Let’s take a few different Intl APIs:

DateTimeFormat, uhm, formatting (as is bugging us so far)
Pluralization (e.g. apple, 2 of them = two apples, or more complex changes for languages that differentiate between “one”, “a handful”, and “many”)
Locale names (e.g. saying that “Greek” is “Ελληνικά” in Greek)

You can imagine that all of the underlying data (calendars, names of months, pluralization rules) must be coming from somewhere!

Indeed, there is a standard resource for these in the ICU (International Components for Unicode) data. Quoting from the site:

ICU makes use of a wide variety of data tables to provide many of its services. Examples include converter mapping tables, collation rules, transliteration rules, break iterator rules and dictionaries, and other locale data. Additional data can be provided by users, either as customizations of ICU’s data or as new data altogether.

A related data-set is the CLDR (Unicode Common Locale Data Repository). Quoting again from the site:

The Unicode CLDR provides key building blocks for software to support the world’s languages, with the largest and most extensive standard repository of locale data available. This data is used by a wide spectrum of companies for their software internationalization and localization, adapting software to the conventions of different languages for such common software tasks. It includes: …

The ICU data-set uses CLDR itself for many things, with a few differences:

Data which is NOT sourced from CLDR includes:

Conversion Data

Break Iterator Dictionary Data ( Thai, CJK, etc )

Break Iterator Rule Data (as of this writing, it is manually kept in sync with the CLDR datasets)

Those data come in different formats, such as XML (LDML), categorised by locale (roughly, that I can tell). The ICU data seems more commonly used by higher-level libraries, because the format is more compact.

With this data available, browsers have enough information to provide the richer Intl and Date localisation APIs.

Handwaving

Here are some things I am handwaving at this point.

I use ICU and CLDR rather interchangeably. As far as I can tell, the ICU data is derived from the CLDR data. I found better links for the CLDR sources, so I am digging into those.

I am also not 100% clear on whether all browsers use the ICU/CLDR data at the moment, or use some other source. I could not find anything normative about the data source in the specs (I would find that surprising anyway), and I am bad at going through issue trackers.

I found one tracking issue about Firefox transitioning to the CLDR data, and at least my testing seems to support that. Perhaps the CLDR data version would be useful for browsers to expose? Not as an API, rather an `about:` config or something similar in the UI.

Node definitely uses the ICU data, and gets its own following section for it.

Excerpt from the CLDR Data

For example, here is the top-level directory structure from one download of the CLDR data:

> tree -L 1 cldr-common-35.1/
cldr-common-35.1/common/
├── annotations
├── annotationsDerived
├── bcp47
├── casing
├── collation
├── dtd
├── main
├── properties
├── rbnf
├── segments
├── subdivisions
├── supplemental
├── transforms
├── uca
└── validity

An excerpt from the main directory:

> cldr-exploration tree -L 1 cldr-common-35.1/common/main
cldr-common-35.1/common/main
├── af_NA.xml
├── af.xml
├── af_ZA.xml
├── agq_CM.xml
├── agq.xml
├── ak_GH.xml
├── ak.xml
├── am_ET.xml
├── am.xml
├── ar_001.xml
├── ar_AE.xml
├── ar_BH.xml

And here is part of the data for English (common/main/en.xml):

<monthWidth type="wide">
    <month type="1">January</month>
    <month type="2">February</month>
    <month type="3">March</month>
    <month type="4">April</month>
    <month type="5">May</month>
    <month type="6">June</month>
    <month type="7">July</month>
    <month type="8">August</month>
    <month type="9">September</month>
    <month type="10">October</month>
    <month type="11">November</month>
    <month type="12">December</month>
</monthWidth>

ICU and Node

If you have tried to work with internationalisation in Node, you might have run into the ICU data yourself.

Up until version 13 (a few months ago), Node only had a base English locale loaded. The ICU data takes up space on the order of tens of megabytes, and so Node for the longest time did not come with them installed.

To get correct localisations in Node, you had to either a) build Node yourself with the full-icu dataset loaded, or b) install the correct build of the icu data locally, and provide the path via NODE_ICU_DATA.

It was messy, and probably still exists as an arcane parameter in current and aging codebases. Watch tests fail because NODE_ICU_DATA is not supplied, ugh.

Node getting the full ICU data built-in from version 13 was one of my favourite features, and if you’ve read this far, at least someone else might now understand my excitement!

If you are curious:

Either way, now that we have gone through all the abbreviations, we’re in a good spot to find the data and investigate it!

Digging into the CLDR data

Time to dig into the CLDR data, to validate whether the months in Azerbaijani show up capitalised, uncapitalised, or inconsistent.

To check for any changes (and in the case of our test, regressions), I downloaded CLDR versions 35.1, 36.1 and 37.

I started browsing through the directories and quickly got lost because my search skills are bad.

I then decided to go with a more drastic approach, and headed to the command line. In my case Gnome Terminal on Linux, but iTerm on MacOS or Windows Subsystem for Linux would work just as well, if you want to follow along.

There is a nice utility called ripgrep which can search through files very fast. It is written in Rust and is lovely, though to be honest I just didn’t remember the grep flags any more.

Anyway, I went searching through the files. I used “Yanvar” capital case and “yanvar” lower case for the known issues, as well as “Oktyabr” capital case and “oktyabr” lower case as a control.

The results from ripgrep across three versions follow, and then a long-form explanation of them.

# Yanvar capital case - 1 result from version 35.1
>  az-AZ-exploration rg "Yanvar" cldr*/**/az.xml 
cldr-common-35.1/common/main/az.xml
1412:  <month type="1">Yanvar</month>

# Yanvar lower case - two results for version 36.1 and 37, one for 35.1
>  az-AZ-exploration rg "yanvar" cldr*/**/az.xml
cldr-common-37.0/common/main/az.xml
1360:  <month type="1">yanvar</month>
1404:  <month type="1">yanvar</month>

cldr-common-36.1/common/main/az.xml
1360:  <month type="1">yanvar</month>
1404:  <month type="1">yanvar</month>

cldr-common-35.1/common/main/az.xml
1368:  <month type="1">yanvar</month>

# Oktyabr capital case - one result for each version
>  az-AZ-exploration rg "Oktyabr" cldr*/**/az.xml
cldr-common-37.0/common/main/az.xml
1413:  <month type="10">Oktyabr</month>

cldr-common-36.1/common/main/az.xml
1413:  <month type="10">Oktyabr</month>

cldr-common-35.1/common/main/az.xml
1421:  <month type="10">Oktyabr</month>

# Oktyabr lower case - one result for each version
>  az-AZ-exploration rg "oktyabr" cldr*/**/az.xml
cldr-common-37.0/common/main/az.xml
1369:  <month type="10">oktyabr</month>

cldr-common-36.1/common/main/az.xml
1369:  <month type="10">oktyabr</month>

cldr-common-35.1/common/main/az.xml
1377:  <month type="10">oktyabr</month>

We have a winner! From version 36 onward, we get “yanvar” as lower case for January, while “Fevral” for February stays capitalised for all versions. The same pattern repeats with March and December. Version 35, by comparison, has both Yanvar and Fevral (and all the other months) capitalised.

Data sources

Something I found interesting: the data for months appears in two places, once in a “months” entry, and once in a “calendar” entry (again, for the Gregorian calendar).

The “months” entry has consistent capitalisation throughout. They are all lower case; “yanvar”, “fevral” and so on.

This hints to me that Firefox and Node use the “calendar” entry for the names of the months in this case. It makes sense, because if you’ll recall our original function, we go through a Date object’s toLocaleString, which deals with dates directly, rather than canonical names or anything of that sort.

Changelog, Contributions

I was curious as to what changed in version 36 onward.

Diving into the Changelog for the CLDR data version 36 we find the following line:

Additionally, the following locales had at least a 15% increase in basic coverage: az (Azerbaijani / Latin script), so (Somali / Latin script).

The inconsistent months might have been entered accidentally, or were caused somehow when the coverage was expanded.

Future steps

This is all many words, for a simple change in our codebase at least: change the test to match the data (3 line change), alongside a description about why that is ok (200 words in the PR, however many words is this post).

I am not keen on capitalising the months ourselves (today’s hotfix is tomorrow’s footgun), but we might do that specifically for Azerbaijani, with an inverse test case to notify us when the data is updated.

Another thing I am looking into, is contributing the consistent capitalisation into the CLDR. Ideally, I would like to submit it as something to be approved by a native speaker, because who the heck am I to say what the capitalisation of months in Azerbaijani should be!

I have not really researched the CLDR process, so this might all be simple.

Wrapping up

Long story short: sometimes, it is the data.

This whole process was some of the most fun I’ve had at work this month! I love it when the different abstraction layers (specs, JS APIs, JS hosts, CLDR data, bugs, messiness) fall into place. Localisation and internationalisation take a lot of material effort, so diving into it makes me appreciate it much more.

In this case, I am also fond of our team’s past selves. We had the tests in place, and had already gone into the ICU/CLDR rabbit hole a year ago, filing the Chrome bug. It was both a time-saver, and brought a smile to my face.

I hope I managed to impart at least a glimpse of that fun to you, and that you found something interesting here.

I’ll be happy to discuss this post and any linked resources!

Appendix: When this method of getting months goes wrong

As mentioned previously, we go through a Date object’s toLocaleString to get the array of months.

However, because the formatting happens in the context of a date, languages with different cases might inflect the month.

When running this function for Greek, we get the following:

> console.log(getArrayOfMonths('el-GR'));

[
  'Ιανουαρίου',  'Φεβρουαρίου',
  'Μαρτίου',     'Απριλίου',
  'Μαΐου',       'Ιουνίου',
  'Ιουλίου',     'Αυγούστου',
  'Σεπτεμβρίου', 'Οκτωβρίου',
  'Νοεμβρίου',   'Δεκεμβρίου'
]

All of these months are in the genitive case (denoting possession). This is the equivalent of saying “x of January”, “y of February” and so on in English. In our site, we use this function in the context of birthdays, so it ends up being ok! If, however, we wanted to only list the months, it would technically be wrong (we’d need the nominative case). Make sure to test for your use-case, and beware of tutorials only assuming English language rules.

I am not certain how I would go about listing the months in the nominative, at least with the Date object. Intl has a draft (Stage 3) family of APIs called Intl.DisplayNames that “enables the consistent translation of language, region and script display names”. Would something similar for month names be desirable? I’m not sure! Let me know if you know of an approach.

HTML details is awesome

Fotis Papadogeorgopoulos — Sun, 24 Feb 2019 14:32:12 +0000

Originally posted on https://fotis.xyz/posts/details-is-awesome/

A while back, I read the slides and notes of a talk by Mu-An Chiou, titled "Details on <details>". It's a fantastic overview of how to use the <details> element of HTML.

In short, details, and its pair summary, are a way to implement native collapsible sections, without relying on Javascript. Toggling content is one of the most common actions on the web, so being able to provide that without scripts is appealing. It is not just collapsible sections though; you can make panels, menus, and other imaginative things with it!

I had stashed that knowledge at the back of my mind. Then, some weeks ago, I was implementing a collapsible section for the webmentions on this blog:

This seemed like a great use case for details. I would get the native functionality of toggling, and could then work with styling it. Let's go over how to implement it.

Implementing a "show all" section

Markup

You nest <summary> inside of <details>. <summary> is what appears as the "toggle button", regardless of the section being collapsed or not. Anything after that will be hidden and only appear when the widget is open.

Here is what an initial attempt at our comments section would look like:

<details>
  <summary>
    Show all (2)
  </summary>
  <ol>
    <li>I am a comment</li>
    <li>I am another comment.</li>
  </ol>
</details>

Styling

There are a couple of extra things to know about styling details.

The arrow is styled with the list-style properties on summary, except in Chrome, which uses ::-webkit-details-marker. You could consider resetting them and then relying on a unified ::before selector.

The open attribute is added when the summary is open. You can query that as details[open] to style the container further. The demo on MDN shows the open attribute in practice.

I also found that on Safari, the summary element cannot be a flexbox container, even if defined in CSS. I wanted to do that to show author images next to the "Show all" text. I added an extra div wrapper inside of summary, to act as a flexbox wrapper.

After adding some more styles to our details, it can look like this:

<details class="details-reset">
  <summary class="summary fg-highlight cursor-default">
    <div class="flex-wrapper-for-safari">
      <span>Show all (2)</span>
      <div class="author-list">
        <div class="author">
          <img src="https://fotis.xyz/img/logo.png" alt="" class="author-image" />
        </div>
        <div class="author">
          <img src="https://fotis.xyz/img/logo.png" alt="" class="author-image" />
        </div>
      </div>
    </div>
  </summary>

  <ol>
    <li>I am a comment</li>
    <li>I am another comment</li>
  </ol>
</details>

:root {
  --highlight: #da0993;
}

/**
  * Styles and resets for the <details> element.
  * @see https://github.com/primer/primer/blob/master/modules/primer-buttons/lib/button.scss#L206-L213
*/

/* Remove marker added by the display: list-item browser default */
.details-reset > summary {
  list-style: none;
}

/* Remove marker added by details polyfill */
.details-reset > summary::before {
  display: none;
}

/* Remove marker added by Chrome */
.details-reset > summary::-webkit-details-marker {
  display: none;
}

/* Other styles */
.flex-wrapper-for-safari {
  display: flex;
  align-items: center;
}

.fg-highlight {
  color: var(--highlight);
}

.cursor-default {
  cursor: default;
}

.author-list {
  display: flex;
  margin: 1rem;
}

.author {
  width: 2rem;
  height: 2rem;
}

.author-image {
  max-width: 100%;
  border-radius: 100%;
  background-color: gray;
}

Focus affordances

In reality, our section summary has two distinct elements; the "show all" button, and the profile pictures of commenters. The whole summary is interactable as far as input methods and highlighting are concerned. This makes sense to start with, and is a benefit of using semantic HTML.

I think we can do a bit better, by enhancing the focus, so that it highlights the action more clearly. If the user focuses (by keyboard or otherwise) on the section, I would like to only highlight the "show all" part. This "nested focus" pattern is something I took out of Heydon Pickering's "Collapsible Sections" article.

<details class="details-reset">
  <summary class="nested-focus fg-highlight cursor-default">
    <div class="flex-wrapper-for-safari">
      <span class="nested-focus-target">Show all (2)</span>
      <div class="author-list">
        <div class="author">
          <img src="https://fotis.xyz/img/logo.png" alt="" class="author-image" />
        </div>
        <div class="author">
          <img src="https://fotis.xyz/img/logo.png" alt="" class="author-image" />
        </div>
      </div>
    </div>
  </summary>

  <ol>
    <li>I am a comment</li>
    <li>I am another comment</li>
  </ol>
</details>

:root {
  --highlight: #da0993;
}

.nested-focus:focus {
  /* NOTE: The only good reason to hide an outline is if you enhance it */
  outline: none;
}

.nested-focus:focus .nested-focus-target {
  outline: 2px solid var(--highlight)
}

/** The rest is the same as above */

Other things to consider would be user-select and cursor. user-select in particular is an open question, so I left it intact. I did give the summary a cursor: default, though there are certainly different ways to prioritise.

Polyfills

The polyfill for details is great. It is small in size (just under 1.5kB), and covers IE and Edge well. It is also a good example of a layered polyfill, where parts of the functionality are polyfilled depending on what is supported. Give the source code a read, I learned a bunch from it.

Accessibility

Scott O'Hara investigated the use of the details element with various screen reader and browser combinations. I would urge you to read that piece for more information and readouts. A summary would be that screen reader support is good, with a few edge cases pending.

(I would love to fill more on this after looking into it myself, and checking the status of the bugs mentioned by Scott).

Apart from Scott's notes, there are a couple of things I would point out for collapsible sections.

Avoid changing the display text

You might notice in the example above that I avoided changing the "Show all" text when expanding. You could do this with Javascript, or even some CSS conditional on the open attribute. Beware though! In toggle buttons, it is common to not change the text, since the state is already communicated via aria-expanded (Heydon Pickering writes about toggle buttons). I think collapsible sections with the details element should follow the same idea, since the state is communicated natively.

If I did want to change the display text, I would try to always expose the same text to screen readers, and keep parity with toggle buttons.

<details>
  <summary>
    <!-- This is exposed to AT -->
    <span class="visually-hidden">Show all (2)</span>
    <!-- These will be hidden from AT -->
    <span aria-hidden="true" class="summary-open">Hide all</span>
    <span aria-hidden="true" class="summary-closed">Show all (2)</span>
  </summary>
  <ul>
    <li>I am a comment</li>
    <li>I am another comment.</li>
  </ul>
</details>

/* Hide visually, but keep in the tree for AT */
.visually-hidden {
  position: absolute !important;
  height: 1px; width: 1px;
  overflow: hidden;
  clip: rect(1px 1px 1px 1px);
  clip: rect(1px, 1px, 1px, 1px);
}

details .summary-open {
  display: none;
}
details[open] .summary-open {
  display: inline;
}
details .summary-closed {
  display: inline;
}
details[open] .summary-closed {
  display: none;
}

However, keeping the rules of ARIA usage in mind, and gauging the value of this feature, I would not implement it. It is not a big deal if "Show all" persists visually, and I like that the presentation is unified. Also, the arrow is a good indicator already, so if you need this feature, then consider not removing it.

Avoid interactive content in `summary`

Interactive content in summary is an open question on the spec. I also would question the need for that. I would not place, say, a button inside a button, and in the same spirit I would not nest something interactive inside summary. Your mileage may vary, and it might be a chance to rework the widget, if you have this use case.

Wrapping up

The details element is a great part of HTML. It offers a lot of commonplace functionality without relying on JS. This is important when it comes to resilience. Between requests failing, or a heavy load on the browser (such as when hydrating server-rendered markup), being able to collapse sections without relying on main scripts is valuable.

There are even more interesting uses of details by Github, such as modals and menus. It has a couple styling hooks of its own, and even some UX questions to explore. The polyfill is well-encompasing, and the accessibility story pretty solid.

Have you tried using the details element in your projects? How did you find it? Let me know!

More resources

Mu-An's presentation and notes that set me on this path. It offers a concise explanation and guidance, perfect for bookmarking and referring to, say, when writing an article :)
The MDN guide on details has a good summary (no pun intended)
The spec for details
The polyfill for details
Heydon Pickering's Inclusive Components has a chapter that explains the various affordances that Collapsible Sections provide. He also goes into details about how to implement one with Javascript. Give it a read, it is good stuff.

Forem: Fotis Papadogeorgopoulos

HTTPS for Local Sites

Getting a domain

Getting a certificate for that domain

Automation

A more applied example

Install acme.sh

Set up lighttpd

Getting the certificate

Installing the certificate

Hosts resolution

Wrapping up

A toLocaleString Mystery

Numeronyms

The bug

First step, checking our own function

Finding if a locale is supported with Intl

A past Chrome bug with supportedLocalesOf

Localisation data: ICU, CLDR, oh my!

Handwaving

Excerpt from the CLDR Data

ICU and Node

Digging into the CLDR data

Data sources

Changelog, Contributions

Future steps

Wrapping up

Appendix: When this method of getting months goes wrong

HTML details is awesome

Implementing a "show all" section

Markup

Styling

Focus affordances

Polyfills

Accessibility

Avoid changing the display text

Avoid interactive content in summary

Wrapping up

More resources

Avoid interactive content in `summary`