Reinventing the Web

HDOC format description

HDOC stands for ‘hypertext document’. It is a static format which means you can’t add a script to it. You can use CSS classes from a list of predefined classes, but you can’t define your own CSS classes or use inline CSS.

METADATA

HDOC has metadata section that servers the same purpose as head section in a regular HTML file. Inside of it it may have a <title> tag. Other things that may go into metadata section are not yet defined.

<hdoc>
    <metadata>
        <title>Title of my post</title>
    </metadata>
</hdoc>

CONTENT

While regular html file puts all visible content into a <body> tag, HDOC has two tags with visible content: <header> and <content> (a <footer> may be added in the future). Inside the header you can add the visible title of the page and some information like author name and publication date. Over time more options will be added to that list. Which ones of them are actually shown will be determined by client apps.

The content of the page is included as HTML inside content section. Technically it is possible to include the title into the content section and omit the header section, but it’s not recommended, because you may want to change it in the future and that can break floating links on your page. Try to not make any changes unnecessarily to the content. Note how the content starts right after the opening content tag. It’s a good rule to follow, especially if you edit your source code manually.

<hdoc>

    <metadata>
        <title>Title of my post</title>
    </metadata>

    <header>
        <h1>Title of my post</h1>
        <author>Me</author>
        <date>October 15, 2025</date>
    </header>

    <content><p>This is a paragraph.</p></content>

</hdoc>

PANELS

Optionally HDOC may have panels section. It is responsible for top and bottom panels which are standardised and will look the same on all websites. You as an author can only specify main logo or website name, and a list of links. It may also contain link to a paired web page (if some interactivity is needed) and/or a link to comments in JSON format. Paired web page or a list of comments will appear on the side panel.

Root Element: <panels>

Child Elements:

  1. <top> (optional): Defines the top panel of the page.
  2. <side> (optional): Defines the URL of a page that will be shown on the side of the main document.
  3. <bottom> (optional): Defines the bottom panel of the page.

Child Element: <top>

Defines the top section of the webpage.

Child Elements:

  1. <site-name>(optional): Represents the site name.
    • Attributes:
      • href (optional): URL to navigate to when the site name is clicked.
    • Content: The text of the site name.
  2. <logo>(optional): Represents a site logo.
    • Attributes:
      • src (required): URL to the logo image.
      • href (optional): URL to navigate to when the logo is clicked.
  3. <a>(optional, multiple): Represents a hyperlink in the top panel.
    • Attributes:
      • href (required): URL of the hyperlink.
    • Content: The text of the link.

Child Element: <side>

Defines a side panel of the webpage, typically used for comments section.

Attributes:

  • side(optional): Specifies which side the panel appears on.
    • Values:
      • "left": The panel is on the left side.
      • "right" (default): The panel is on the right side.

Child Elements:

Child element: <comments>

Contains URL of a list of comments in JSON format.

Attributes:

  • title(optional): Specifies the title that goes above the comments section.
  • empty (optional): Specifies the message that will be shown if there are not comments yet.

Child element: <ipage>

Contain URL of the paired interactive page.

Content:

  • The URL of webpage to be displayed in the side panel.

Child Element: <bottom>

Defines the bottom section of the webpage.

Child Elements:

Content: The text of the message.

<section>(optional, multiple): Defines a section within the bottom panel.

Attributes:

title (optional): The title of the section.

Child Elements:

<a>(optional, multiple): Represents a hyperlink in the section.

Attributes:

href (required): URL of the hyperlink.

Content: The text of the link.

<bottom-message>(optional): Defines a message at the bottom of the panel.

Example:

<panels>
    <top>
        <site-name href="https://google.com">hello   website</site-name>
        <logo src="https://mywebsite.com/wp-content/uploads/2024/12/logo.png" href="https://mywebsite.com"/>
        <a href="https://mywebsite.com/about">About</a>
        <a href="https://mywebsite.com/contacts">Contacts</a>
    </top>
    <side side="left">
<comments>https://mywebsite.com/json-comments?post=1</comments>
<ipage>https://mywebsite.com/some-page</ipage>
</side>
    <bottom>
        <section title="About">
            <a href="https://mywebsite.com/me">About me</a>
            <a href="https://mywebsite.com/contacts">Contacts</a>
        </section>
        <bottom-message>All rights reserved 2025</bottom-message>
    </bottom>
</panels>

Some notes on using <panels> section.

All panels – <top>, <side>, <bottom> – are optional.

You should use either <site-name> or <logo> but not both.

COPY-INFO

Optional section that is used only when HDOC is a copy of some other HDOC in which case this section is required.

This section is currently not supported by LZ Desktop, but will be in the future.

Child Elements:

<source>(required, multiple): A URL of the source page. If hdoc represents a copy of a copy of some hdoc, then multiple source tags must be used. In general you should avoid making copies of copies if the original document is available. But if its unavailable and you have to make a copy of a copy, using multiple source tags allows us to save the history of the document.

Attributes:

  • copied-at (required): An ISO 8601 timestamp of the moment when the copy was made. For example (UTC), 2025-01-01T12:00:00Z or (with Timezone Offset) 2025-01-01T12:00:00+02:00

<media-mappings>(optional). This element represents a collection of mappings for media files, allowing you to replace old URLs with new ones. Contains one or more <m> elements, each defining a mapping between an old URL and a new URL.

Child Elements:

<m>: Represents a single mapping.

<old>: The original URL of the media file.

<new>: The updated URL of the media file.

<media-mappings> 
<m>    
    <old>https://example.com/images/image1.jpg</old>  
    <new>https://mywebsite.com/images/image1.jpg</new> 
</m> 
<m> 
    <old>https://example.com/images/image2.png</old> 
    <new>https://mywebsite.com/images/image2.png</new> 
</m> 
<m> 
    <old>https://example.com/images/image3.svg</old>  
    <new>https://mywebsite.com/images/image3.svg</new> 
</m> 
</media-mappings>

Since section is currently not supported, the details may change when the support is finally implemented.

CONNECTIONS

This is an XML structure that contains information about documents the current document wants to connect to as well as floating links that connect those documents with the current documents.

Connections section will be supported by all three document types: HDOC, CDOC, and SDOC. For that reason its description is on a separate page.

CONNECTIONS format description.

Note on parsing HDOCs

HDOC consists of XML and HTML content. First HTML should be extracted using regular expressions (HTML is only included in the content section. H1 tag in the header is an XML tag). Then XML and HTML can be parsed separately. Text in H1 should not contain any html tags. If it does, they should be stripped away.

Format update notice

HDOC format was changed drastically on October 15, 2025. Since I haven’t really promoted my app yet, currently nobody uses it but me, so I can make big changes.

More posts