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.

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.

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?



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?



Different ways to do separators in horizontal text
@edent — Mon, 16 May 2022 11:34:52 +0000
Quite often on the web, you'll see a set of "things" with a separator between them.  For example, at the top of this post, you'll see

Thing 1 | Something Else | Another Thing.

This provides clear visual separation between logical groups. But there are a couple of problems. Firstly, the separator character may not be interpreted correctly by screen readers. They may read out "Vertical Pipe", which isn't very user friendly. Similarly, robots may not attach the correct semantics to the separator. Which is a problem if you're trying to do machine learning on text.

HTML and CSS are about the separation of content and style. So let's examine the ways we can provide a better way to do separators.

Hide Them

I think that this is the least satisfying method.

| Thing 1 | Something else


The aria-hidden tag hides the content from accessibility software. It is specifically designed to remove purely decorative items. But, because the separators are simply removed, the text runs together. That's a problem for screen readers.

CSS Borders

This is another popular way to visually distinguish groups.

span {
   border-right: solid #000 1px;
}


Thing 1 Another thing


You can style the CSS however you like. Depending on your layout, you may need to use :not() on the last element to prevent an unnecessary separator.

But, again, there's no way for a screen reader or robot to know that the content is supposed to be distinct from each other.

⋮:before and ::after?

Similarly, the ::before and ::after selectors can be used to add content before/after an element:

span::after {
   content: " | ";
}


Thing 1 Another thing


Abuse the  element?

This is a bit wacky. The 
 element is a - somewhat - outdated way to provide a sectioning break by drawing a horizontal line. But it is accessible in CSS. By changing its rotation and width, it makes a passable vertical separator!

hr {
   rotate: 90deg;
   width: 1em;
}


Thing 1  Another thing


It can be a bit tricky to get the styling just right - but it will effectively separate logical groups.

List styling

I like using lists for things like this. It groups the items together and provides a logical "block" that either a human or robot can interpret or skip.

Here's a baroque method to make a list horizontal and to replace the content of the bullet.

#hz > li::before {
    display: list-item;
    content: "";
    position: absolute;
    margin-inline-start: -.5em;
}
#hz > li {
    display: inline-block;
    list-style-type: "|";
    padding-right: 1em;
}
#hz > li:first-child {
    list-style-type: "";
}



    Thing 1
    Another thing



That removes all the bullets. Then replaces every one except the first with a pipe spaced back a little from the text. And lays the list out horizontally.

If you want to change the colour or position of the bullet, you can use ::marker instead.

Mix And Match

My preferred way is to use 
, remove the bullets, and then style a border on the left - except for the first one.  This keeps the semantics of the list, and is a relatively simple piece of CSS.

#hz > li {
    display: inline-block;
    border-left: solid #000 1px;
    padding: 0 1em 0 1em;
}
#hz > li:first-child {
    border: none;
}



    Thing 1
    Another thing



Is there a best way?

No, it is a matter of personal taste and appetite for complexity.  My "strong opinion weakly held" is that semantic HTML is nearly always preferable to just chucking stuff in a load of >s and 
s. It makes the content easy to understand if you're browsing without CSS, or if you're a robot trying to understand the world.

Similarly, I think simple CSS is better than complicated CSS. Something small and human-readable is always going to be easier to understand and manage in the future.

But, if you think I'm wrong - or know a better way to lay things out - please let me know in the comments.



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.



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.

semantic web – Terence Eden’s Blog

Maximally Semantic Structure for a Blog Post

Footnotes

Alice says: