Embedded HDOC format description

I originally designed HDOC as a standalone document format. In the future, when browsers and search engines support it natively, many HTML pages could be replaced with HDOCs. In most cases, the real content is stored in a database anyway, and changing the presentation layer is trivial. The problem is that right now, neither browsers nor search engines know anything about HDOCs. If you replace your HTML pages with HDOCs today, your site basically disappears for most people.

One way around this is to serve HDOCs from separate endpoints. That lets you keep the original HTML page, but now you’re maintaining two URLs for essentially the same content. It would be much better if you could serve both the HTML page and the corresponding HDOC from a single URL. That’s exactly what the embedded HDOC format is for. It lets you embed an HDOC inside your HTML page.

Which version a person sees depends on the software they use. Most visitors will just see the HTML page. Anyone with HDOC-aware software will see the HDOC version instead.

To embed an HDOC into an HTML page, you need to do two things:

1. Mark the element containing the page’s actual content with a special class called hdoc-content.
2. Add a <script> tag with JSON content and the id hdoc-data that includes all the additional information needed to construct the HDOC locally.

Example JSON:

<script type="application/json" id="hdoc-data">
{
	"removal-selectors":".some-class,.other-class",
	"panels":{...}
	"header":{
		"h1":"The title",
		"author":"John Doe",
		"date":"October 13, 2025"
	},

	"connections":[...]
		
	
}
</script>

A client app will download the full HTML page, extract the content from the marked element, then read everything else from the JSON. With that information it can construct an HDOC—served from the exact same URL as the original HTML page.

A panels section in the JSON may look like this:

 {
  "panels":{
      "top":{
         "site-name":"My website",
         "home-url":"https://example.com",
         "site-logo":"https://example.com/icon.png",
         "links":[
            {
               "href":"https://example.com/archive",
               "text":"Archive"
            }
         ]
      },
      "side":{
         "side":"left",
         "ipage":"https://example.com/interactive-page",
         "comments":{
            "url":"http://exmple.com/json-comments/?post=19",
            "title":"Comments",
            "empty":"No comments yet"
         }
      },
      "bottom":{
         "sections":[
            {
               "title":"Section 1",
               "links":[
                  {
                     "href":"https://example.com/about",
                     "text":"About us"
                  }
               ]
            },
            {
               "title":"Section 2",
               "links":[
                  {
                     "href":"https://example.com/contacts",
                     "text":"Contacts"
                  }
               ]
            }
         ],
         "bottom-message":"This is a bottom message"
      }
   }
}

A connections section may look like this:

{
"connections":[
   {
      "url":"https://example.com/dates",
      "title":"Dates",
      "hash":"d79712",
      "flinks":[
"i:769;l:256;h:ff3d6e;e:Vy4=_i:0;l:8;h:e68ee0;e:RXM=",
"i:1278;l:16;h:512358;e:THM=_i:35;l:11;h:1e5fac;e:Y3M="
]
   },
   {			   
      "url":"https://example.com/collage",
      "title":"Collage",
      "hash":"54dfa4",
      "flinks":[				 
"i:2029;l:97;h:72bcf5;e:RS4=_p|x:79.772;y:142.467;r:0.147",
"i:2423;l:79;h:7f7a20;e:Qi4=_p|x:81.226;y:142.1;r:0.147"
]
   }
  ]
}

The "removal-selectors" field is useful if some plugin has polluted your content with unnecessary elements. You can list selectors that HDOC-aware software should remove from the final content.

You don’t need the metadata field if all you want is the page title. The client software will automatically use document.title from the HTML page.

There may be other fields not described here. This format is still a draft, and I’ll make this and the other data formats more official in the near future.

My WordPress plugin already supports embedded HDOCs. Once installed, it handles everything for you: marking the content, generating the JSON, and injecting it into the page. If you want, you can also define site-wide information in the plugin’s settings, and it will automatically include it in the JSON.

The best part is that your site looks exactly the same as before to most people. You don’t need extra endpoints or duplicate pages just to make HDOCs available.