DEV Community

Cover image for The Block Structure of Podlite
Alexandr Zahatski
Alexandr Zahatski

Posted on

The Block Structure of Podlite

#webdev #writing #documentation #podlite

Podlite is a small block-based markup language that is easy to read as plain text, simple to parse, and flexible enough to be used everywhere — in code, notes, technical documents, long-form writing, and even full documentation systems.

One of the core ideas behind Podlite is its consistent block-based structure.
Every meaningful element of a document — a heading, a paragraph, a list item, a table, a code block, a callout — is represented as a block. This makes documents both readable for humans and predictable for tools.

Podlite supports three interchangeable block styles: delimited, paragraph, and abbreviated.

diagram here showing the three block styles and how they map to the same internal structure

Abbreviated blocks (=BLOCK)

This is the most compact form.
A block starts with = followed by the block name.

=head1 Getting Started
=item Install Node.js 20+
=para Podlite makes documentation predictable and easy to automate.
Enter fullscreen mode Exit fullscreen mode
  • ends on the next directive or a blank line
  • best used for simple one-line blocks
  • cannot include configuration options (attributes)

Paragraph blocks (=for BLOCK)

Use this form when you want a multi-line block or need attributes.

=for code :lang<ts>
console.log("Hello from Podlite!");
Enter fullscreen mode Exit fullscreen mode
  • ends when a blank line appears
  • can include complex content
  • allows attributes such as :lang, :id, :caption, :nested, …

Delimited blocks (=begin BLOCK … =end BLOCK)

The most expressive form. Useful for large sections, nested blocks, or structures that require clarity.

=begin nested :notify<important>
Make sure you have administrator privileges.
=end nested
Enter fullscreen mode Exit fullscreen mode
  • explicit start and end markers
  • perfect for code, lists, tables, notifications, markdown, formulas
  • can contain other blocks, including nested ones

These block styles differ in syntax convenience, but all produce the same internal structure.

Regardless of which syntax you choose:

  • all three forms represent the same block type
  • attributes apply the same way (:lang, :caption, :id, …)
  • tools and renderers treat them uniformly
  • nested blocks work identically
  • you can freely mix styles inside a document

Links

Top comments (0)