The BrooksB Digital Garden

Please share and adapt.

.

Features

The digital garden sports a handful of features to help the wandering reader. Please note, the examples on this page may require JavaScript to function and some links are intentionally disabled.

Color Scheme

A light or dark color scheme is provided depending on your browser theme. I have tried to make color choices such that everything is readable. Generally, I use the dark color scheme the most, so it might be more up-to-date.

The most characteristic feature of the Web are links. They give the Web its name: it is a web of links which connect documents together by reference, allowing users to quickly move between those documents. Hypertext is text with (hyper)links.

Internal vs External

Internal links are displayed in green:

This is an internal link.

External links are displayed in blue:

This is an external link.

Hover

Hovering over or clicking on a link causes it to be highlighted:

This is a link.

Visited

If a link points to a page in your browser history, only its underline will be saturated:

This is a visited link.

If a link points to a page not in your browser history, both the text and its underline will be saturated:

This is a new link.

Last Major Revision

Some articles contain a date of last major revision before their primary content. This only applies to those articles where I think knowing their timeliness is particularly important. The date also doubles as a hyperlink to the article's history. And a word of warning, I change the date manually whenever, in my opinion, the semantics of the article have changed significantly. This means that the date might not be updated for things like typos or other minor corrections which have little impact on semantics.

Images

Alt-Titles

Any element that has its alt attribute defined will have its title attribute default to match its alt attribute. Practically, this means that every non-decorative image will have a corresponding hover tooltip.

Visible Alt Text

Nearly every image comes with a caption that explains the relevant information contained in the image. The caption is written to convert the associated image from informative to decorative. And hence, the associated image is given null alt text. I take this approach because I want to make sure alt-like text is visible to and usable by everyone, not just blind users. The text description can be useful, even for sighted people. For most users, alt text becomes a form of invisible metadata. Always being visible makes it much easier to spot mistakes when the text no longer matches the image for whatever reason.

I read that Scott O'Hara vehemently disagree with this approach. It would be nice if there was a way to indicate in HTML that an image is present but that it serves an ultimately decorative purpose. In Scott's article, he provides an example of "how not to use the figure element" which is an HTML list of someone's favorite movies. In the example, a movie is represented by the following HTML:

<figure>
  <picture>
    <img src="fightclub.jpg" alt="" />
  </picture>
  <figcaption>Fight Club</figcaption>
</figure>

I think this is a pretty clear case where the cover could be serving a decorative purpose. As the W3C's Web Accessibility Initiative tutorial on informative images states, "Whether to treat an image as informative or decorative is a judgment that authors make, based on the reason for including the image on the page." If the reason for the cover was just another way to identify the movie, that purpose may already be handled by the figcaption element that includes the movie's title. Unless the author was trying to convey some other specific details about the movie cover, the cover is merely decorative.

Spoilers

Images can be wrapped in a spoiler which obscures the contained image and can be toggled with a click or space bar or enter. See the Spoiler Example for what this looks and acts like.

Spoiler Example

There has been some discussion about what accessibility properties and behaviors a spoiler element ought to exhibit.[1][2] While deciding how to implement spoilers in the garden, I settled on the following objectives:

  1. Do not reflow. I do not recall seeing this point being mentioned elsewhere, but it can often be important. Avoiding reflow reduces overall motion and avoids confusing situations after a refresh. Browsers will typically restore your scroll position after you refresh a page. However, anything that changes the position of page content is likely to not persist. This causes the user to end up at the wrong part of the page. Hence, I did not find <details> to be suitable.
  2. Be semantic. This includes an effort to be accessible for screen readers. In particular, I wanted to make sure that the spoiler was keyboard accessible in ways a user would not be too surprised by.
  3. Be simple. If it is complicated to use, then I am less likely to use it correctly. Simplicity also helps when someone else is trying to understand what's going on.
  4. Avoid JavaScript (if possible). I want to give noscript users as full of an experience as possible. It also means a more declarative style that can be easier to reason about.

I discovered a pure HTML/CSS strategy which leverages an invisible checkbox. It works really well for block content but struggles with inline content where it interferes with typical text selection behavior. For some reason, click to reveal causes the underlying text to be highlighted.

My previous strategy tried to leverage buttons with a little JavaScript. This proved to be a real pain in the butt and I was never able to get it working how I wanted. There does not appear to be a good answer for a generic interactive wrapper element. Ideally, when using JavaScript, we would have a button with a transparent content model (a la the anchor element). But for the time being, completely repurposing buttons is not possible.[3][4]

Every article contains a section after its primary content which provides a list of backlinks. As an added bonus, the backlinks are sorted according to approximate page rank (calculated as how many backlinks a page has). This design pattern is important enough that I have an article which covers some of the benefits of backlinks.

The footer of each page contains a few resources.

History

Every page has a link to the page's history. Specifically, it is a Git blame which makes it easy to determine when a particular change was made and why.

Example Citation

Every page has an example citation. Specifically, it can be used to provide credit to me when distributing or creating derivatives of my work.

  1. https://seirdy.one/posts/2023/11/12/spoiler-element/ ↩︎

  2. https://www.scottohara.me/blog/2024/08/22/spoiler.html ↩︎

  3. https://www.scottohara.me/blog/2018/10/03/unbutton-buttons.html ↩︎

  4. https://github.com/w3c/csswg-drafts/issues/3226 ↩︎

Backlinks