Markup patterns

Here are markup patterns I use on this site. You may also be interested in the site colophon and in the custom elements I use here.

Asides, examples, notes, and warnings
Carousels
Embeds
Feed-only content
Galleries
Grawlix
<hr> variants
Hero images
Inset text
Snug captions
Tombstones
Mentions
Names of works
Postnominals
Quotes
Slides
Stealth links

Asides, examples, notes, and warnings

<aside>
  <p>Something distinct from the main content…
</aside>

<aside class=example>
  <p>For instance, …
</aside>

<aside class=note>
  <p>What’s particularly interesting here is…
</aside>

<aside class=warning>
  <p>This page will self-destruct in 10 seconds.
</aside>

Instagram-style multiple-image carousels: the `tess-carousel` element

This custom element uses CSS Scroll Snap to do its thing. It even works with JavaScript disabled.

Making third party embeds behave: `div.embed-container`

Third party embeds often don’t behave well when dropped onto a page. I’ve found I can work around the vast majority of cases by sticking them in a flex container.

<div class=embed-container>
  … embed goes here …
</div>

Feed-only content: the `feed-only` class

Sometimes I post content that is unlikely to render in full fidelity or interactivity in feed readers. For instance, the colored table cells in this post. I put a warning in the post content that gets included by my Atom feed generator, which I display: none on my site.

<aside class=feed-only>
  <p>This post contains content that your feed reader may ignore.
</aside>

Grids of images: the `gallery` class

When I have a bunch of figures grouped together, I often want them to make a pretty grid of images in larger browser windows. I use a gallery class and a bunch of @media blocks plus CSS Grid to achieve this.

<section class=gallery>
  <figure>…</figure>
  <figure>…</figure>
  <figure>…</figure>
  <figure>…</figure>
</section>

Grawlix

I use a grawlix class on <em> or <strong> elements to mark up runs of grawlix:

<strong class=grawlix title=shit>+*@!</strong>

and I use the title attribute to communicate the meaning.

<em class=grawlix title=fucking>#*!$@+%</em>

`<hr>` variants: `hr.dinkus, hr.fleuron, hr[title]`

A dinkus is a series of three asterisks used as a section break. So I type <hr class=dinkus> and this is what comes out:

Sometimes I use a fleuron for a more stylized section break. Typing <hr class=fleuron> produces:

I’ve also made it possible to customize the text used for the separator with the title attribute. For instance, <hr title="⁂"> looks like this:

I used to use a dinkus for my default <hr> styling, but recently decided to embrace <hr>’s default styling. I think that’s a better fit for this site’s minimalist vibe.

Hero images

For the most part, I keep content constrained within a centered colum on the page, including images. They look like this:

A transformer on a sidewalk in San Francisco’s Mission District.
It’s been painted with a styleized depiction of a woman standing in front of the Lexington Club, an iconic lesbian bar that unfortunately closed several years ago. — The Lex

Sometimes I like to have “hero” images that are full-bleed. I mark them with a hero class, like so:

<figure class=hero>
  …
</figure>

They look like this:

Inset text

Sometimes I like to scoot the caption of an image up into the image itself, like I did for the image right above this section. To do this I mark the <figcaption> element with an inset class.

<figure>
  …
  <figcaption class=inset>…</figcaption>
</figure>

This works for any container of an inset, not just <figure> elements, thanks to the :has() selector:

:has(> .inset) {
    position: relative;
}
.inset {
    position: absolute;
    bottom: 0;
    right: 0;
    …
}

Snug captions

Sometimes I want figure captions to be much closer to the figure itself, and stylistically offset from the regular text. I use <figcaption class=snug> for this:

End of article tombstone: `.halmos`

I sometimes end articles with the U+220E ∎ END OF PROOF character. When I do so, I surround the character with an element that has class=halmos. Sometimes that’s just a span:

<span class=halmos>∎</span>

Sometimes I use the tombstone to carry the article’s permalink. In those cases, I use <a rel=bookmark>.

<a href="" class=halmos rel=bookmark>∎</span>

Mentions: `a.mention`

This is how I at-mention a user from some other site:

<a href=https://cohost.org/hober class=mention>hober</a>

I prepend an at sign to mentions by default with a ::before pseudo-element: hober. Depending on the site, however, I sometimes style mentions in more interesting ways. Here are some examples:

cohost usernames look like jkap. Note that there’s a <span> inside the <a> element for these because I don’t know how to get the blending to work otherwise. One of these days I’ll make smfr or dino explain this shit to me.
Instagram usernames look like hober
LinkedIn usernames look like hober
LiveJournal usernames get rendered like bradfitz
reddit usernames look like aaronsw
Wikipedia usernames look like TessOConnor

I wonder if it would be better to use XFN’s rel=contact instead of class=mention. I asked tantek.

Names of works

The HTML spec says to use the <cite> element for the names of works.

Conventionally, in English, some titles get italicized (e.g. Nevada by Imogen Binnie), while some get surrounded by quotes (e.g. Don’t Hesitate, by Mary Oliver, in Devotions), but the <cite> element italicizes all of them by default.

So I use various classes to distinguish the various types, and key styling off of them:

<cite class=album>Aztlán</cite>, by Zoé
<cite class=article>Consequences of Undecidability in Physics on the Theory of Everything</cite>, Drs. Mir Faizal, Lawrence M. Krauss, Arshid Shabir, and Francesco Marino, published in the Journal of Holography Applications in Physics
<cite class=artwork>The Scream</cite>, by Edvard Munch
<cite class=book>Nevada</cite>, by Imogen Binnie
<cite class=court-case>Obergefell v. Hodges</cite> 576 U.S. 644 (2015)
<cite class=journal>Journal of Holography Applications in Physics</cite>
<cite class=magazine>The New Yorker</cite>
<cite class=poem>Don’t Hesitate</cite>, by Mary Oliver
<cite class=song>Trampoline</cite>, by SHAED

Postnominals: `abbr.postnominal`

Fr. Daniel Berrigan, SJ is written like so: <abbr title=Father>Fr.</abbr> <a href=https://danielberrigan.org/>Daniel Berrigan</a>, <a href=https://en.wikipedia.org/wiki/Jesuits><abbr title="Society of Jesus" class=postnominal>SJ</abbr></a>

Quotes with attribution: `figure > blockquote`

<figure>
  <blockquote cite=https://en.wikipedia.org/wiki/Occam's_razor lang=la>
    <p>Entia non sunt multiplicanda praeter necessitatem.
  </blockquote>
  <figcaption>— <a href=https://en.wikipedia.org/wiki/Occam's_razor>William of Ockham</a></figcaption>
</figure>

These days, I only use the <cite> element in the <figcaption> when the thing being quoted is a work, per the specified semantics of <cite>:

<figure>
  <blockquote cite=https://en.wikipedia.org/wiki/Moby-Dick>
    <p>Call me Ishmael.
  </blockquote>
  <figcaption>— <a href=https://en.wikipedia.org/wiki/Moby-Dick><cite>Moby-Dick</cite></a></figcaption>
</figure>

But I’m sure there’s a bunch of legacy content on this site that uses <cite> more liberally, as was the custom before Ian wrote the modern HTML spec.

Slide decks: `article.deck`

When I mark up slides I use an <article> element for the deck itself and <section> children to represent each slide. I mark the current slide with the aria-current attribute.

<article class=deck>
  <section>slide one</section>
  <section aria-current=true>slide two is the current slide</section>
  …
  <section>slide N</section>
</article>

Stealth links: `a.stealth`

Sometimes I want a link to just look like regular text. This class does that. The link still works—you can click on it, and AT announces it to users—it just doesn’t look like a link visually. The first AT in this paragraph is such a link.

Theresa O’Connor / Treasa Ní Chonchúir

Markup patterns

Table of Contents

Asides, examples, notes, and warnings

Instagram-style multiple-image carousels: the `tess-carousel` element

Making third party embeds behave: `div.embed-container`

Feed-only content: the `feed-only` class

Grids of images: the `gallery` class

Grawlix

`<hr>` variants: `hr.dinkus, hr.fleuron, hr[title]`

Hero images

Inset text

Snug captions

End of article tombstone: `.halmos`

Mentions: `a.mention`

Names of works

Postnominals: `abbr.postnominal`

Quotes with attribution: `figure > blockquote`

Slide decks: `article.deck`

Stealth links: `a.stealth`

Markup patterns

Table of Contents

Asides, examples, notes, and warnings

Instagram-style multiple-image carousels: the tess-carousel element

Making third party embeds behave: div.embed-container

Feed-only content: the feed-only class

Grids of images: the gallery class

Grawlix

<hr> variants: hr.dinkus, hr.fleuron, hr[title]

Hero images

Inset text

Snug captions

End of article tombstone: .halmos

Mentions: a.mention

Names of works

Postnominals: abbr.postnominal

Quotes with attribution: figure > blockquote

Slide decks: article.deck

Stealth links: a.stealth

Instagram-style multiple-image carousels: the `tess-carousel` element

Making third party embeds behave: `div.embed-container`

Feed-only content: the `feed-only` class

Grids of images: the `gallery` class

`<hr>` variants: `hr.dinkus, hr.fleuron, hr[title]`

End of article tombstone: `.halmos`

Mentions: `a.mention`

Postnominals: `abbr.postnominal`

Quotes with attribution: `figure > blockquote`

Slide decks: `article.deck`

Stealth links: `a.stealth`