diff --git a/README.md b/README.md index 43650fe..b263ad3 100644 --- a/README.md +++ b/README.md @@ -15,56 +15,118 @@ Dependencies To build: - Hugo 0.93 or later -- Make +- bmake or GNU Make. OpenBSD make (omake) should work too, but I haven't tested it. - Git (Hugo uses Git info for features like date last updated) +- [htmlq](https://github.com/mgdm/htmlq), to parse HTML when fetching some webring links and for some post-processing. +- POSIX utils: `grep`, `find`, POSIX-compliant `/bin/sh`, etc. + +Before deploying, I use some tools to process the output. + +- `xmllint`, part of libxml2, to format the generated polygot XHTML5 markup. +- [sd](https://github.com/chmln/sdA) (for advanced multi-line regex operations, much of which exist to fix `xmllint`'s output) + +I also apply static compression at max levels, using the following tools: + - [Efficient Compression Tool](https://github.com/fhanau/Efficient-Compression-Tool) It's like zopfli but more efficient and faster. -- Brotli (optional; set `NO_STATIC=1` to disable) -- POSIX utils: grep, find, etc. +- Brotli To deploy: -- ssh -- rsync -- libzstd +- rsync, with SSH and zstd support To lint: -- stylelint -- csslint -- pnpm -- [lychee](https://github.com/lycheeverse/lychee) +- stylelint, invoked using pnpm. +- [lychee](https://github.com/lycheeverse/lychee), to check broken links. +- A very recent build of the w3c's [Nu HTML checker](https://github.com/validator/validator) to validate the HTML and XHTML. +- [jq](https://stedolan.github.io/jq/), to filter false-positives from the Nu HTML checker. -See the `Makefile` for details. +Build instructions +------------------ -Design ------- +- To just build the HTML: `make hugo` +- To build the polygot formatted HTML and XHTML: `make hugo xhtmlize` +- To lint and validate: `make hugo xhtmlize lint-local` +- To build everything and compress: `make hugo xhtmlize compress` +- To deploy the clearnet site and corresponding Tor hidden service: `make deploy-prod deploy-onion` -I made the site as inclusive as possible. Tested using multiple screen readers (Orca, TalkBack, Apple VoiceOver, Windows Narrator, NVDA), and I regularly test with the following browsers/engines. Testing in a browser does not imply any sort of endorsement; I just want to meet people where they're at. +`make` can parallelize only a little, since many jobs depend on previous jobs. -Desktop: +Compatibility +------------- + +I made the site as inclusive as possible. Tested using multiple screen readers (Orca, TalkBack, Apple VoiceOver, Windows Narrator, NVDA), and I regularly test with the following browsers/engines. Testing in a browser does not imply any sort of endorsement; I just want to meet people where they're at and I want my site to be as robust as possible. + +For all the listed options, I test "reading mode" whenever it's available. Most of my testing happens on Linux since that's my main OS, but I sometimes test on a Windows machine. + +The main compatibility issue is a lack of support for `
`; the only non-mainstream engine to support it is Servo. The site is still perfectly usable without support for `
`; users will just be annoyed by pre-expanded toggle buttons that don't do anything. + +### Desktop + +Mainstream engines: - Gecko: Nightly, Stable, ESR, and sometimes Pale Moon - the Tor Browser - Blink: latest Chromium snapshot, stable, and QtWebEngine -- WebKit: Webkit2GTK3 +- WebKit, via Webkit2GTK3 + +Non-mainstream engines: + - NetSurf -- SerenityOS Browser -- Very old WebKit via rekonq (Qt4 QtWebKit) -- KHTML +- [The SerenityOS Browser](https://github.com/SerenityOS/serenity/tree/master/Userland/Libraries/LibWeb) (does not yet support ECDSA-based certs, so I test on my Tildeverse mirror). Known issue: SVG avatar doesn't render unless I view it in a new tab. +- Very old WebKit via rekonq (Qt4 QtWebKit). +- KHTML (KF5), via Konqueror. - Servo -- Trident, if I have access to a Windows machine that has Edge with "IE Mode". +- Tkhtml, via Hv3 (no TLS 1.2, so I use a terminating proxy or localhost version) -For all the above options, I test "reading mode" whenever it's available. +Tested on a provisional basis, when I have access to a Windows machine: -Mobile: +- [Winternight Classic](https://github.com/ClassicNick/Crescent-Vine). +- IE 11. +- Even older WebKit, via Safari 5.1.7. Requires a TLS terminating proxy. +- Ancient Gecko, via NetScape Navigator. Requires a TLS terminating proxy. + +Desktop screen readers tested: + +- Orca +- NVDA +- Windows Narrator +- TODO: borrow someone's mac and test macOS VoiceOver. + +### Mobile - Android: Blink, Gecko, Tor Browser -- iOS WebKit: latest stable version, iOS 12, iOS 10 on an iPhone 5. Also test Reader Mode. -- TODO: try a KaiOS device. +- iOS WebKit: latest stable version, iOS 12, iOS 10 on an iPhone 5. Also tested Reader Mode. +- TODO: try a KaiOS device and Samsung Internet's dark mode. -Smart watches: +The site should work well even on viewports that are under 240 CSS pixels wide. + +Mobile screen readers: + +- TalkBack +- VoiceOver +- TODO: test KaiOS Readout + +### Smart watches - Borrowed an Apple Watch to try the embedded browser. -- TODO: test on a Tizen or Wear OS device's browser. +- TODO: test on a Tizen or Wear OS device's browser (Samsung Internet is a popular choice) -Everything works well in all the above browsers. +## Accessibility + +To my knowledge, this site meets all applicable WCAG 2.2 AA requirements. + +This site meets all applicable WCAG 2.2 AAA requirements, with the following exceptions: + +- SC 1.4.8 Visual Presentation: long article body text for articles should have an average character count per line below 80 characters. Some lines may exceed this limit. Text outside of article bodies has a longer line width. +- SC 2.4.9 Link Purpose (Link Only): I mostly follow this guideline, but there may be some exceptions. Link purpose in context is always clear, though. +- SC 3.1.5 Reading Level: the required reading ability often exceeds the lower secondary education level +- SC 3.1.6 Pronunciation: I do not yet provide pronunciation information. + +I have only tested WCAG compliance in mainstream browser engines (Blink, Gecko, WebKit). + +I also go further than WCAG in many aspects. + +- Rather than follow SC 2.5.5's requirement to achieve a minimum tap target size of 44 by 44 pixels, I follow Google's more strict guidelines. These guidelines mandate that targets are at least 48-by-48 pixels, with no overlap against any other targets in a 56-by-56 pixel range. +- I ensure at least one such 56-by-56 pixel non-interactive region exists on the page, for users with hand tremors or or anyone who wants to tap the screen without clicking something. +- I only set custom colors in response to the `prefers-color-scheme: dark` media query. These custom colors pass APCA contrast ratios, all being close to the ideal lightness contrast of 90. They are also autism- and overstimulation-friendly colors: yellow links are significantly de-saturated to reduce harshness.