How to

How to display

Goal: display received comments in high fidelity, at least as nicely designed as the comments that are "natively" displayed on blog posts and silo posts (e.g. replies on Twitter posts, comments on Facebook posts, Flickr/Instagram photos, etc. - see Silos below for analysis of their practices).

parse the h-entry at that URL (only use the first h-entry if there's more than one, seriously, it's supposed to be a permalink) - use a microformats2 parser to do so.

if its hyperlink to the original post lacks in-reply-to markup, then add it to the "Related Articles" or "Mentions" section in the post footer, otherwise keep going:

get commenter information to display

if the h-entry has a p-author, use its h-card:

otherwise get the first*rel-author link on the page, retrieve the URL it points to, and use its representative h-card:

logo/photo

name

url (of commenter profile/homepage)

get the text of the comment to display

IF the h-entry has an e-content, AND if the text is not too long (per your own site UI preference/design, but note that "too long" may be both by character/word count or by number of lines if the content contains newlines), THEN use that, after sanitizing (filtering out unsafe HTML).

IF there is no e-content OR it's too long, THEN

IF the h-entry has a p-summary, AND the text is not too long, THEN use that (useful author crafted summary or for longer posts where only a part of it is the comment)

IF the p-summary is too long (per your own site UI preference/design), THEN truncate the p-summary yourself (per below TRUNCATING details)

ELSE truncate the e-content (if any) yourself (per TRUNCATING).

OTHERWISE (no e-content and no p-summary), IF it has a p-name, THEN use that

IF the p-name is too long (per your own site UI preference/design)

THEN truncate the p-name yourself (per TRUNCATING).

TRUNCATING: IF the text of the comment (however you got it above) is too long (your site, your judgment), THEN abbreviate it with some intelligent ellipsing code (e.g. see POSSEing an abbreviated note to Twitter for some thinking) and provide a "See more" / "View more" / "More ..." link to the permalink (useful to have an explicit link to the whole comment right next to the ellipsis when YOU (your site) has chosen to truncate or show only a summary because comments can themselves have an ellipsis at the end).

get more comment info to display

use the h-entry dt-published for the time of the reply

additionally, its dt-updated could be used for an "edited: datetime" annotation in your display

use its u-url for the permalink (hyperlink the time of reply to the permalink)

optional location brainstorm - because not many have implemented location info in posted replies

use the h-entry p-geo / p-latitude / p-longitude for location - you may need to use a service to translate that into a human readable neighborhood / city / state / country name. perhaps hyperlink to a map, or an aggregation on your site of all posts (and comments) near that location.

(Issue: perhaps h-entry could use a p-location property similar to h-event that would permit embedding of an h-adr with structured address information.)

With that information a sufficiently rich display should be possible in a "Comments" section in the footer on the original post permalink. Add to that for each comment:

"*first" rel-author is good enough because a) there aren't many multiauthor blogs, comparatively speaking, and more importantly b) this is retrieving a *reply* post, and those are always written by a single person, so there should only be a single rel-author on *that* page. Real-world counter-examples welcome.

in realtime

Even better, if you can display comments in real-time on people viewing a post, when they're received by your server, it looks amazing to the user. Idea/challenge 2013-09-30.

How to overview:

keep a websocket open from the browser view of your post with comments to your server

have your server push comments to your browser view your post through the open websocket.

Which documents a bunch of pre-indieweb thinking of how to markup comments, especially when comments were only made natively on a post directly, rather than being propagated peer-to-peer.

In general this "how to" and the indieweb approach is a further simplification of the microformats comment-brainstorming, with properties added as needed by real world needs.

p-content on comment body

Note that class="p-content" is used for the body of the comment, here's why:

p-* instead of e-*: The easiest and safest thing to do is to only show plain text comment content from someone else's site. Therefore use p-content instead of e-content. If you were including links, images, or anything else richer than plain text from someone else's site, then you could use e-content.

p-content instead of p-summary: Typical comments are small enough to display in their entirety, thus that common case is the entirety of the content not a summary, therefore p-content is more appropriate than p-summary. If for some reason you find it necessary to truncate the comment (or use someone else's "p-summary"), then yes, you should use p-summary instead of p-content.

Markup Issues

I think the h-cite markup only works for comments via pingback/webmention, but what about comments made directly on the post using a comment-form? -- pfefferle

Native comments make sense as "h-entry" since the copy of them on the post is likely the canonical copy. - Tantek 13:45, 12 July 2015 (PDT)

Past Examples

Laurent Eschenauer

Laurent Eschenauer using Storytlr: displayed comment posts from the IndieWeb marked up with h-entry and received via pingback, and comments posted locally on his posts, in an integrated time-ordered "Comments" section, since 2013-04-19 (til ~2016). e.g.:

Tumblr

Tumblr groups various different response types into a generic “notes” feed, at the bottom of each post (example). They show:

The author’s username

The author’s profile photo

Twitter

Twitter shows all tweets which are both in-reply-to a particular tweet AND contain the original tweeters @name below the tweet metadata in chronological order. They provide a “reply” box above (?) the reply feed (example). The tweets have:

Facebook

Facebook treats comments as completely secondary to “full” posts, showing them in chronological order beneath the post’s action bar. Facebook only show the latest ~4 comments if there are more, and display the leave-a-comment box below. They have:

The author’s name

The author’s profile photo

The comment content

A relative timestamp

'via mobile' if applicable

Like button w/ like counter

Comments Embeds

Some silos have a comments embed which is used by various sites to host comments elsewhere:

Disqus - their focus is to provide comments or ("discussion" - hence their name) sections on other pages.

Comment Hiding

shutup.css is custom stylesheet that hides comments on many popular websites. As such it is empirical research on how silos mark up comments. See the CSS for details.

FAQ

Why use p-summary when I can truncate e-content

Q: I guess if I grab the e-content and think it's too long, I might as well just truncate it myself. why would I need the p-summary?

A: Because the p-summary is likely (or even just possibly) explicitly crafted by the author/publishers to be a more meaningfully truncated version of the e-content than you could yourself automatically truncate.

Why use u-comment instead of p-comment

Q: Why use u-comment around the comment instead of p-comment?

A:u-comment will parse the comment's implied value as the comment's URL, which is useful for salmention support. [1]

Discussion

Long posts where only a part of it is in-reply-to another post and a large chuck of it is a tangent should not be published as a reply/comment and instead should be published as a mention. Noting this here because this is accounted for above in the "How to display > get the text of the comment to display" section and it might wrongly send the message that (largely tangential) posts like these should be marked up with in-reply-to. (See [2])

For places where comments can't be included in line the use of a u-responses to point to another page containing a list of h-entry objects with all of the received comments would be useful. Useful in blog lists and when using an external WebMention endpoint such as webmention.herokuapp.comKodfabrik.se

How to mark up nested comments?

Nested comments could easily be caused by Salmention. reply-chain has some examples of people showing multiple replies.

We decided to treat the 70m comments that have been left on the Guardian – and in particular the comments that have been blocked by our moderators – as a huge data set to be explored rather than a problem to be brushed under the carpet.

2013-05-16 Audrey Watters: The Comments Are Closed - many specific criticisms of comments, and the burden of maintaining them

Previous specifications for display

(this historical section could be moved to its own page)

Included here for thoroughness / historical purposes - a critique of existing specifications for display.

Summary: Existing specifications either don't say much or provide bad advice for what to display (if anything) in response to receiving a webmention.

"Pingback from" is jargon - provides no value to the user - only noise

the title of the comment blog post is useless as it provides a summary of the original blog post

the [...] ... [...] summary text is nearly unreadable without more context, and doesn't even show what phrase linked to the original blog post

in the first pingback, even just including the entire first paragraph of the comment post would have been better. And if it wasn't a reply then it should just be a list of related articles (date, author, linked post name, all marked up with h-cite), rather than including cryptic broken summaries.

the overall visual design is very dated and has fallen behind modern comment presentation designs