Maximally Semantic Structure for a Blog Post

@edent — Mon, 12 Jan 2026 12:34:53 +0000

Yes, I know the cliché that bloggers are always blogging about blogging!

I like semantics. It tickles that part of my delicious meaty brain that longs for structure. Semantics are good for computers and humans. Computers can easily understand the structure of the data, humans can use tools like screen-readers to extract the data they're interested in.

In HTML, there are three main ways to impose semantics - elements, attributes, and hierarchical microdata.

Elements are easy to understand. Rather than using a generic element like

you can use something like

to show an element's contents are for navigation. Or

to show that the contents are an address. Or

to show that the section is part of a parent article.

Attributes are also common. You can use relational attributes to show how a link relates to the page it is on. For example shows that the link is to the author of the current page. Or, to see that a link goes to the previous page in a series .

Finally, we enter the complex and frightening world of microdata.

Using the Schema.org vocabulary it's possible to add semantic metadata within an HTML element. For example, says that the body of this page is a Blog. Or, to say how many words a piece has, 1,100 words.

There are many properties you can use. Here's the outline structure of a single blog post with a code sample, a footnote, and a comment. You can check its structured data and verify that it is conformant HTML.

Feel free to reuse.



My Blog


    
        My Blog
    

    
        
            
                
                    1st January, 2025
                
                
                    Post Title
                
                
                    
                        By Author Name
                    
                    
                
                
                    HTML 
                    semantics 
                    6 comments
                    1,100 words
                    
                        
                        
                            Viewed ~5,150 times
                        
                    
                
            

            
                
                Text of the post.
                Text with a footnote⁰.

                                    PHP
                    &lt;?php echo $postID ?&gt;
                

                
                    Footnotes
                    
                        
                            Footnote text. ↩︎
                        
                    
                
            
        

        
            Comments
            
                
                    2025-09-11 13:24
                
                
                    
                    
                        Alice says:
                    
                
                
                    Comment text

This blog post is entitled "maximally" but, of course, there is lots more that you can add if you really want to.

Remember, none of this is necessary. Computers and humans are pretty good at extracting meaning from unstructured text. But making things easier for others is always time well spent.

Fixing "Date/time not in ISO 8601 format" in Google Search Console

@edent — Wed, 24 Dec 2025 12:34:43 +0000

I like using microdata within my HTML to provide semantic metadata. One of my pages had this scrap of code on it:

9 June 2025 11:27

The Google Search Console was throwing this error:

I was fairly sure that was a valid ISO 8601 string. It certainly matched the description in the Google documentation. Nevertheless, I fiddled with a few different formats, but all failed.

On the advice of Barry Hunter, I tried changing the datetime attribute to content. That also didn't work.

Then I looked closely at the code.

The issue is the itemscope. Removing that allowed the code to pass validation. But why?

Here's what the Schema.org documentation says:

By adding itemscope, you are specifying that the HTML contained in the block is about a particular item.

The HTML specification gives this example:

Here, the image property is the value of the element. In this case google-logo.png. So what's the problem with the time example?

Well, is a void element. It doesn't have any HTML content - so the metadata is taken from the src attribute.

But is not a void element. It does contain HTML. So something like this would be valid:

2025-06-09T11:27:06+01:00

The text contained by the element is a valid ISO8601 string.

My choice was either to present the ISO8601 string to anyone viewing the page, or simply to remove the itemscope. So I chose the latter.

Class Warfare! Can I eliminate CSS classes from my HTML?

@edent — Fri, 19 Sep 2025 11:34:55 +0000

I recently read a brilliantly provocative blog post called "This website has no class". In it, Adam Stoddard makes the case that you might not need CSS classes on a modern website:

I think constraints lead to interesting, creative solutions […]. Instead of relying on built in elements a bit more, I decided to banish classes from my website completely.

Long time readers will know that I'm a big fan of using semantic HTML where possible. If you peek beneath the curtain of this website you'll only see a handful of

elements (mostly because WordPress hardcodes them) - all the other blocks are fully semantic. Regrettably, there are rather too many elements for my liking - normally for accessibility or for supplementing the metadata.

Overall, my CSS contained about 134 rules which selected based on class. Is that a lot? It feels like a lot.

On the one hand, classes are an easy way of splitting and grouping elements. Some s should be displayed one way, the rest another. There's no semantic way to say "This is a hero image and should take up the full width, but this is an icon and should float discretely to the right."

But, on the other hand, why do we need classes? Keith Cirkel's excellent post "CSS Classes considered harmful" goes through their history and brings together some proposed solutions for replacing them. I think his idea of using data- attributes is a neat hack - but ultimately isn't much different from using classes. It's still a scrap of metadata to be tied into a style-sheet.

Classes are great for when you reuse something. I have multiple

elements but most don't share anything in common with the others. So they probably oughtn't have classes.

Removing classes has some advantages. It makes the HTML fractionally smaller, sure, but it also forces the author to think about the logical structure of their page and the semantics behind it.

Looking through my HTML, lots of classes exist because of laziness. If I want to position all the elements which are within a comment, I don't need to write and to pair it with .whatever { … }. Instead, I can use modern CSS selectors and say #comments time { … }.

But this leads me on to another existential question.

Are IDs necessary in modern HTML?

Mayyyyybe? I only have one

element, so an ID on there is unnecessary. elements need IDs in order to be properly targetted by s - but the label can wrap around the input. I have multiple

elements because there's no semantic element, so they need unique IDs.

In theory, as suggested by Adam above, I could use an autonomous custom element like - but that has none of the semantics and, frankly, feels like a bit of a cheat.

Trimming the fat

Any day where I can delete some code is a good day. This was an excellent exercise in going through (years) of HTML and CSS to see what cruft had built up.

The first CSS rule I changed was, as mentioned above:

time.commentmetadata {
    float: right;
}

Which became:

#comments time { 
    float: right;
}

Classless and slightly more brief. Is it more readable? Having the fact it was about the metadata in a class could have been slightly useful - but if I thought it would be confusing, I could stick a /* comment */ in there.

Next, I found

- what a tautology! I have multiple

elements, it is true. But none of them have the same style. So this swiftly became

with an accompanying CSS rewrite.

My theme switcher had a bunch of s. They were all within a container with a unique ID, so could they be changed? Yes. But seeing the class name in the HTML is a good reminder to the author of how they are meant to display. Does that co-mingle content and presentation too much?

Some of the WordPress default classes are ridiculous. The body_class() function injected this into every

"wp-singular post-template-default single single-post postid-62959 single-format-standard wp-theme-edent-wordpress-theme"

Most of that is redundant - what's the difference between single and single-post? For my purposes, nothing! So they were all yeeted into the sun.

Rather than targetting IDs or classes, I targetted the presence or absence of Schema.org microdata.

For example:

main[itemprop="blogPost"] { … }
main:not([itemprop="blogPost"]) { … }

This can go to the extreme. I have lots of comments, each one has an author, the author's details are wrapped in

…

That can be replaced with:

/* Comment Author */
li[itemtype="https://schema.org/Comment"] > article > div[itemprop="https://schema.org/author"] {
    margin-bottom: 0;
}

Is that sensible? It is more semantic, but feels a bit brittle.

Parent selector are also now a thing. If I want a paragraph to have centred text but only when there's a submit button inside it:

p:has(input#submit) {
  text-align: center;
}

Again, am I sure that my button will always be inside a paragraph?

Similarly, sibling selectors are sometimes superior - but they do suppose that your layout never changes.

What remains?

There are some bits of this site which are reusable and do need classes. The code-highlighting you see above requires text to be wrapped in spans with specific classes.

Image alignment was also heavily class based.

There are some accessibility things which are either hidden or exposed using classes.

A bunch of WordPress defaults use classes and, even if they are redundant, it's hard to exorcise them.

As much as I would have liked to get rid of all my IDs, many needed to stay for linking as well as CSS targetting.

All told, the changes I made were:

134 class selectors down to about 65.
35 ID selectors up to about 50.
5 attribute selectors up to to about 20.
Deleted or combined a lot of redundant CSS and tidied up my markup considerably.

I have around 250 CSS rules, so now the majority target semantics rather than classes or IDs.

Is this really necessary?

No, of course not. This is an exercise in minimalism, creativity, and constraint. Feel free to litter your HTML with whatever attributes you want!

As I went through, it increasingly became apparent that I was fitting my CSS to my HTML's logical structure rather than to its conceptual structure.

Previously, my comments were targetted with a class. Now they have the slightly more tangled targetting of "divs with this schema attribute whose parent is an article and whose grandparent has this ID".

It is a delightful meditative exercise to go through your code and deeply consider whether something is unique, reusable, or obsolete.

Is IPA furigana a bad idea?

@edent — Thu, 10 Oct 2024 11:34:17 +0000

My name is Terence(/ˈtɛɹəns) Eden(ˈiːdən/).

Modern HTML allows the user to use to annotate text.

This is usually used for furigana - which allows pronunciation to be placed above words.

For example: "シン・ゴジラ (Shin Godzilla)" shows you how to pronounce both words if you are unfamiliar with kanji. The text can be any language or use any characters. In Japanese, it is quite often used to show phonetic pronunciation using hiragana.

Because English is a composite language⁰, it isn't always easy for people to pronounce words¹.

So I have abused(?) the ruby syntax to show the International Phonetic Alphabet above the English words.

Is this a good idea? Is it a valid use of the syntax? Is it semantically correct? I don't know. But I do now know that it is possible.

I doubt the majority of people know the IPA, so it is of dubious use. It does make my name's pronunciation more apparent to machines.

An alternative is to use Schema.org. For example, my contact page has the following microdata:


    
        
            Terence 
            Eden

That allows humans to listen to the pronunciation of my name, and machines to see the IPA version.

Is there a better, more accessible, more useful way of encoding how to pronounce text?

Or a mongrel language ↩︎
Yes, I've seen that funny Tiktok. And that one. ↩︎

What programming language is in this `block?`


@edent — Tue, 27 Aug 2024 11:34:28 +0000
I'm a little bit obsessed with the idea of Semantic markup. I want the words that I write to be understood my humans and machines.

Imagine this piece of code: print( "Hello, world!" )

Is that code example written in Python? C++? Basic? Go? Perhaps you're familiar enough with every programming language to tell - but most people aren't.  Wouldn't it be nice to give an indication of what programming language is used in an example?

Here's how we might represent it in HTML:

    
        print( "Hello, world!" )
    



How do we let the browser, search engines, and humans know what language that's written in? It might seem obvious to use the lang attribute, right? We're writing in a programming language, so just use . Sadly, the HTML specification disagrees.


The lang attribute specifies the primary language for the element's contents and for any of the element's attributes that contain text. Its value must be a valid BCP 47 language tag, or the empty string. 
 HTML Specification 3.2.6.2 The lang and xml:lang attributes (emphasis added)

That means it must be a human language like en or en-GB. No Klingon or Elvish - and certainly no computer languages!

Does the specification give any clues about the  element?


There is no formal way to indicate the language of computer code being marked up. Authors who wish to mark code elements with the language used, e.g. so that syntax highlighting scripts can use the right rules, can use the class attribute, e.g. by adding a class prefixed with "language-" to the element.
HTML Specification 4.5.15 The code element (emphasis added)

So we have to turn to our old friend Schema.org! There is a SoftwareSourceCode type which is used for exactly this case. Sadly, there is no example documentation because Google likes to start up a project but never quite finish it.

Here's how to write a code snippet in HTML and have it semantically expose the programming language used:

    Python
    
    
        print( "Hello, world!" )
    



If you run that through the validator you'll see what a computer sees:



The programmingLanguage is a string - so you can write anything you like in there. You can optionally add a codeSampleType which, again, is a free-text field.

The  items are only viewable to machines. You could also them to the user if you wanted, using a  or other suitable element.

Alternatives

It is possible to define private subtags of languages for example en-x-python - which could mean "Comments written in English, using the private Python extension. Or even just x-python. That then leads on to how you describe a language - but while COBOL has a MIME type not all languages do.  There are some unofficial ones like text/x-python though.

But, of course, programming languages aren't really languages - so using lang probably isn't suitable.

A data- attribute might also work. Adding data-code="python" would allow CSS to style specific code blocks. But data attributes are private to a page, and generally aren't standardised.

I think this is a gap in the specification. I think there ought to be a code-lang attribute or similar. Perhaps something like:


    print( "Hello, world!" )



Which could allow authors to semantically give the name - and possibly version - of the programming language they are writing in.

Thoughts?



Addressing the Overlooked Non-Micropsychiatric Uses for Thiotimoline
@edent — Mon, 26 Jun 2023 11:34:34 +0000
One of the (many) problems with AI is that training data usually needs to come from "natural" sources. If you want to emulate human-written text, you need to train something on human-written text.   But with the proliferation of cheap and fast AI tools, it is likely that training data will unwillingly become contaminated with AI-written text.

In order to prevent the "Habsburg Jaw" effect, I think it would be helpful if publishers could semantically indicate that a work was written by AI.  In this example, I'm using Schema.org's Quotation type to show that I'm quoting an AI, and explicitly set the author to ChatGPT.


    Author: OpenAI ChatGPT
    ...



Is that sufficient to stop AIs from feeding on their own young? I don't know. I also don't know if this covers every possible use-case, or whether there are better ways to address this. I'd be interested in hearing your thoughts.

Anyway, here's a letter to the editor of Nature written by ChatGPT. It took a little bit of prompt-engineering, but I'm rather pleased with how readily it took to the idea of inventing new uses for Thiotimoline. I especially like the way it has created obviously fictitious journals in its citations!  This example is marked up so as to let robots know that it is a synthetic output.


    Author: OpenAI ChatGPT

    
Dear Editor,

I hope this letter finds you well. As a distinguished biologist who has been an avid reader of Nature for many years, I would like to draw attention to a concerning issue that I believe has inadvertently slipped through the cracks of the journal's otherwise comprehensive coverage of scientific advancements. It is with great disappointment that I note the persistent oversight of the non-micropsychiatric applications of Thiotimoline, an area of research that deserves proper recognition.

Thiotimoline has generated considerable interest within the scientific community due to its unique temporal properties and hypothetical solubility characteristics.

Contrary to popular belief, Thiotimoline's potential extends far beyond the realm of micropsychiatry. Researchers have explored various hypothetical applications in multiple disciplines, and it is disheartening to witness Nature's omission of these intriguing possibilities. Allow me to shed some light on the non-micropsychiatric uses of Thiotimoline that merit attention:


Time-Dependent Chemical Reactions: Thiotimoline's purported ability to dissolve before it comes into contact with water presents fascinating prospects for studying time-dependent chemical reactions. By altering reaction kinetics and introducing temporal dimensions into experimental setups, Thiotimoline could revolutionize our understanding of reaction mechanisms and provide insights into complex chemical processes ⁰.
Temporal Pharmacokinetics: Thiotimoline's hypothetical solubility properties and unique temporal characteristics offer a potential breakthrough in drug delivery systems. Controlled-release formulations utilizing Thiotimoline could provide precise temporal dosing, ensuring optimal drug concentrations at critical intervals and improving therapeutic efficacy ¹.
Time-Sensitive Analytical Chemistry: Thiotimoline's temporal properties have captivated analytical chemists, inspiring innovative methodologies in time-sensitive analysis. Researchers propose the use of Thiotimoline as a temporal indicator, enabling real-time monitoring of chemical reactions and facilitating rapid data acquisition in various analytical techniques ².


While the studies mentioned above are speculative, they demonstrate the conceptual potential of Thiotimoline as a catalyst for groundbreaking scientific exploration. By embracing the imaginative aspects of scientific inquiry, we can encourage innovative thinking and uncover unexpected insights that may guide future advancements.

I implore Nature to devote some attention to these non-micropsychiatric uses of Thiotimoline. By acknowledging the imaginative scientific spirit that drives our quest for knowledge, the journal can foster interdisciplinary collaboration and inspire researchers to explore uncharted territories.

Thank you for considering my concerns. I sincerely hope that Nature will continue to lead the scientific community by embracing the full spectrum of scientific endeavors.

Yours faithfully,








Hypothetical Research, Journal of Speculative Chemistry, vol. 123, no. 4, pp. 567-578, 20XX. ↩︎



Imaginary Drug Delivery Systems, Journal of Fictional Pharmacology, vol. 45, no. 2, pp. 211-223, 20XX. ↩︎



Exploring Time-Sensitive Analytical Techniques, Fictional Analytical Chemistry Review, vol. 67, no. 3, pp. 354-365, 20XX. ↩︎







LinkedIn supports Schema‎.org metadata
@edent — Fri, 23 Jun 2023 11:34:09 +0000
I'm a big fan of machine-readable metadata. It's useful for programs which need to extract information from messy and complicated websites. It's always surprising where it turns up.

For example, take this post of mine on LinkedIn. If you view the source, you'll see this scrap of linked data:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "SocialMediaPosting",
  "@id": "https://www.linkedin.com/posts/terenceeden_did-you-know-that-every-post-you-make-on-activity-7075043149462556672-fxiw",
  "author": {
    "name": "Terence Eden",
    "image": {
      "url": "https://media.licdn.com/dms/image/C4E03AQEX11qBnAo43A/profile-displayphoto-shrink_400_400/0/1517677542848?e=1692230400&v=beta&t=-AHOoj__Ehm_p24dQ6McPbqNj9gQ2UsjvzOCIU16IGs",
      "@type": "ImageObject"
    },
    "url": "https://uk.linkedin.com/in/terenceeden",
    "@type": "Person"
  },
  "datePublished": "2023-06-15T09:35:34.752Z",
  "articleBody": "Did you know that every post you make on LinkedIn has SchemaOrg metadata embedded in it?\n(This post mostly to test which fields are supported.)",
  "isAccessibleForFree": false,
  "hasPart": {
    "@type": "WebPageElement",
    "isAccessibleForFree": false,
    "cssSelector": ".details"
  }
}
</script>


If you share a link in your post, the markup is slightly different:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "SocialMediaPosting",
  "@id": "https://www.linkedin.com/posts/terenceeden_why-im-using-mx-as-a-title-activity-7074702026084884480-jO0C",
  "author": {
    "name": "Terence Eden",
    "image": {
      "url": "https://media.licdn.com/dms/image/C4E03AQEX11qBnAo43A/profile-displayphoto-shrink_400_400/0/1517677542848?e=1692230400&v=beta&t=-AHOoj__Ehm_p24dQ6McPbqNj9gQ2UsjvzOCIU16IGs",
      "@type": "ImageObject"
    },
    "url": "https://uk.linkedin.com/in/terenceeden",
    "@type": "Person"
  },
  "datePublished": "2023-06-14T11:00:04.600Z",
  "image": {
    "url": "https://media.licdn.com/dms/image/sync/D5627AQHWF4nuGqlfzQ/articleshare-shrink_800/0/1686397225711?e=1687428000&v=beta&t=SsQ_1b8M3xAGXnhUvID0976rpItlTLdC2Gz9RG3sXwI",
    "@type": "ImageObject"
  },
  "sharedContent": {
    "@type": "WebPage",
    "headline": "Why I'm using \"Mx\" as a title",
    "url": "https://shkspr.mobi/blog/2023/06/why-im-using-mx-as-a-title/"
  },
  "articleBody": "What title do you use when filling in forms? Mr? Mrs? Ms? Or something newer and more incluside?\n\nWhy do companies want to know my title? What are they going to do with my data?\n\nHere's why I'm using \"Mx\" as my title.\nhttps://lnkd.in/eCNH5sqp",
  "isAccessibleForFree": false,
  "hasPart": {
    "@type": "WebPageElement",
    "isAccessibleForFree": false,
    "cssSelector": ".details"
  }
}
</script>


Interestingly, this doesn't seem to be exposed in the API. It's available to any user-agent which requests a public LinkedIn post. I don't recommend you train any LLMs on the data though - it would be unbearably smug.

It would be incredibly useful if other social media platforms like Mastodon used this.



Does AI mean we don't need the Semantic Web?
@edent — Sat, 20 May 2023 11:34:47 +0000
If you hang around with computerists long enough, they start talking about the Semantic Web. If you can represent human knowledge in a way that's easy for computers to understand it will be transformative for information processing.

But computers, traditionally, haven't been very good at parsing ambiguous human text.

Suppose you saw this text written for a human:

Our opening hours are: Weekdays 10 until 7. Weekend 10 until 10 (Early closing 9 o'clock Sunday).

Not the most straightforward sentence, but pretty easy for a human to parse.

Until recently, the best way to represent that for a computer was something like:






or




A tightly constrained vocabulary which can be precisely parsed by a simple state-machine. Easy to ingest, interpret, and query. Easy for machines, that is. As much as I love the semantic web, it is hard for humans to write, update, and maintain.

But we have AI now.  So do we need to mark up documents specifically for machines?

I fed the text into OpenAI's ChatGPT.  Here's what it said:



It isn't just capable of parroting back data - it can perform moderately complex reasoning:



Do we need to write for computers any more?  One of the demands of the Semantic Web was that we should use HTML elements like 
 to clearly mark up a contact address and we should wrap dates and times in the  element.

Is that now redundant?

We still need to write clearly and unambiguously. But do we need separate "machine-readable" HTML if machines can now read and interpret text designed for humans?



Adding restaurant review metadata to WordPress
@edent — Sun, 22 Jan 2023 12:34:46 +0000
I've started adding Restaurant Reviews to this blog - with delicious semantic metadata.  Previously I'd been posting all my reviews to HappyCow.  It's a great site for finding veggie-friendly food around the worlds, but I wanted to experiment more with the IndieWeb idea of POSSE.  So now I can Post on my Own Site and Syndicate Elsewhere.

The Schema.org representation of a Restaurant is pretty simple:

"itemReviewed": {
    "@type": "Restaurant",
    "name": "Example Bistro",
    "address": "42 Wallaby Way, Sydney",
    "hasMenu": "https://example.com/menu",
    "servesCuisine": "Vegetarian",
    "sameAs": "https://www.example.com/restaurant"
}


There are many more metadata items which could be added - but that's enough for my purposes.

I've written my own WordPress theme to add Semantic Reviews. It gives me a little UI box to add in all the essential data.



Once all that's fed in, it's converted to JSON+LD which looks like this:

{
    "@context": "https:\/\/schema.org",
    "@type": "Review",
    "author": {
        "@type": "Person",
        "name": "Terence Eden",
        "sameAs": [""]
    },
    "url": "https:\/\/shkspr.mobi\/blog\/?p=44547",
    "datePublished": "2023-01-20T12:34:10+00:00",
    "publisher": {
        "@type": "Organization",
        "name": "Terence Eden\u2019s Blog",
        "sameAs": "https:\/\/shkspr.mobi\/blog"
    },
    "description": "If you've visiting Batu Caves in Kuala Lumpur, I have two tips for you. Firstly, get there as early as possible in order to avoid the heat and other tourists. Secondly, after climbing a mountain of ",
    "inLanguage": "en-GB",
    "itemReviewed": {
        "@type": "Restaurant",
        "name": "Rani Vilas Restaurant Batu Caves",
        "address": "Jalan Batu Caves, Batu Caves, Malaysia, 68100",
        "sameAs": "http:\/\/www.facebook.com\/RaniVilasRestaurantBatuCaves",
        "hasMenu": "https:\/\/www.foodpanda.my\/restaurant\/w1rb\/rani-vilas-restaurant-shop",
        "servesCuisine": "Vegetarian Indian",
        "image": "https:\/\/shkspr.mobi\/blog\/wp-content\/uploads\/2023\/01\/rani.jpg",
        "aggregateRating": {
            "@type": "AggregateRating",
            "ratingValue": "5",
            "reviewCount": "1",
            "worstRating": 0,
            "bestRating": 5
        }
    },
    "reviewRating": {
        "@type": "Rating",
        "worstRating": 0,
        "bestRating": 5,
        "ratingValue": "5"
    },
    "thumbnailUrl": "https:\/\/shkspr.mobi\/blog\/wp-content\/uploads\/2023\/01\/rani.jpg"
}


The somewhat messy code is available on my GitLab. If there's any interest, I might turn it into a separate WordPress plugin.



Semantic Comments for WordPress
@edent — Thu, 28 Apr 2022 11:34:13 +0000
As regular readers will know, I love adding Semantic things to my blog.

The standard WordPress comments HTML isn't very semantic - so I thought I'd change that. Here's some code which you can add to your blog's theme - an an explanation of how it works.

The aim is to end up with some HTML which looks like this (edited for brevity):


    
        
            22-04-12 10:22
        
        
            
            
                Commenter's Name says:
        
        This is the text of my comment
    



Which will be interpreted as:


This adds  elements as well as Schema.org microdata.

Howto

In comments.php you'll see something like this:


     'ol',
            'short_ping'  => true,
            'avatar_size' => 64,
        ) );
    ?>



You need to add a new callback. In this case, I've called it my_comments_walker:


     'ol',
            'short_ping'  => true,
            'avatar_size' => 64,
            'callback' => 'my_comments_walker',
        ) );
    ?>



You can read more about WordPress Walkers on their documentation page.

Now that's done, you need to create a function in your functions.php file.  I added this to the end of my file:

function my_comments_walker() {

    //  Basic comment data
    $comment_id          = get_comment_id();
    $comment             = get_comment( $comment_id );

    //  Date the comment was submitted
    $comment_date        = get_comment_date( "c" );
    //  In slightly more human-readable format
    $comment_date_human  = get_comment_date( "y-m-d H:i" );

    //  Author Details
    $comment_author      = get_comment_author();

    //  Author's URl if they've added one
    $comment_author_url  = get_comment_author_url();

    //  If there's an Author URl, link it
    if ($comment_author_url != null) {
        $comment_author_name = "{$comment_author}";
    } else {
        $comment_author_name = "{$comment_author}";
    }

    //  Provide a link to the comment anchor
    $comment_url_link = "{$comment_date_human}";

    //  Author's Avatar based on ID
    //  As per https://developer.wordpress.org/reference/functions/get_avatar/ both alt & default must be set
    $gravatar            = get_avatar( $comment, 64, "", "", array('extra_attr' => 'itemprop="image"') );

    //  Comment needs newlines and links added
    $comment_text        = apply_filters( 'comment_text', get_comment_text(), $comment);


    //  The comment may have various classes. They are stored as an array
    $comment_classes     = get_comment_class();
    $comment_classes_text = "";
    foreach( $comment_classes as $class ) {
        $comment_classes_text .= $class . " ";
    }
    $comment_classes_text = trim($comment_classes_text);

    //  Link to open the reply box
    $comment_reply_link = get_comment_reply_link( [
                    'depth'     => 20,
                    'max_depth' => 100,
                    'before'    => '',
                    'after'     => ''
            ] );

    //  Write the comment HTML. No need for a closing  as WP handles that.
    echo <<< EOT
    
        
            
                $comment_url_link
            
            
                $gravatar
                $comment_author_name says:
            
            $comment_text
            $comment_reply_link
        
    EOT;
}


There are a few extra classes and spans which I use. You can remove them if you like.

And that's it. All your comments will have individual semantic metadata. If you think anything else should be included, please let me know.



How to add ISSN metadata to a web page
@edent — Fri, 17 Sep 2021 11:09:05 +0000
Inspired by John Hoare at the Dirty Feed blog - I've asked the British Library to assign my blog an International Standard Serial Number (ISSN).

An ISSN is an 8-digit code used to identify newspapers, journals, magazines and periodicals of all kinds and on all media–print and electronic.



Why?

Shut up.

OK. It turns out that lots of people cite my blog in academic papers - so I wanted to make it slightly easier for scholars of the future to use metadata to trace my vast influence on Human civilisation.

How?

I filled in a form on the British Library website. Didn't cost me a penny. Was pretty quick!

Metadata

I can stick a bit of text at the bottom of each page with the ISSN - but that doesn't make it easily discoverable by automated tools. How can I make an ISSN machine readable?  There are a few ways.

Meta Elements

There are a limited list of official  names. These are extensible, and Google Scholar recommends citation_issn. Which is as simple as adding the following to your page's :




There alternatives though.

Schema.org

In recent years, Schema.org has become the dominant form for representing metadata on the web. There are two ways you can implement it:

JSON-LD

JSON Linked Data involves adding a scrap of JavaScript to your HTML, like this:




If you don't want to add a separate script, you can add the data inline using...

Microdata

The microdata specification uses the exact same data as Schema.org - but allows you to add the data directly into the web page like this:


   ...
   ISSN 1234-5678


That's probably the easiest way to do it.

Links

The ISSN registry allows you to look up any ISSN with a simple URL. Mine is at https://portal.issn.org/resource/ISSN/2753-1570.

Belt and braces

So, this is what I've ended up doing - cramming everything in all at once.


   ...
   


   ...
   ISSN 1234-5678


Any other ways?

What am I missing? Can someone smarter than I tell me that there's an easier / better / more interoperable way to do this?



Introducing DOI2HT.ML - the simple semantic citation server
@edent — Fri, 13 Nov 2020 12:51:22 +0000
Academic citations are hard. One of the joys of the Digital Object Identifier System (DOI) is that every academic paper gets a unique reference - like: 10.34053/artivate.8.2.2.

As well as always leading you to a URl of the paper, a DOI also provides lots of metadata. Things like author, publisher, ORCID, year of publication etc.

I've built a simple website that turns any DOI into a semantic HTML reference - get started at DOI2HT.ML.

Here's what it looks like:



Pop a DOI in the box and hit the button. You'll receive an HTML5 citation which has embedded schema.org microdata data.  It makes a human-readable citation and a robot-readable way for search engines to understand your citation.

It uses content negotiation to get the canonical citation, then it renders it into standards compliant HTML + microdata.

There's no tracking, no cookies, no selling your data. Just a plain HTML site - the way the web should be.

Enjoy!

DOI2HT.ML

This is a "scratch my own itch" product. I run a citations page where I track whenever I'm mentioned in academia. Feedback very welcome.



Adding Semantic Reviews / Rich Snippets to your WordPress Site
@edent — Sun, 12 Jul 2020 11:50:01 +0000
This is a real "scratch my own itch" post. I want to add Schema.org semantic metadata to the book reviews I write on my blog. This will enable "rich snippets" in search engines.

There are loads of WordPress plugins which do this. But where's the fun in that?! So here's how I quickly built it into my open source blog theme.

Screen options

First, let's add some screen options to the WordPress editor screen.

This is what it will look like when done:



This is how to add a custom metabox to the editor screen:

//  Place this in functions.php
//  Display the box
function edent_add_review_custom_box()
{
   $screens = ['post'];
   foreach ($screens as $screen) {
      add_meta_box(
         'edent_review_box_id', // Unique ID
         'Book Review Metadata',    // Box title
         'edent_review_box_html',// Content callback, must be of type callable
         $screen                 // Post type
       );
   }
}
add_action('add_meta_boxes', 'edent_add_review_custom_box');


The contents of the box are bog standard HTML

//  Place this in functions.php
//  HTML for the box
function edent_review_box_html($post)
{
    $review_data = get_post_meta(get_the_ID(), "_edent_book_review_meta_key", true);
    echo "";

    $checked = "";
    if ($review_data["review"] == "true") {
        $checked = "checked";
    }
    echo "";

    echo "";

    echo "";

    echo "Embed Book Review: 
Rating: 
ISBN: ";
}


Done! We now have a box for metadata. That data will be POSTed every time the blogpost is saved. But where do the data go?

Saving data

This function is added every time the blogpost is saved. If the checkbox has been ticked, the metadata are saved to the database. If the checkbox is unticked, the metadata are deleted.

//  Place this in functions.php
//  Save the box
function edent_review_save_postdata($post_id)
{
   if (array_key_exists('edent_book_review', $_POST)) {
        if ($_POST['edent_book_review']["review"] == "true") {
            update_post_meta(
                $post_id,
                '_edent_book_review_meta_key',
                $_POST['edent_book_review']
            );
        } else {
            delete_post_meta(
                $post_id,
                '_edent_book_review_meta_key'
            );
        }
    }
}
add_action('save_post', 'edent_review_save_postdata');


Nice! But how do we get the data back out again?

Retrieving the data

We can use the get_post_meta() function to get all the metadata associated with a blog entry.  We can then turn it into a Schema.org structured metadata entry.

function edent_book_review_display($post_id){
    // https://developer.wordpress.org/reference/functions/the_meta/
    $review_data = get_post_meta($post_id, "_edent_book_review_meta_key", true);
    if ($review_data["review"] == "true")
    {
        $blog_author_data = get_the_author_meta();

        $schema_review = array (
            '@context' => 'https://schema.org',
            '@type'    => 'Review',
            'author' =>
            array (
                '@type' => 'Person',
                'name'  => get_the_author_meta("user_firstname") . " " . get_the_author_meta("user_lastname"),
                'sameAs' =>
                array (
                    0 => get_the_author_meta("user_url"),
                ),
            ),
            'url' => get_permalink(),
            'datePublished' => get_the_date('c'),
            'publisher' =>
            array (
                '@type'  => 'Organization',
                'name'   => get_bloginfo("name"),
                'sameAs' => get_bloginfo("url"),
            ),
            'description' => mb_substr(get_the_excerpt(), 0, 198),
            'inLanguage'  => get_bloginfo("language"),
            'itemReviewed' =>
            array (
                '@type'  => 'Book',
                'name'   => $review_data["title"],
                'isbn'   => $review_data["isbn"],
                'sameAs' => $review_data["book_url"],
                'author' =>
                array (
                    '@type'  => 'Person',
                    'name'   => $review_data["author"],
                    'sameAs' => $review_data["author_url"],
                ),
            'datePublished' => $review_data["book_date"],
            ),
            'reviewRating' =>
            array (
                '@type' => 'Rating',
                'worstRating' => 0,
                'bestRating'  => 5,
                'ratingValue' => $review_data["rating"],
            ),
            'thumbnailUrl' => get_the_post_thumbnail_url(),
        );
        echo '';

        echo "";
        if (isset($review_data["rating"])) {
            echo "";
            $full = floor($review_data["rating"]);
            $half = 0;
            if ($review_data["rating"] - $full == 0.5)
            {
                $half = 1;
            }

            $empty = 5 - $half - $full;

            for ($i=0; $i < $full ; $i++) {
                echo "★";
            }
            if ($half == 1)
            {
                echo "⯪";
            }
            for ($i=0; $i < $empty ; $i++) {
                echo "☆";
            }
            echo "";
        }
        echo "";
        if ($review_data["amazon_url"] != "") {
            echo "Buy it on Amazon";
        }
        if ($review_data["author_url"] != "") {
            echo "Author's homepage";
        }
        if ($review_data["book_url"] != "") {
            echo "Publisher's details";
        }
        echo "";
    }
    echo "";
}


In index.php, after the_content(); add:

edent_book_review_display(get_the_ID());


Then, on the website, it will look something like this:



Note the use of the Unicode Half Star for the ratings.

The source code of the site shows the output of the JSON LD:


When run through a Structured Data Testing Tool, it shows as a valid review:



And this means, when search engines access your blog, they will display rich snippets based on the semantic metadata.



You can see the final blog post to see how it works.

ToDo

My code is horrible and hasn't been tested, validated, or sanitised. It's only for my own blog, and I'm unlikely to hack myself, but that needs fixing.

I want to add review metadata for movies, games, and gadgets. That will either require multiple boxes, or a clever way to only show the necessary fields.



The future of the web, isn't the web
@edent — Sun, 22 Dec 2019 12:24:46 +0000
My friends, and former employers, at the Government Digital Service have written a spectacularly good blog post "Making GOV.UK more than a website".

In it, they describe how adding Schema.org markup to their website has allowed search engines to extract semantic content and display it to a user. For example, the "Learn to drive" page has content which can appear directly in a search engine:


Even better, if you ask Siri / Google / Alexa for something, it can give an answer from an authoritative source:


This is the death of the web. Long live the web!

Why this is really important

Your information has to be where your users want to access it. Not where you want to display it.  I remember sitting in a housing benefits office, watching someone playing on their PlayStation Portable - or so I thought. On closer inspection, she was browsing the GOV.UK web pages to see what the process was for claiming benefits.  Web browsers are everywhere!

But the future is not a browser. It is a User-Agent.  It could be your search engine, smart watch, voice assistant, or something yet to be invented.

History

The web is great. But its real power was in separating content from design.


HTML for your words.
CSS for your layout.


That's a good start. But we can go one deeper. Because content isn't HTML.

Your content probably lives in a database. Whether you're running a personal blog, or an ecommerce platform, the content is actually data. You render it as HTML because that's what's easiest for humans to read on a screen.

But... not everyone is able to read a screen. Nor do they always want to.

Do we need to write custom CSS just in case our data is rendered on a smartwatch? Or a TV? Or an Internet Connected Fridge? No! The User-Agent should be able to grab the data and render it appropriately.

At the moment, we're mostly stuck in this paradigm:

Data ➡ HTML ➡ CSS ➡ Browser ➡ 👀

But because our content is just data in a database, we're not restricted to that. It can just as easily be:

Data ➡ Speech Synthesis Markup Language ➡ Alexa ➡ 👂

Too many APIs

And that is what I love about HTML + microdata / Schema.  No one is going to use your API - unless you are a megacorp. But if the data is already in your web pages, they don't have to do anything fancy.

No one is ever going to use my blog's API. But your Kindle could come across my web page, and see this recent review - embedded in it is this data:

{
    "@context": "http:\/\/schema.org",
    "@type": "Review",
    "author": {
        "@type": "Person",
        "name": "@edent",
    },
    "itemReviewed": {
        "@type": "Book",
        "name": "This Is How You Lose the Time War",
        "isbn": "9781534431003",
        "author": {
            "@type": "Person",
            "name": "Amal El-Mohtar",
            "sameAs": "https:\/\/www.goodreads.com\/book\/author\/Amal+El-Mohtar"
        },
    },
    "reviewRating": {
        "@type": "Rating",
        "worstRating": 1,
        "bestRating": 5,
        "ratingValue": 5
    }
}


And - hey presto! - it can find the book via ISBN, show you books by the same author, and display the rating I gave the book. All without needing any fancy AI or Natural Language Processing.

Your smart-fridge can find a recipe and display the steps you need to take in order to prepare the perfect moussaka.  You don't need to build an app for Samsung fridges, and another one for Smeg fridges. Just build a website and embed your data in the pages!

The future

So, I hope that the future is more data-in-the-web & more diverse User Agents.

You will have many, many User Agents - your car, your speaker, your microwave - all of them grabbing data on your behalf, rendering it, processing it, giving you information in the format which works best for you.

It will all be powered by the web, but won't be accessed by what you think of as a traditional web browser.



Add review to Goodreads from Schema markup
@edent — Tue, 10 Dec 2019 19:40:23 +0000
I write book reviews on my blog. I also want to syndicate them to Goodreads.

Sadly, Goodreads doesn't natively read the Schema.org markup I so carefully craft.  So here's the scrap of code I use to syndicate my reviews.

Goodreads API Keys

Get your Keys from https://www.goodreads.com/api/keys

You will also need to get OAuth tokens

For this documentation, I'll use the example keys - please substitute them with your own keys.

from rauth.service import OAuth1Service, OAuth1Session

# Get a real consumer key & secret from: https://www.goodreads.com/api/keys
API_KEY    = 'ABC123'
API_SECRET = 'XYZ789'

goodreads = OAuth1Service(
    consumer_key    = API_KEY,
    consumer_secret = API_SECRET,
    name='goodreads',
    request_token_url = 'https://www.goodreads.com/oauth/request_token',
    authorize_url     = 'https://www.goodreads.com/oauth/authorize',
    access_token_url  = 'https://www.goodreads.com/oauth/access_token',
    base_url          = 'https://www.goodreads.com/'
)

OAUTH_TOKEN, OAUTH_SECRET = goodreads.get_request_token(header_auth=True)
authorize_url = goodreads.get_authorize_url(request_token)
print(authorize_url)


Visit the URL printed out, and authorise the app.  Then run this to get the access tokens you need:

session = goodreads.get_auth_session(OAUTH_TOKEN, OAUTH_SECRET)
ACCESS_TOKEN = session.access_token
ACCESS_TOKEN_SECRET = session.access_token_secret


Save those tokens, we'll need them later!

Get JSON-LD from HTML page

This uses Requests and BeautifulSoup.

import requests
from bs4 import BeautifulSoup
import json
import re

review_url = 'https://shkspr.mobi/blog/2019/11/review-because-internet-by-gretchen-mcculloch/'
r = requests.get(review_url)
soup = BeautifulSoup(r.text)
pattern = re.compile(r"\"@type\":\"Review\"")
script = soup.find("script", text=pattern)
review = script.text
review_json = json.loads(review)

isbn        = review_json["itemReviewed"]["isbn"]
rating      = review_json["reviewRating"]["ratingValue"]
date        = review_json["datePublished"]:date[0:10]
description = review_json["description"] + " " + review_url



ISBN to Goodreads ID

goodreads_id = requests.get("https://www.goodreads.com/book/isbn_to_id/" + isbn + "?key=" + API_KEY).text


This will return a number - the Goodreads ID.

Post a review

The documentation for posting Goodreads reviews is a bit sparse.

goodreads_api = OAuth1Session(
    consumer_key        = API_KEY,
    consumer_secret     = API_SECRET,
    access_token        = ACCESS_TOKEN,
    access_token_secret = ACCESS_TOKEN_SECRET,
)

#   Post the review to the API
#   https://www.goodreads.com/api/index#review.create

review_data = {"book_id": goodreads_id, "review[review]":description, "review[rating]":rating, "review[read_at]":date}

response = goodreads_api.post('https://www.goodreads.com/review.xml', review_data)

print(response.text)


Setting the date

The Goodreads API is... crap. Posting the review doesn't actually add a date to the review. So you need to edit the review to post it again.  To start with, we need to get the review's ID:

import xml.etree.ElementTree as ET
tree = ET.fromstring(response.text)
review_id = tree.find("id").text
review_data = {"review[read_at]":date[0:10]}
response = goodreads_api.post('https://www.goodreads.com/review/'+review_id+'.xml', review_data)
print(response.text)


Get the code

The Python code is available on my GitLab.

But... The Goodreads API is a bit picky. ISBN lookup doesn't work very well, and bits of the API are flaky. So while this code mostly works, I don't run it that often.



Convert DOI to a HTML5 / Schema citation
@edent — Sat, 07 Dec 2019 12:51:27 +0000
This is a quick and dirty way to turn a DOI (Digital Object Identifiers for academic papers) into an HTML & Microdata citation.  I use this to power my Citations page.

Schema.org is a Microdata standard which allows machines to read your HTML and create semantic relations between documents.

Here's a minimum viable citation:


    
        
            Terence Eden
        
     
    
        Proof that P ≠ NP
    
    (2025)
    
        https://ex.doi.org/99.9999/1234
    
    
        
            Journal of Impossible Research
        
    



That says: This citation is a scholarly article which has a headline, date, and URl. It has an author who is a person with a name. It has a publisher which is an organisation with a name.

Here's a more full example, including ORCID, page numbers, etc:


    
        
            
            
                Losavio, Michael M.
            
        ,
        The Internet of Things and the Smart City: Legal challenges with digital forensics, privacy, and security
        (2018)
        Page: e23.
        
            Wiley
        
        Security and Privacy
        https://doi.org/10.1002/spy2.23
    



APIs

Sadly, CrossRef doesn't do Schema.org, so we have to use their API to get some JSON and convert it to JSON+LD.

Here's how to install their official Python library:

pip3 install --user crossref-commons


The Code

import crossref_commons.retrieval
import os
import re

# Set a friendly header
os.environ['CR_API_MAILTO'] = 'yourEmail@example.com'

reference = input("Enter a DOI: ")

# Check DOI is valid
# https://www.crossref.org/blog/dois-and-matching-regular-expressions/
regex = r"^10.\d{4,9}/[-._;()/:A-Z0-9]+$"
matches = re.search(regex, reference, re.IGNORECASE)

if matches:
    # Call the API
    data = crossref_commons.retrieval.get_publication_as_json(reference)

    # Start the citation
    citation_html = ''

    # Get all the authors
    authors = []
    for a in data["author"]:
        author_html = ''

        if "ORCID" in a:
            author_html += ''

        author_html += '' + a["family"] +', ' + a["given"] + ''

        authors.extend({author_html})

    # Add the authors to the citation
    for author in authors:
        citation_html += author
        citation_html += " & "
    # Remove the last &
    citation_html = citation_html.rstrip(' &')

    # Title and any language information
    if "title" in data:
        headline  = data["title"][0]

        if "language" in data:
            lang = data["language"]
            citation_html += ' '+headline+' '
        else:
            citation_html += ' '+headline+' '

    # Add the date
    if "published-print" in data:
        year = data["published-print"]["date-parts"][0][0]
        citation_html += '(' + str(year) + ') '
    elif "issued" in data:
        year = data["issued"]["date-parts"][0][0]
        citation_html += '(' + str(year) + ') '
    elif "created" in data:
        datetime = data["created"]["date-time"]
        year     = data["created"]["date-parts"][0][0]
        citation_html += '(' + str(year) + ') '
    elif "deposited" in data:
        datetime = data["deposited"]["date-time"]
        year     = data["deposited"]["date-parts"][0][0]
        citation_html += '(' + str(year) + ') '

    # Page number information
    if "page" in data:
        citation_html += ' page: ' + data["page"] + '. '

    # Publisher
    if "publisher" in data:
        citation_html += ''+data["publisher"]+'. '

    # Publication
    if "container-title" in data:
        citation_html += ''+data["container-title"][0]+'. '

    # DOI link
    if "DOI" in data:
        doi = data["DOI"]
        doi_url = "https://doi.org/" + doi
        citation_html += ''+doi_url+''

    # End the citation
    citation_html += ''

    print(citation_html)


Opinions about citations

There are too many citation styles. And most of them suck. I used to hate seeing "Smith (1991)" as the only reference.  Theoretically, a DOI is the only citation you need - but I discovered that some were missing from major resolvers.  And, it is probably helpful to have some human readable information to aid discoverability.

I've tried to keep to author name(s), title, year, publisher, publication, page, DOI.  That's more-or-less MLA.  But, because of the microdata, a machine can understand the citation and you can convert to your preferred style.

Or, if you wish, you can adapt this code to pump out a different citation style.

Source code on GitLab.



Use-cases wanted! Adding dietary requirements to Schema.org/Person
@edent — Mon, 02 Dec 2019 12:11:35 +0000
I want Schema.org to add dietary requirements to the Person specification. And I need your help!

Background

Schema.org is a metadata standard. You can include it on webpages to create structured, machine-readable data.

Here's a sample way of representing a Person:

{
  "@context": "https://schema.org/",
  "@type": "Person",
  "name": "Albert Einstein",
  "hasOccupation": [
    {
      "@type": "Occupation",
      "name": "Professor of Physics",
      "occupationLocation": {
        "@type": "Country",
        "name": "USA",
        "sameAs": "https://www.wikidata.org/wiki/Q30"
      }
    }
  ]
}


Hopefully easy to follow. This is a Person, they have a name and an occupation. That occupation has a name and is located in a country. That country has some linked data.

There are all sorts of properties we can associate with a Person - birth and death dates, memberships, nationality, credentials, tax ID, and even weight! See Schema.org/Person for a full list.

One which I think would be useful is a person's diet.

Diet

Schema already has the concept of a RestrictedDiet type.  It lists things like Vegetarian, Halal, Kosher, Low Salt etc.

But it only applies to MenuItem and Recipe types.  That is, I can mark up a restaurant's menu and say that this dish is Gluten Free, and that dish is Vegan friendly.

{
    "@context": "http://schema.org",
    "@type":"MenuItem",
    "name":"Potato Skins",
    "description":"Small serving of baked potato skins.",
    "offers":{
        "@type":"Offer",
        "price":"4.49",
        "priceCurrency":"GBP"
    },
    "suitableForDiet":[
        {
            "@type": "GlutenFreeDiet"
        },
        {
            "@type": "VeganDiet"
        }
    ]
}


My Use Cases

I maintain a personal contact site. I tell people my name, address, occupation, etc. I also want to inform other people that I am vegetarian.


On a social network, it might be nice to have an (optional) feature where people give their dietary preferences.
My Jewish and Muslim friends might want to automatically filter out the pork casserole recipes people post.
My address book might suggest a restaurant which caters for my guests' preferences.
An encyclopædia can show dietary restrictions of famous people.
An airline could - with permission - read your social profile to select your meal for a flight.


Sample

Here's how I think it could work:

{
    "@context": "https://schema.org/",
    "@type": "Person",
    "name": "Terence Eden",
    "restrictedDiet": "http://schema.org/VegetarianDiet"
}


That is, just add restrictedDiet as a valid property of Person.  I suppose it could be hasDiet or dietaryPreference or similar.

Your Use Cases

If you want to add your own use cases, or just think this is a good idea, please leave a comment on GitHub.com/schemaorg/schemaorg/issues/1996

schema.org – Terence Eden’s Blog

Maximally Semantic Structure for a Blog Post

Footnotes

Alice says: