Simplequiz #7: Pinterest

by .

One of our readers commented on an article a while ago (I won’t tell you which one just now ;) asking about marking up items on Pinterest. It struck me that this would be a prime candidate for a Simplequiz, so here we are.

Pinterest, for the uninitiated of you, allows you to organise and share things you love — mostly food, drink, and kittens.

Pinterest Homepage Screengrab
A distinct lack of kittens on Pinterest’s homepage in this screengrab

We’re going to look at how to mark up a single pinned item, as shown below:

Individual pinned item on PinterestIndividual pinned item on Pinterest
The item we’ll be marking up (bottom image is the hovered state)

The existing markup is below (I’ve simplified it a little to make it easier to read):

<div class="pin">
  <div class="pin-holder">
    <div class="actions">
      <a href="#repin">Repin</a>
      <a href="#like">Like</a>
      <a href="#comment">Comment</a>
    </div>
    <a href="me/cat/">
      <img src="cat.jpg" alt="My awesome cat">
    </a>
  </div>
  <p>Awesome cat description.</p>
  <p class="stats">
    <span>25 likes</span>
    <span>2 comments</span>
    <span>100 repins</span>
  </p>
  <div class="convo">
    <a href="/me/">
      <img src="me.jpg" alt="Profile picture of me">
    </a>
    <p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
  </div>
</div>

So, all’s well and good, but how should it be marked up in HTML5? As the saying goes, there are a hundred ways to skin a cat (excuse the pun). We’ve created five possible options, one of which achieved some consensus amongst the Doctors. Be warned: some of the differences between options are small and may be difficult to spot. Look carefully at each option!

Let us know which answer you would go with (or roll your own) in the comments. Make sure you show your working out. Also, please escape your HTML (or use pseudo code), or we’ll put a severed unicorn head skinned cat in your bed.

Answer A:

An <article>, with <nav> and <aside> elements:

<article class="pin">
  <div class="pin-holder">
    <nav class="actions">
      <a href="#repin">Repin</a>
      <a href="#like">Like</a>
      <a href="#comment">Comment</a>
    </nav>
    <a href="me/cat/">
      <img src="cat.jpg" alt="My awesome cat">
    </a>
  </div>
  <p>Awesome cat description.</p>
  <aside class="stats">
    <span>25 likes</span>
    <span>2 comments</span>
    <span>100 repins</span>
  </aside>
  <article class="convo">
    <a href="/me/">
      <img src="me.jpg" alt="Profile picture of me">
    </a>
    <p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
  </article>
</article>

Answer B:

An <article>, with <aside> elements:

<article class="pin">
  <div class="pin-holder">
    <aside class="actions">
      <a href="#repin">Repin</a>
      <a href="#like">Like</a>
      <a href="#comment">Comment</a>
    </aside>
    <a href="me/cat/">
      <img src="cat.jpg" alt="My awesome cat">
    </a>
  </div>
  <p>Awesome cat description.</p>
  <aside class="stats">
    <span>25 likes</span>
    <span>2 comments</span>
    <span>100 repins</span>
  </aside>
  <article class="convo">
    <a href="/me/">
      <img src="me.jpg" alt="Profile picture of me">
    </a>
    <p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
  </article>
</article>

Answer C:

An <article>, with <nav>, <figure>, and <aside> elements:

<article class="pin">
  <div class="pin-holder">
    <nav class="actions">
      <a href="#repin">Repin</a>
      <a href="#like">Like</a>
      <a href="#comment">Comment</a>
    </nav>
    <figure>
      <a href="me/cat/">
        <img src="cat.jpg" alt="My awesome cat">
        <figcaption>Awesome cat description.</figcaption>
      </a>
    </figure>
  </div>
  <aside class="stats">
    <span>25 likes</span>
    <span>2 comments</span>
    <span>100 repins</span>
  </aside>
  <article class="convo">
    <a href="/me/">
      <img src="me.jpg" alt="Profile picture of me">
    </a>
    <p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
  </article>
</article>

Answer D:

A <section>, with <aside> and <figure> elements:

<section class="pin">
  <div class="pin-holder">
    <aside class="actions">
      <a href="#repin">Repin</a>
      <a href="#like">Like</a>
      <a href="#comment">Comment</a>
    </aside>
    <figure>
      <a href="me/cat/">
        <img src="cat.jpg" alt="My awesome cat">
        <figcaption>Awesome cat description.</figcaption>
      </a>
    </figure>
  </div>
  <p class="stats">
    <span>25 likes</span>
    <span>2 comments</span>
    <span>100 repins</span>
  </p>
  <div class="convo">
    <a href="/me/">
      <img src="me.jpg" alt="Profile picture of me">
    </a>
    <p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
  </div>
</section>

Answer E:

A <div>, with child <article> and <aside> elements:

<div class="pin">
  <article class="pin-holder">
    <aside class="actions">
      <a href="#repin">Repin</a>
      <a href="#like">Like</a>
      <a href="#comment">Comment</a>
    </aside>
    <a href="me/cat/">
      <img src="cat.jpg" alt="My awesome cat">
      <p>Awesome cat description.</p>
    </a>
  </article>
  <aside class="stats">
    <span>25 likes</span>
    <span>2 comments</span>
    <span>100 repins</span>
  </aside>
  <div class="convo">
    <a href="/me/">
      <img src="me.jpg" alt="Profile picture of me">
    </a>
    <p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
  </div>
</div>

Your answers below, please, with your rationale, by Tuesday, 29th January.

64 Responses on the article “Simplequiz #7: Pinterest”

Sara Soueidan says

Just scanning the options quickly, I would go with answer C.

Colin Robson says

I’d go with ‘D’, an article to me, represents the page, and sections represent parts of the article. Although you can have many ‘article’s actually within a page it makes more semantic sense (to me) to use ‘sections’ of a page

Giuseppe Gurgone says

I’d definitely pick the last one (E) with some changes:

1. Use the figure element
2. Place the .actions aside after the figure
3 Maybe the .convo could be a footer ?

Anders Fisher says

I’d go for D as it’s clearly a section within the context of a search as opposed to a stand alone article, and the image with caption is a clear use cae of figure and figcaption!

Richard says

I’m thinking C. Can a pin exist alone or be syndicated? A tweet can, and by the same logic a pin can. Hence it’s an article.

Figure is clear. The Nav refers to options for that content and seems OK, and the aside seems sensible.

Matthew Somerville says

My thought process, from the spec – a pin is an independent item of content that could be syndicated, so article preferred to section, so not D. I don’t think figure is appropriate, because it’s for things that can be taken out of flow and moved to an appendix, and the pins on the page are the whole point of the flow. So not C. nav says it’s for major navigation, so not A. aside is for things that can be considered separate from the main content – not true here, where the nav/stats only make sense within that context, so not A, B, or, oh, E. I’m out :) Perhaps an article just containing divs?

Brian Dukes says

I don’t think the actions should be <nav>, since they don’t take you anywhere, so that eliminates A & C. Using the figure to associate the caption with the image feels right, so I want to lean towards D. However, it certainly seems that Pinterest would consider each pinned item a standalone piece of content, which makes me want to wrap it in an <article>, rather than a <section>. I like <aside> for the actions and stats. Maybe I’m misunderstanding the “convo” section, but it seems like metadata (<footer>?), rather than anything that should be an <article> (based on the class name, I’d think there might be comments, which could be <article>s, but what I’m seeing doesn’t look like comments). So, that leaves me with something like this:


<article class="pin">
<div class="pin-holder">
<aside class="actions">
<a href="#repin">Repin</a>
<a href="#like">Like</a>
<a href="#comment">Comment</a>
</aside>
<figure>
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat">
<figcaption>Awesome cat description.</figcaption>
</a>
</figure>
</div>
<aside class="stats">
<span>25 likes</span>
<span>2 comments</span>
<span>100 repins</span>
</aside>
<div class="convo">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</div>
</article>

Richard says

Yeah. The Nav on C seems weird. I think figure seems OK as they could be put on their own with the caption and still make sense.

Convo does look like a footer.

The person above looks like what I’d do.

Jeremy Keith says

What Matthew Somerville said.

Fabrizio Calderan says

I agree too with Matthew Somerville for the same exact reason.

Pete says

Each individual “pin” is clearly a self-contained composition so an <article> is entirely appropriate as the main wrapper.

Leaving the “actions” segment as just an unordered list of links would mean semantically that this is content, which clearly isn’t the case. It does not contain links to other content (i.e. this isn’t navigation) so I would argue that a <nav> element isn’t the right way to go. <header> seems more fit for our purposes since this is supposed to be used to represent “introductory or navigational aids”.

<figure>s are intended to contain accessory content, not the main substance of the section in question. The spec says they can be moved away from the main flow of the document without affecting the document’s meaning. I therefore don’t think it’s appropriate to use them for the main image and description here. This is the meat of our <article> (i.e. this is our actual content) so doesn’t need a special wrapper.

The “stats” area doesn’t contain related content (related content would be a list of similar images or something) so an <aside> isn’t quite right here. According to the spec a <footer> contains “information about its section” so going with that is more appropriate.

The “convo” portion is just standard comments functionality, so the convo wrapper should be a <section> and each individual comment should be wrapped in an <article> tag.

Taking out the unnecessary <div>s for clarity leaves us with this:

<article class="pin">
    <header class="actions">
        <a href="#repin">Repin</a>
        <a href="#like">Like</a>
        <a href="#comment">Comment</a>
    </header>
    <a href="me/cat/">
        <img src="cat.jpg" alt="My awesome cat">
    </a>
    <p>Awesome cat description.</p>
    <footer class="stats">
        <span>25 likes</span>
        <span>2 comments</span>
        <span>100 repins</span>
    </footer>
    <section class="convo">
        <article>
            <a href="/me/">
                <img src="me.jpg" alt="Profile picture of me">
            </a>
            <p><a href="/me/">Me</a> onto <ahref="/here/">here</a></p>
        <article>
    </section>
</article>

Alejandro Moreno says

Taking Matthew Somerville’s comments into account, I put together the sample solution. But I put the comments on a footer.


<article class="pin">
<div class="pin-holder">
<div class="actions">
<a href="#repin">Repin</a>
<a href="#like">Like</a>
<a href="#comment">Comment</a>
</div>
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat">
</a>
</div>
<p>Awesome cat description.</p>
<div class="stats">
<span>25 likes</span>
<span>2 comments</span>
<span>100 repins</span>
</div>
<footer class="convo">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</footer>
</article>

Alejandro Moreno says

Curses. I missed out on Pete’s reply.

I really like Header for mini-navigation.

Disagree on Footer for the stats.

But again, Section-Article for the comments makes a lot of sense.

Pete says

@Alejandro – I think we agree that the stats wrapper doesn’t contain actual content; this is meta data. Therefore it needs a descriptive wrapper to distinguish it from the content. The question is: which element do we use?

<aside> is very clearly meant to be used for tangentally related content. The stats are not “related” or “slightly connected” to our content, they directly describe it so I would argue that according to the specs <aside> is appropriate.

To quote html5doctor “The footer element typically contains metadata about its enclosing section” which seems to me to be bang on the money.

Pete says

Sorry, I meant aside is “inappropriate”.

Evan Mullins says

Yes, I think we’ve come to something much stronger than the initial 5 choices.

I think footer for the stats makes sense, especially if we’re putting the .actions into a header. I know neither are required but it gives a sense to me that this is the whole entity.

Emigdio Gutierrez says

Answer C seems best to me. Though I think the point is, there are many ways to interpret what is semantically correct.

Luke Padgett says

What is being pinned? The picture and it’s description. Everything else relates to those and don’t really stand on their own. The picture is the article. Links at the top are all commands for actions, not necessarily places to go which fits a menu. The bottom is information about the author which describes a footer. The stats are an aside to what actions have been performed on the picture. So to me it would be:


<article class="pin">
<div class="pin-holder">
<menu class="actions">
<a href="#repin">Repin</a>
<a href="#like">Like</a>
<a href="#comment">Comment</a>
</menu>
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat">
</a>
</div>
<p>Awesome cat description.</p>
<aside class="stats">
<span>25 likes</span>
<span>2 comments</span>
<span>100 repins</span>
</aside>
<footer class="convo">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me">Me</a> onto <a href="/here/">here</a></p>
</footer>
</article>

frappacanu says

Luke Padgett has a point introducing the menu tag into the markup, cause nav would not be appropriate. the element with class=”convo” is imho the footer of the article.
if there are comments or the comment form is shown, i would include another section.

this would be my markup:


<article class="pin">
<section class="pin-holder">
<menu class="actions">
<a href="#repin">Repin</a>
<a href="#like">Like</a>
<a href="#comment">Comment</a>
</menu>
<figure>
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat">
</a>
<figcaption>Awesome cat description.</figcaption>
</figure>
</section>
<aside class="stats">
<span>25 likes</span>
<span>2 comments</span>
<span>100 repins</span>
</aside>
<footer class="convo">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me">Me</a> onto <a href="/here/">here</a></p>
</footer>
</article>

Jasper Rijkeboer says

[edit: sorry for the spam, I'm a newbie here]

I would combine answer C with some of the great comments here. Note that the greyed section can also have child boxes with comments (there’s one added in my example below).

As a Pinterest user I can experience a pin as an actual discernable item and i therfore use the <article> tag to define it as such.
As a pin is the sum of the actual image and the pinner’s personal comment, i would group these together in a <section>. It is on this part of the article that I want run an action. As the actions are not on a different page or in a hierarchy i would elect to use the <menu> tag and not a <nav> tag for these.
As for the stats, they are seemingly related to the figure, yet they are in actual fact related to the pin are therefore outside of this section.
Lastly, the attribution and comments are footnotes to the actual pin and are therefore contained within a <footer>.
But as the attribution and the comments are related to the actual pin each is also contained in an <aside> rather than a <div>.

I was uncertain on the comments though, and I used a data* attribute to uniquely identify a comment.


<article class="pin">
<section class="pin-holder">
<menu class="actions">
<a href="#repin">Repin</a>
<a href="#like">Like</a>
<a href="#comment">Comment</a>
</menu>
<figure>
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat" />
<figcaption>Awesome cat description.</figcaption>
</a>
</figure>
</section>
<aside class="stats">
<span>25 likes</span>
<span>1 comments</span>
<span>100 repins</span>
</aside>
<footer class="convo">
<aside class="attribution">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</aside>
<aside class="comments">
<div data-comment-id="42">
<a href="/user_name/">
<img src="/avatars/user_name_1337.jpg" alt="Profile picture of User Name">
</a>
<p><a href="/user_name/">User Name</a> this pin is cool!</p>
</div>
</aside>
</footer>
</article>

Sara Soueidan says

OK I’m convinced, its not C because of the nav tag on the actions buttons.

Luke Padgett says

Can someone advocating the usage of figure & figcaption, particularly someone who thinks it is clear/obvious, explain their reasoning for me? I’m with Pete, I don’t see how you can remove the picture and description while maintaining meaning. I’m still learning this so if I’m missing something I want to know.

The figure element represents a unit of content, optionally with a caption, that is self-contained, that is typically referenced as a single unit from the main flow of the document, and that can be moved away from the main flow of the document without affecting the document’s meaning.
W3C Specification

Emphasis mine. If you were to use figure & figcaption could you really move it to an appendix or another page without affecting the meaning of the article? Both the stats & convo sections would really have no meaning if you were to do so.

Jasper Rijkeboer says

@Luke Padgett: you’re right about the <figure>.

The image and the comment are the essence of the article after all should be placed in their section as first level assets.

On second thought I would remove the <figure> and replace <figcaption> with a simple <p>.

Pete Schuster says

I agree with Jeremy Keith

Brian Dukes says

I had liked the inclusion of <figure> to link the caption to the image, but had forgotten that it is for non-essential content. So, I think it’s become clear that it’s not a good choice here.

Alohci says

I’d just like to point out that C and D are invalid.’ figcaption’ must be first or last direct child of ‘figure’; it cannot have an ‘a’ element in between. The ‘a’ element should wrap the ‘figure’ element.

kevinTelluLater says

Luke Padgett skinned the cat. Many great solutions here but I do agree w/ Luke and Pete.

Justin says

Can we not put the stats into a list? Aren’t they just a list of stats?

If that’s information about the pin why not put that inside of the footer along with the .convo?


<article class="pin">
<div class="pin-holder">
<div class="actions">
<a href="#repin">Repin</a>
<a href="#like">Like</a>
<a href="#comment">Comment</a>
</div>
<a href="me/cat/"><img src="cat.jpg" alt="My awesome cat"></a>
</div>
<p>Awesome cat description.</p>
<footer>
<ul class="stats">
<li>25 likes</li>
<li>2 comments</li>
<li>100 repins</li>
</ul>
<div class="convo">
<a href="/me/"><img src="me.jpg" alt="Profile picture of me"></a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</div>
</footer>
</article>

steve faulkner says

Statements in regards to use of the the figure element in these comments has lead me to believe the current definition of the figure element in HTML is incorrect and should be changed:
current definition of in HTML is problematic.

Michael[tm] Smith says

I think it’s possible that too much is being read into that “can be moved away from the main flow of the document without affecting the document’s meaning” phrase in the spec. At least I think some readers may not be reading the spec critically enough and maybe are just accepting that there’s this restriction, but without questioning at all whether having such a restriction would even be a good idea.

This is an element that’s basically just intended for enabling you to associate a caption with an image, right? So pretend for a minute that additional phrase isn’t there in the spec at all — or even, that the element is not yet defined in the spec — and you’re the one designing the language and defining the element. Ask yourself what sense would it make to design the language such that you restrict your associate-a-caption-with-an-image element to only being allowed for associating captions with images that are “accessory content” (or however else it’s been described in other comments).

Who knows, maybe there really would be some really good reason for only using an associate-a-caption-with-an-image element for accessory content. But if there is, I sure can’t think of one. So unless you believe that there’s some really good reason for having such a restriction, I would think you ought to be considering that language in the spec to be a bug that needs to be fixed, as Steve noted http://html5doctor.com/html5-simplequiz-7-pinterest/#comment-30459

Alohci says

Steve and Michael – I’ve always taken that phrase to intentionally have the effect of discouraging figure for the main content. The reason, I believe, is that “figure” on a web page, is directly analogous to a figure in printed book, i.e. a diagram or inset that helps to understand the main content but can be independently positioned to suit the limitations of layout on a printed page.

This is consistent with the way <b> and <i> are defined in HTML5 in terms of standard typographic conventions.

It shouldn’t be necessary to use figure when the image is the main content, because all the text on the page is automatically it’s caption.

steve faulkner says

@Alohci

It shouldn’t be necessary to use figure when the image is the main content, because all the text on the page is automatically it’s caption.

I don’t consider this to be a useful way to view it, for example in the flickr use case the image is clearly the key part of the content (otherwise the page would not be there) and image clearly has a caption.

In terms of how figure/figcaption are mapped in the accessibility layer, they provide a method to associate a caption with ,often an image.

Associating all the content on the page is as if it’s the caption is not useful, but associating that bit of content under the image is.

Also it should be noted that use of figure/figcaption is the ONLY conforming method to include an image in a page without an alt attribute, and is allowed for photo site use cases.

Fireh says

I think the key here is that the <figure> can be referenced later like you would reference a table for its data.
I think of it as a loaded version of <img>.

icaaq says

IMHO the source order is kind of messed up and I think it can be simplified. this is my suggestion:


<article class="pin">
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat">
</a>
<p>Awesome cat description.</p>
<p>
<span class="visually-hidden">This pintrest has </span>
<span>25 likes </span>
<span>2 comments </span>
<span>100 repins </span>
</p>
<p><span class="visually-hidden">Would you like to </span>
<ul>
<li><a href="#repin">Repin <span class="visually-hidden">My awesome cat</span></a></li>
<li><a href="#like">Like <span class="visually-hidden">My awesome cat</span></a></li>
<li><a href="#comment">Comment <span class="visually-hidden">on My awesome cat</span></a></li>
</ul>
</p>
<aside class="convo">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</aside>
</article>

Shea Bunge says

I would go with Answer C, as <nav> seems like the right way to markup the action links. The actual block seems more of an < article> then a <section>, as they are shown in an order and submitted chronologically. The stats and author pic seem like content related to the actual image, but not directly related as the action element are. Finally, the picture and caption should be marked up as <figure> and <figcaption> elements because that’s how you do it in HTML5.

Stefan says

A rough translation of my answer (posted in German) on my blog):

I’d use none of the given answers.

A/B/C uses article for .convo, probably because it is displayed similar to following repins/comments. But the first entry in .convo is not the “first repin” (maybe technically, but it’s about the meaning here) but the authorship and category info. So using article here is not correct (otherwise you’d use a separate article element for the authorship info of a blogpost, too).

C/D uses figure+figcaption for the main content. But this use is not in compliance with the specification. figure requires two things: the content has to be self-contained (it’s the case here) and it is typically referenced as a single unit from the main flow of the document (it’s not the case). One could argue that typically could mean that other uses might be allowed, too. But I guess it’s clear where the definition is heading to. See the following sentence in the spec:

The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc, that are referred to from the main content of the document, but that could, without affecting the flow of the document, be moved away from that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix.

Let’s think of the Pinterest homepage, where the most popular pins might be listed, or think of a detail page where only one pin is shown … you can’t remove the figure without affecting the flow of the document, and the content isn’t referred to from the main content because, well, it is the main content.

D uses section instead of article. Why? A pin perfectly matches every aspect of article in the spec. A section wouldn’t be wrong, but article fits perfectly and is more specific.

E uses div instead of a sectioning element as container. While this wouldn’t be incorrect per se, it results in a document outline error. The aside containing the statistics isn’t part of the included article element. Therefor the aside is related to the whole document (resp. the next parenting sectioning element) instead of the article resp. the div. So it is lost (for the document outline and the sectioning) to which pin the statistics applies.

Now to my answer. As the first step I discuss the usage of sectioning elements (section, article, aside, and nav) and how to “get” the main content by marking-up metadata (address, footer, and header). The second part is about how to markup the actual content and details. At the end I include the whole code.

Part 1: sectioning

Let’s see what the structure of such a pin is:

· image and description (→ main content)
· statistics
· author avatar/name, source (not in the example), category
· comments/repins (not in the example)
· actions

1.1: container

I think it’s clear that we need a sectioning element as container for the whole pin. Possible would be article or section. I think the article element is the right choice here: each post is a self-contained composition and in principle, independently distributable or reusable, e.g. in syndication; it has (or could have) an own author, an own URL, a publication date etc.

1.2: main content

The main content of the article consists of the image and the description. It doesn’t need any markup. Everything else needs to be in its own sectioning element or marked-up with address, footer, or header.

1.3: statistics

The statistics are metadata to the article (resp. the main content). We have two choices here: aside or footer. A footer typically contains information about its section, an aside contains content that is tangentially related to the content around the aside element, and which could be considered separate from that content. The main difference: aside is a sectioning element, so it creates an entry for the document outline. I think the footer element is appropriate here, because statistics are more than just tangentially related.

1.4: author

The avatar and the paragraph about the author/category should be placed in a footer. The spec is pretty clear about it: typically contains information about its section such as who wrote it […].

One might want to include the paragraph in an address element, because it contains the link to the user’s profile, which could be seen as a way to contact the user. However, two problems: the paragraph contains more than the profile link (e.g. the category), but address must not contain information other than contact information. Also, at least for guests, there is no way to contact a user via the profile (so at most they could add an address element only for logged-in users, if they provide a contact form for them).

1.5: comments

They are missing in this example, therefor I don’t include the markup in my answer. But in general: each comment and repin should be enclosed in its own article element. As already noted, the “first” thing looking like a repin isn’t a repin but the author metadata of the pin. See → 1.4.

1.6: actions

For the three actions the following elements might be possible: aside, menu (in aside or footer), or nav. I think the header element is not an option, because these actions hardly count as introductory or navigational aids.

nav and aside are both sectioning elements. Which one of those two would I choose? It depends on the question: Do these actions link to a certain part of the page resp. to a different page? If yes, then I’d go with nav. Btw: the often quoted for sections that consist of major navigation blocks is just a Note, and therefor not normative. However, if these actions would be classical links, I’d consider them the major navigation for that article, too. However, I don’t think that the answer to the question would be yes (I only assume here, because I never used Pinterest). “Like” sounds to me like an instant action, not loading a new page or jumping to a part of the current page. It fires and you are done. So it’s more like a button than a link. “Comment” would probably be a link suitable for nav, while “Repin” is probably somewhere inbetween. I wouldn’t want to separate the three actions, though.

So, what about the menu element? The definition represents a list of commands sounds good for our case here. We don’t need a context menu or a toolbar, so we could go with the default (list) type (so I don’t think we’d run into any serious browser compatibility issues; however, for this quiz browser issues aren’t relevant anyway). To “exclude” this from the main content, we’d need to enclose the menu in an aside element (some might use a footer for that, but I think these kind of links are not good candidates for a footer, as they are in no way about the section).

Part 2: details

I removed the div with the class pin-holder. It’s not relevant for the markup. If needed as CSS/JS hook, simply add it back.

Each of the three action links (inside of menu) should go into a li element.

The statistics (p with class stats) are no “paragraph” (a run of phrasing content that forms a block of text with one or more sentences that discuss a particular topic). Use a div instead. Also, instead of using span for each statistic rather use div, too. Otherwise users of textbrowsers etc. would see one line of text without separators: “25 likes 2 comments 100 repins”. Instead of using a div with span elements, a ul would also be possible here.

The image is linked with the detail page of that pin. Therefor we should use the link type bookmark.

The avatar and the author name are linked to the user profile page. Therefor we should use the link type author. This is possible because we used article as sectioning element. Otherwise the authorship link type would apply to the whole document.

Part 3: my answer (code)


<article class="pin">

<aside>
<menu class="actions">
<li><a href="#repin">Repin</a></li>
<li><a href="#like">Like</a></li>
<li><a href="#comment">Comment</a></li>
</menu>
</aside>

<a href="me/cat/" rel="bookmark">
<img src="cat.jpg" alt="My awesome cat">
</a>

<p>Awesome cat description.</p>

<footer>

<ul class="stats">
<li>25 likes</li>
<li>2 comments</li>
<li>100 repins</li>
</ul>

<div class="convo">
<a href="/me/" rel="author">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/" rel="author">Me</a> onto <a href="/here/">here</a></p>
</div>

</footer>

</article>

If the markup order can also be changed, I’d place the main content (img and p) at the top, followed by the aside, followed by the footer (followed by comments).

bruce says

There seems to be a lot of confusion about how to use <figure>. It’s not *only* for things that can be taken out of the flow; the spec says “can thus be used” not “must only be used”.

The only normative part of the spec (a horrible standardsese word that means “considered to be a prescriptive part of the standard”) is the bit that says “The figure element represents some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document.”

I’ve written to the Working Group today to suggest sublty tweaking the wording and, more importanly, giving some visual emphasis on the normative advice to distinguish it from that which explains or glosses it, but which isn’t normative.

Dillon says

I would wrap the whole thing inside an <article> element for sure, considering repinning is some form of syndication.

This is what the spec sais about the <nav> element: The nav element represents a section of a page that links to other pages or to parts within the page. Even though the actions are <a> elements, they aren’t linking to anything, they are actions. That’s why I don’t think they should be inside a <nav> element.

I wouldn’t use <aside> either, as I consider it as content related to, but not part of the main content. But I’m in doubt about that one.

All that said, I would use something like this:

<article class="pin">
<div class="actions">
<a href="#repin">Repin</a>
<a href="#like">Like</a>
<a href="#comment">Comment</a>
</div>
<figure class="pin-holder">
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat"/>
</a>
<figcaption>Awesome cat description.</figcaption>
</figure>
<footer>
<div class="stats">
<span>25 likes</span>
<span>2 comments</span>
<span>100 repins</span>
</div>
<div class="attribution">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</div>
<section class="comments">
<article class="comment">...</article>
</section>
</footer>
</article>

About using the <figure> element “out of spec”, Bruce said:

I think that the definition of <figure> will be used to caption such content. and that the spec should be clarified and widened slightly to allow this.

And I’m going with that.

Also, I’ve included the comments section (not in the answers), containing each comment as an <article> as this is a pattern w3 is using in an example about articles.

Off-topic: There are some misplaced </p> tags in the figure elements on this page. ;)

Alohci says

@Bruce – “The element may also be used ..” In addition to what, exactly?

I think we understand the word “can” perfectly well. The sentence is providing the use cases for the figure. It’s not intended to be exclusively those use cases, the spec never (as far as I know) says that the listed use cases are the only ones in the description of any element, but if as an author it flags to me that if my usage is not one of the listed use cases, I should consider whether another element is more appropriate.

The key word in the normative text in this instance is “referenced”. Once a figure is referenced, it can be moved at will. “typically referenced” indicates that it is not mandatory, but the spec provides little information about situations where it wouldn’t be referenced. It is that text and situation that needs clarification.

One other small point to bear in mind; the figure element can contain flow content, not just images, so it is important that wrapping main content in a figure element doesn’t have the effect of accidentally cutting off headings from the document outline because the figure element is a sectioning root, and any contained headings will not appear in that outline.

steve faulkner says

@Alohci

The question I keep asking myself and keep drawing a blank is:

What benefit does constraining the use of figure/legend as intepreted do? What benefit is it to users who actually consume the semantics?

The HTML spec is not set in stone it can and suggest should and will be changed in this case unless good reasons can be found not to do so.

Alohci says

@Steve

That’s a very good question indeed. And let me say up front that I don’t know the answer.

What I do know is that for semantics to have any opportunity to work, they must be writeable as well as readable. Which means that many, many authors must find them easy to use in a consistent fashion such that the semantics of the element are reasonably dependable on real world web pages. It is my assertion that perhaps of all the new elements, figure is, in its current incarnation, one of the easiest elements to understand.

To any who asks “When do I use <figure>?” the answer is easy. Open a text book, turn to the page with the table of figures, select a page from that, and inspect. There. That’s what a figure is. If you’d do that in a book, do it in a web page. (The equivalent process works well for tables too.)

I’m not trying to stop the HTML5 spec from changing. Clarifications and improvements are always welcome. What I am requesting, please, is that when you change the spec in the way I believe you want to, that the result answers clearly and unambiguously two questions.

1. How can an element that is “typically referenced as a single unit from the main flow of the document” be the primary and potentially only constituent of that main flow?

2. What is the use case for having a figure as the key content?

Is that reasonable?

steve faulkner says

Hi Alohci

Note the suggested change is not a normative change, it is informative. It, if changed would advise nothing more than is already advised in other parts of the spec in respect to use of figure figcaption. For example have a look at their usage in 4.8.1.1.10 A key part of the content.

In relation to teachability of their use, I would suggest that “the elements can be used to markup an image or other content whenever it has a caption”, is about as simple as it gets, the complexity occurs when we start to try to explain the more esoteric advice (not requirements) in the spec.

Alohci says

Hi Steve

This markup is a conforming HTML5 fragment:


<figure>
<h1>My Life</h1>
<p>I was born in the wagon of a travelling show ...</p>
</figure>

What is the meaning of the figure element when it doesn’t contain a figcaption? Or alternatively, why is the above fragment conforming?

steve faulkner says

Hi Alohci,

Depends on what you mean by “meaning” in practical terms figure maps to the group role in accessibility APIs. If it has no associated figcaption its a figure without an accessible name.

What is the author intent in the example? What we know is that the h1 won’t appear in the document outline, but that is a theoretical concern. Is that the authors intent? At worst in practical terms the use in this case is crufty.

Alohci says

Hi Steve

Thanks. (For the moment forget about the headings. That’s just an unnecessary complicating factor).

“At worst in practical terms the use in this case is crufty.” Right, that’s what I’m trying to find out. If the definition of a figure element is marking up flow content whenever it has a caption, is there any usage of the figure element without a figcaption which isn’t crufty? And if there isn’t, why does HTML5 permit it?

BTW, “Meaning” as in Semantics, i.e. the higher level concept that applies to markup elements, which can be interpreted by browsers to expose to the accessibility API, and interpreted by other tools for other purposes. For example, in this case, maybe to extract from the web site a table of figures.

    Richard Clark says

    Wow, thanks for all the comments and discussion everyone!

    As mentioned in the original post, someone commented on HTML5 Doctor asking how items should be marked up on Pinterest. Johan’s comment was in fact on our Figure & Figcaption article, so it’s interesting that we should stray into that discussion here as well. For what it’s worth, I agree that the wording of the spec should be amended along the lines that Steve and Bruce have suggested on the public-html mailing list.

    As many of you have pointed out, none of the options we provided are entirely correct. Hat tip to Matthew Somerville for first spotting it. I thought the debate would be more interesting, and wanted to see what you all came up with.

    With that in mind, how would we mark up a pin? Probably something like this (as some of you have done, we’ve changed the source order a bit).

    <article class="pin">
      <figure class="pin-holder">
        <a href="me/cat/">
          <img src="cat.jpg" alt="My awesome cat"/>
        </a>
        <figcaption>Awesome cat description.</figcaption>
      </figure>
      <footer>
        <ul class="stats">
          <li>25 likes</li>
          <li>2 comments</li>
          <li>100 repins</li>
        </ul>
        <div class="attribution">
          <a href="/me/">
            <img src="me.jpg" alt="Profile picture of me">
          </a>
          <p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
        </div>
      </footer>
      <menu class="actions" type="toolbar">
        <button onclick="repin">Repin</button>
        <button onclick="like">Like</button>
        <button onclick="comment">Comment</button>
      </menu>
    </article>

    To explain, we’ve started with an article to wrap the pin, which we’re all agreed on. Next, figure with figcaption for the image and description, as we’ve confirmed figure can be used for the main content.

    We’ve then included the stats and attribution in a footer, as it is information related to the content. The stats are in an unordered list to ensure they are distinct entities, rather than running into each other as they would do currently using spans if the CSS doesn’t load. We’ve left the attribution wrapped in a div, as there is no natural heading to make it a section etc.

    Finally, we’ve also introduced the menu element for the action buttons now it is starting to gain some browser support. The menu type could easily be changed to a list, really depends on how the actions are implemented I guess.

    Continuing our cat metaphor, some other ways include using something other than menu if browser support was an issue and getting fancier with the attribution (and comments) markup. I wrapped the stats and attribution in a footer as I think they’re supplementary information related to the main content. However Dr. Studholme argues that the footer isn’t necessarily needed, as for him the stats and attribution are main content. The great thing is both answers are correct according to the spec — as with many semantics issue, it depends on how you perceive the content.

    Thank you all for taking part. We hope you enjoyed it, and look forward to seeing what you come up with in the next HTML5 simple quiz!

    PS — Alohci, you’re spot on with C and D being invalid, I really should have spotted that. Thanks!

Stefan says

What do you think about using the link types I suggested ( author and bookmark) for the pin?

maxw3st says

Here’s what answers A — E + my own solution look like: Answers The images aren’t all of the same original dimensions.

maxw3st says

nice of wordpress to change my quotes to typographic speach quotes. I didn’t enter them that way. So, sorry the link above won’t work.

icaaq says

@Dr Richard Clark: Just a small note. If you you do it like that:

<div class="attribution">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</div>

Then a screen reader will announce something like: “link image profile picture of me”. A link that points to a picture of me… and that is not true, the link points to a profile page. A better alt-value would be alt=”[name]s profile page”.

A good link is regarding this is the simple alt text decision tree at http://dev.w3.org/html5/alt-techniques/#tree

Pete says

So essentially what you are saying is that <figure> element gives no meaning to its contents but is simply a mechanism to attach a caption to a some content.

If that is the case then I would suggest the use of the word “figure” is what is misleading rather than the wording of the spec.

Niels Matthijs says

There are so many things to say about this, but what I really don’t get is why all the stats are marked up using spans. A span is for inline content, meaning that the 3 stats would be read a single statement, even though they are three different entities? If anything, I’d use divs there.

Paul O'Donnell says

@Dr. Richard Clark. While the final markup seems to be the best thing going, I keep going back to Luke Padgett’s point about <figure> and <figurecaption>. I gather it is confirmed for use as main content. But this doesn’t mean we should. Furthermore, using it in this way seems to me to set limitations on what you can include in your main content. Let me explain, with reference to another great post…

From Common mistakes with the figure element:

The spec describes <figure> as being some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document. Therein lies the beauty of <figure>, that it can be moved away from the primary content — to a sidebar, say — without affecting the document’s flow.

So what happens if we were to move this content to a sidebar? By marking this content with <figure&gr;, we are characterizing it as a “single unit” (by which I understand, it is able to be taken from its current context without affecting the meaning of what’s behind). In this case, it leaves footer information with likes and dislikes and ‘posted by’ information without context.

What is wrong with a simple <img> for the image and <p> for the description?

<article class="pin">
<a href="me/cat/">
<img src="cat.jpg" alt="My awesome cat"/>
</a>
<p>Awesome cat description.</p>
<footer>
<ul class="stats">
<li>25 likes</li>
<li>2 comments</li>
<li>100 repins</li>
</ul>
<div class="attribution">
<a href="/me/">
<img src="me.jpg" alt="Profile picture of me">
</a>
<p><a href="/me/">Me</a> onto <a href="/here/">here</a></p>
</div>
</footer>
<menu class="actions" type="toolbar">
<button onclick="repin">Repin</button>
<button onclick="like">Like</button>
<button onclick="comment">Comment</button>
</menu>
</article>

By the way… what a blog post. It has helped me waste an entire day.

Paul O'Donnell says

A follow-up to my last comment.

Either <figure> is a tag meant for an image or graphic that accompanies and augments an article (as in, “see figure 1″) or it is, as Pete disapprovingly or disappointedly notes, merely a mechanism for captioning an image (with no other semantic overhead).

The former seems more in line with w3′s definition of it as “a unit of content, optionally with a caption, that is self-contained, that is typically referenced as a single unit from the main flow of the document, and that can be moved away from the main flow of the document without affecting the document’s meaning.”

This seems inconsistent with its being -the- main content in an article. Our example is a good illustration of why. First, ‘Moving it away’ leaves a footer that foots nothing. Second, it is not referenced from the main flow of the document.

So I guess I am taking issue with <figure> being used as the main content. It is not that it’s superfluous, but self-neutering. Neutersome, to coin a term.

Paul says

I’m pretty sure I’m beating a dead horse and everyone has moved on. But I didn’t see this solution proposed and I think it works:

Certain elements are said to be sectioning roots, including blockquote and td elements. These elements can have their own outlines, but the sections and headings inside these elements do not contribute to the outlines of their ancestors.
->
blockquote, body, details, dialog, fieldset, figure, td
HTML5 Spec

Since figure is a sectioning root, it can have its own outline. And it allows for flow content like footer and menu with an optional figcaption.

So, what about…


<article class="pin">
  <figure class="pin-holder">
    <a href="me/cat/">
      <img src="cat.jpg" alt="My awesome cat"/>
    </a>
    <figcaption>
<p>Awesome cat description.<p>
</figcaption>
 <footer>
   <ul class="stats">
     <li>25 likes</li>
     <li>2 comments</li>
   <li>100 repins</li>
   </ul>
   <div class="attribution">
     <a href="/me/">
       <img src="me.jpg" alt="Me's Profile">
     </a>
     <p><a href="/me/">Me</a> onto <ahref="/here/">here</a></p>
   </div>
 </footer>
<menu class="actions" type="toolbar">
    <button onclick="repin">Repin</button>
    <button onclick="like">Like</button>
    <buttononclick="comment">Comment</button>
  </menu>
  </figure>
</article>

steve faulkner says

I have updated the HTML 5.1 editor’s draft informative text about figure. Feedback welcome, This blog post On joining the HTML editors team provides details on how you can comment.

steve faulkner says

@paul,

note that figcaption must be either first or last child of the figure element see content model.

Behrang says

I prefer a markup with article, figure, and aside elements but no navs or sections.

Ian Y. says

article, section, and aside are all sectioning elements. Wherever they are presented, there need to be heading elements associated with them. Since there are no headings in Pinterest entries, the above mentioned three elements might not be ideal candidates.

Richard Clark says

@Ian, although they are sectioning elements, there is no requirement for them to have a heading (at least according to the spec). A nav for example won’t always need a heading, yet it is a sectioning element.

Andrew Himmer says

The only issue I have with some of these options is the use of the nav element. I feel that the nav element is reserved for actual navigation. A group of anchor elements that act like tool options does not constitute navigation (they don’t link to related content or pages, or other sections).

Ian Y. says

@Richard, yes, the spec doesn’t say we should add headings for sectioning elements. However, it can cause issues if not doing so.

Sectioning elements form sections in the document outline. Without headings, they lost their identities and people have no way to tell their purposes in the document outline.

Another concern is accessibility. After screen reader users reach a section, they need a heading to let them know what the purpose of the section is.

For sections which don’t show headings visually, we still should add headings for them in HTML and hide their headings using CSS.

Join the discussion.

Some HTML is ok

You can use these tags:
<a href="" title="">
<abbr title="">
<b>
<blockquote cite="">
<cite>
<del datetime="">
<em>
<i>
<q cite="">
<strong>

You can also use <code>, and remember to use &lt; and &gt; for brackets.