DEV Community: Alexandr Zahatski

Podlite 2.0 released

Alexandr Zahatski — Fri, 29 May 2026 09:57:15 +0000

Podlite 2.0 is tagged. Podlite is a block-based markup language built around typed blocks and explicit boundaries — the same document is meant to read cleanly whether a person or a tool parses it. This release adds eight blocks and attributes and changes two parsing rules.

The specification is at podlite.org/specification; the full changelog sits inside the spec under =head2 v2.0.

The Coming in Podlite 2.0 article from the review window covered what is new in depth. This post focuses on what to do now: how to migrate existing documents and where to find the rest. For most documents the answer is short — a well-formed v1.0 document renders unchanged under v2.0.

Breaking changes

Two changes parse differently than before. Neither touches a well-formed document — if anything needs updating, it is a parser, not your text.

Legacy attribute syntax removed

A few outdated string attribute formats are gone. The bracket form (:key<value>) and the parenthesized form (:key('value')) remain.

If a document uses the current syntax, nothing changes.

=include is now a directive

=include always behaved like a directive, but the spec previously listed it under block types. Tokenization rules differ between directives and blocks. Parsers built against the v1.0 spec must move =include into the directive dispatch path alongside =config and =alias.

For document authors: no change. =include still takes the same syntax and produces the same output. The reclassification matters only for tools that build ASTs.

New features at a glance

Eight additions ship in v2.0. Existing documents render unchanged.

=boundary: a typed section divider. Renders as a horizontal rule, exposes structure to tools.
=set: pre-configure attributes for the next block. Multiline values, inline markup, lexical scope.
G<> + :masked: content masking. Inline mark or whole-block attribute; hidden by default, revealed by render condition.
=data-table block: renders CSV or TSV as a table. Three source forms (inline body, external :src<file:X>, =data reference). :columns selects projection, :rename{} overrides display names.

  =begin data-table :caption('Quarterly sales') :mime-type<'text/csv; header=present'>
  quarter,product,revenue
  Q1,Widget,12000
  Q1,Gadget,18000
  Q2,Widget,15400
  Q2,Gadget,21200
  =end data-table

Extended :mime-type syntax: accepts MIME parameters per RFC 6838, with header=present|absent for CSV/TSV header indication per RFC 4180 §3.
Markdown fenced code block attributes: the string after the language tag is now parsed as Podlite attributes.
Per-link configuration attributes for L<>: settings stay with the link rather than scattering through prose.
=table error recovery: explicit warnings for malformed rows (cell count mismatch, mixed separators), graceful fallback instead of silent corruption.

For full examples and rationale, the Coming in Podlite 2.0 article is still accurate.

Where to go from here

Spec: podlite.org/specification
Changelog: spec v2.0 section, Keep a Changelog format
GitHub release: podlite-specs/releases/tag/v2.0
Discussions: podlite-specs/discussions
Editor: pod6.in for trying the new directives live

Coming in Podlite 2.0

Alexandr Zahatski — Thu, 07 May 2026 18:00:03 +0000

The spec branch for Podlite 2.0 has landed in a pull request. The final tag goes up once the review window closes. If you build parsers or ship documents in Podlite, this is the time to read the diff and push back.

Why a major bump? A few real breaking changes (mostly legacy string-attribute syntax that nobody should have been writing anyway), plus five big new features. Bundling them means one parser-side update instead of five spread over time.

Two new directives

`=boundary` — section dividers with semantics

A divider with semantics. It renders as a horizontal rule, but the parser sees a typed block. A tool building a table of contents, page-splitter, or chapter-navigator knows exactly where one section ends and the next begins. The optional :caption attribute describes the transition (=boundary :caption('Part Two')).

`=set` — per-block attribute assignment

Pre-configure attributes for the next block. Multiline values via continuation lines, inline markup inside attribute values, and lexical scope per file. The mechanism is useful when an attribute value is too long to sit on the directive line, or when you want to factor common attributes out of repeated blocks.

Content masking

Accept the terms to read G<the full case study>.

=begin para :masked
Premium analysis. Hidden until the reader signs in.
=end para

G<> masks inline content, :masked masks whole blocks. The renderer hides the content by default and shows it once a condition is met — terms accepted, sign-in done, draft mode on. Use it for content released after agreement (T&C, paywall, age gate). Use it for credentials in code samples, PII in case studies, or unreleased details that should live in the source file but stay out of the rendered output.

This hides content at render time. It is one layer of defense-in-depth, not a replacement for source-file access controls or secret-management tools.

Smarter attributes

Markdown fenced code blocks accept attributes

javascript :line-numbers :caption('Example')
const x = 1;

The string after the language tag is now parsed as Podlite attributes. Previous behavior (raw meta string) is preserved when no attribute syntax is present.

`L<>` takes per-link attributes

L<docs|https://example.com :rel<external> :class<button>>

Settings stay with the link, not scattered through surrounding prose. Existing plain L<text|url> works unchanged.

`:mime-type` accepts MIME parameters

=begin data :key<planets> :mime-type<'text/csv; header=present'>
  name,radius_km,moons
  Mercury,2440,0
  Venus,6052,0
  Earth,6371,1
  Mars,3390,2
=end data

=for data-table :src<data:planets> :caption('Inner planets')

The header=present|absent parameter (per RFC 4180 §3) tells the renderer to treat the first row as column labels in =table data:X. The MIME parameter syntax follows RFC 6838.

CSV and TSV tables with column projection

=for data-table :src<file:./planets.csv>
=    :columns<name,radius_km>
=    :rename{radius_km=>Radius}

A new =data-table block renders CSV or TSV as a table. Three source forms: inline body between =begin data-table and =end data-table, external file via :src<file:X.csv>, or referenced =data block via :src<data:key>.

:columns<> selects which columns appear in output and in what order (names or 1-based indices). :rename{} overrides column display names — sparse hash, only listed columns get overrides.

:mime-type is inferred when possible: from file extension for file: sources, from HTTP Content-Type for remote sources, inherited from the referenced block for data: sources. Explicit declaration is required only for inline body and when inference fails.

Why a separate block? CSV/TSV bodies need verbatim parsing different from =table's formatted-row grammar. Putting two grammars behind one typename would force the parser to read attributes before picking a code path.

Reclassifications and fixes

=include is now formally a directive, consistent with =config and =alias. :folded got a tighter definition. =table has explicit error recovery rules. Malformed rows (wrong cell count, mixed separators) now emit a warning and continue, instead of dropping the parser into silent fallback.

Removed: a few outdated string attribute formats. If you write the current syntax, nothing changes.

Read the diff before the tag lands

Pull request: podlite-specs#26
Branch: release/v2.0
Discussions: podlite-specs/discussions

If something looks off — a broken example, ambiguous wording, an edge case the spec doesn't cover — this is the window. Feedback after the tag is much harder to act on.

Podlite Desktop 0.7.0 — smart lists, code folding

Alexandr Zahatski — Mon, 30 Mar 2026 16:59:08 +0000

Podlite Desktop 0.7.0 is out. A free, open source editor for Podlite markup — a block-based language that extends Markdown with diagrams, formulas, tables and task lists.

What's new in 0.7.0

smart list continuation on Enter with checkbox/numbering inheritance
Tab / Shift+Tab for nesting levels
code folding for =begin/=end and =head sections
collapsible blocks via :folded attribute
input latency reduced from 860ms to near-zero
session restore (cursor, scroll, folds, view mode)

Available on macOS, Windows, Linux.

Download from GitHub · Mac App Store · Microsoft Store · Snap Store

Site: podlite.org

One command to add structured markup to your AI agent

Alexandr Zahatski — Wed, 11 Mar 2026 21:41:26 +0000

I've been keeping a personal knowledge base for years. Notes, specs, decisions, journal entries — all in plain text files. When AI agents became part of my workflow, I started using them to write structured documents: RFC drafts, revision histories, typed notes with metadata. It worked well. Until I closed the session.

The next agent would open the same file and start from scratch — not because it forgot, but because the file gave no structure to hold onto. That's when I started looking at the format, not the model.

The problem I kept running into

My knowledge base has hundreds of files. An agent can read them, but reading isn't the same as understanding the shape of the file. Is this a journal entry or a spec? Is this draft published or scheduled? When was it written?

Plain text doesn't answer those questions. Markdown frontmatter gets you partway — but it's a convention, not a contract. Tools may or may not parse it, and agents that haven't been told what to look for usually don't. When I asked an agent to "write a blog post and schedule it for next Thursday," it produced great prose and put a date somewhere in the text. My publishing pipeline saw nothing.

The problem wasn't the agent's writing. The problem was that the file had no machine-readable structure. The agent had nowhere to put the metadata so that both humans and downstream tools could reliably find it.

What Podlite gives you

Podlite is a markup language built around explicit, typed blocks. Every block has a declared type, and blocks can carry named attributes — structured metadata that travels with the content.

Here's what a blog post looks like when an agent creates it:

=begin pod :pubdate('2026-03-12 10:00:00') :type('page') :publishUrl('/blog/podlite-skills')

=TITLE One command to add structured markup to your AI agent

Content written by the agent...

=end pod

The :pubdate, :type, and :publishUrl attributes aren't decorative. They're fields — any parser or tool that reads Podlite can access them directly, without guessing where in the prose to look.

Podlite natively includes Markdown, so you don't throw away existing files or habits. You can use Markdown syntax inside Podlite blocks without any changes. The structure layer sits on top; the content layer stays familiar.

How this plays out in practice

I ask Claude Code to draft a blog post about a recent technical decision. It creates a .podlite file with :pubdate set to next Wednesday and :publishUrl matching the slug I described. The prose is good. The metadata is correct. I close the session.

On Tuesday, I open a new session and ask a different agent to review the post and push the publish date back a week — I want more time to add a code example. The agent opens the file, reads the block header, finds :pubdate, changes the timestamp. That's it.

Worth slowing down on: the second agent didn't need context from the first session. The file itself carried the instructions. :pubdate is not a comment or a prose sentence — it's a structured field that any agent, parser, or tool can read without guessing. What acts on it depends on your setup — in my case a publishing pipeline that scans the folder and schedules based on the attribute. But the attribute is readable by anything.

This is the difference between "metadata mentioned in the file" and "metadata in the file."

Installing podlite-skills

npx skills add podlite/podlite-skills

This adds Podlite support to your AI agent environment — Claude Code, GitHub Copilot, Cursor, Codex CLI. After installation, the agent understands Podlite block syntax, attribute conventions, and how to create well-formed structured documents.

No configuration file to edit. No extension to install separately. The skill installs, and the agent knows the format. Even without a custom pipeline, you get files where an agent consistently puts type information and metadata in the same place — which means the next agent (or the next you, in six months) can read the file and know exactly what it is and what state it's in.

What I actually use it for

Three categories got noticeably better after switching:

Blog posts and RFC drafts — :pubdate, :status, :type mean any agent can pick up where another left off without me re-explaining the document's state.

Decision logs — typed blocks mean I can query "all decisions made in Q1" without parsing prose.

Specs with revision history — explicit block structure makes diff-reading much easier for agents doing review passes.

The files are still plain text. The agent still writes prose. The difference is that now the output holds its shape between sessions — metadata stays where it was put, structure stays parseable, and any tool or agent that opens the file later starts with something to work with rather than nothing.

If you're already using an AI agent for writing or documentation, this is a one-minute install:

npx skills add podlite/podlite-skills

The podlite-skills repository has the full list of supported blocks and attributes.

The Block Structure of Podlite

Alexandr Zahatski — Fri, 05 Dec 2025 08:14:04 +0000

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.

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.

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!");

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

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

Podlite Desktop Editor 0.6.1 is out

Alexandr Zahatski — Sat, 01 Nov 2025 10:51:12 +0000

Just released a new version of Podlite Desktop Editor - a free markup editor that works with Markdown and extends it with some pretty useful features.

What's Podlite?

Think of it as Markdown++. All your standard Markdown works via =markdown blocks. It's block-oriented, so everything stays clean and readable. Check out the Podlite Quick Tour: https://podlite.org/quick-tour

What's new in 0.6.1

Rebuilt the editor from scratch with updated libraries. Here's what changed:

Syntax highlighting that actually works well
Inline formatting: B<bold>, I<italic>, C<code>, L<links>, O<strikethrough>
Click links with Cmd/Ctrl to open them
Link to other files with file: schema - they open in new windows
Text search (finally!)
Fixed a bunch of window resize bugs
macOS Tahoe support

You can toggle between half-screen and full-screen preview with keyboard shortcuts.

Download

Available free on all platforms:

Github releases: https://github.com/podlite/podlite-desktop/releases
Microsoft Store, Snap Store, Mac App Store

Try the web version first if you want: https://pod6.in

Full details: https://podlite.org/2025/11/1/1/podlite-desktop-editor-0-6-1-released

Source code: https://github.com/podlite/podlite-desktop

📝 Inline text formatting in Podlite editor

Alexandr Zahatski — Sun, 26 Oct 2025 15:30:09 +0000

Podlite supports rich inline text formatting within paragraphs and table cells:

✨ Supported Formatting Codes

Code	Description	Example	Result
`B<>`	Bold text	`B<important>`	important
`I<>`	Italic text	`I<emphasis>`	emphasis
`C<>`	`Code/monospace`	`C<function()>`	`function()`
`L<>`	🔗 Links	`L<https://example.com`\|`click here>`	click here
`O<>`	~~Strikethrough~~	`O<deleted text>`	~~deleted text~~

These formatting codes can be combined within any paragraph or table cell to create rich, formatted content.

Podlite is a lightweight block-based markup language designed for flexibility and ease of use.

Web editor with Podlite markup language syntax highlighting is here!

Alexandr Zahatski — Mon, 13 Jan 2025 17:39:25 +0000

You can check it out at pod6.in!

It was included as part of Podlite v0.0.45.

Podlite: Powering Up Knowledge Management

Alexandr Zahatski — Fri, 04 Oct 2024 06:00:00 +0000

Hey 👋 Exciting news from the Podlite project! Podlite keeps evolving, opening up new possibilities for knowledge management.

Check out this list of recent achievements in the Podlite-web package for creating web projects:

What's New? 🚀

Plugin Support: Extend functionality easily
Global Term Index & Full-Text Search: Find info fast
React Integration: Build dynamic, interactive pages
Automatic ToC & Breadcrumbs: Improve navigation
Code Syntax Highlighting: Make your docs shine

See It in Action 👀

The Raku Knowledge Base v1.0 (Artistic 2.0 License)

Check out The Raku Knowledge Base - a comprehensive, open-source knowledge base for the Raku programming language built with Podlite-web.

Raku (formerly Perl 6) is a powerful, multi-paradigm language. This knowledge base aims to make it more accessible and easier to learn.

Key Features:

📚 Official Raku documentation
📦 User module docs
💻 Code example collections
🔍 Full-text search
🧭 Easy navigation with breadcrumbs
🔗 Auto-generated term index

You can read more about the The Raku Knowledge Base in detail in the official announcement on the Podlite website podlite.org/a5ZK1.

Get Involved 🤝

🌟 Star the repo: https://github.com/zag/raku-knowledge-base
🐛 Report issues: https://github.com/zag/raku-knowledge-base/issues
🛠️ Contribute: PRs welcome!

Use Podlite for your next documentation project!
Let me know what you think or if you have any questions!

Happy coding! 💻✨
thank you!

Excited to announce that Podlite's TypeScript implementation now supports formulas! 🧮✨

Alexandr Zahatski — Mon, 27 May 2024 08:12:11 +0000

I'm excited to announce that podlite now supports formulas!

You can enter formulas using the code F<> and the block =formula.

Within the =markdown block, use $...$ for inline formulas and $$...$$ for display formulas.

Example on pod6.in

For more information, see LaTeX/Mathematics in Wikibooks.

thank you!

Podlite v1.0 released: A lightweight block-oriented markup language for organizing knowledge

Alexandr Zahatski — Tue, 23 Apr 2024 20:03:08 +0000

What is Podlite?

Podlite, a lightweight block-oriented markup language that's all about flexibility and ease of use.

Unbound by any specific domain, programming language, or concept, Podlite stands out as a universal markup language
In addition, the support for Markdown markup as a standard block adds convenience and allows for the use of familiar syntax for text formatting
It's perfect for documentation, educational materials, blogging, and much more for organizing knowledge.
One of the key features of Podlite is its extensibility. This allows for defining unique and domain-specific blocks and expanding the language's functionality according to the requirements of your project.
The Podlite specification is published under the Artistic license 2.0.

Key Features of Podlite

Block-based structure: At the core of Podlite is the concept of "blocks," which are the fundamental units of any document. These blocks can have defined attributes and support the inclusion of rich content.
Rich linking capabilities: Podlite allows blocks, terms, definitions to be linked with various types of relationships, enhancing the interconnectivity and navigability of your documents.
Support for formulas and Markdown: Whether you need to insert complex mathematical formulas or prefer the simplicity of Markdown, Podlite has you covered. It seamlessly integrates both, giving you the flexibility to choose how you want to write.
Extensible and customizable: Extend Podlite with custom blocks and inline codes, tailoring the language to meet your specific needs.

Podlite v1.0 Release Notes

Podlite has introduced a range of new features designed to enhance the flexibility and usability of the markup language:

Customization and Extensibility

Refactoring of Custom blocks: Enhanced customization through refactored named custom blocks.
Inline Markup extension: M<> now extends inline markup features, allowing for more expressive text formatting.

Processing and data handling

Markdown support: The `=markdown block is now a standard block. Integration of a new markdown mode for the parser.
MIME type specification: Added :mime-type attribute for =include and =data blocks, facilitating better handling of diverse data types.
Data schema introduction: Implemented data: schema for use in =picture and =table blocks, simplifying data embedding.
Embedding binary data: Support for embedding binary data directly into documents with :filename and :encoding attributes in =data blocks.
CSV tables: Capability to render tables directly from CSV files with the enhanced =table block.

Content Structuring and Navigation

Selectors: Introduced selectors for dynamic content interaction and manipulation.
Comprehensive TOC: Enhanced =toc block for generating detailed tables of contents.
Including external content: New =include block for incorporating external files and documents seamlessly.
Advanced table formatting: New =row and =cell blocks with :header, :rowspan, and :colspan attributes for intricate table designs.
Additional attributes for linking: Addition of :id, :caption, and :lang attributes to enrich document metadata and accessibility.
Contextual backlinks: W<> for creating contextual backlinks, enhancing document navigation and reference capabilities.
Foldable content: New :folded attribute to toggle visibility of content, and :folded-levels for nested visibility control in table of contents (TOC) blocks.

Document Presentation Enhancements

Notification blocks: Introduced notification blocks with a :notify attribute, improving interactivity within documents.
Task lists: Introduction of task lists with the =item block and a :checked attribute to manage to-do items effectively.
Mistake marking: Introduced O<> for highlighting and marking mistakes, useful in educational and review settings.
Text positioning: New attributes J<> for justifying and H<> for horizontal positioning of text.
Emojis: Added support for emojis with E<>, enriching the expressiveness of documents.
Picture insertions: New features in the =picture block and P<> for improved image handling.
Mathematical formulas: Enhanced support for complex mathematical formulas with =formula and F<>.

Deprecated/removed

With the introduction of new functionalities, certain features have been deprecated or removed to streamline Podlite:

P<toc:> due to =toc block,
P<man:>, P<doc:> due to =include block,
:margin attribute, =encoding directive, Declarator block been removed due to redundancy.
Contextual aliases, the =finish directive, and markers in comments, P<> - placement links, :formatted attribute, :like attribute have been removed due to redundancy and enhancements in other areas.

Summary of Release

This release of Podlite introduces significant enhancements aimed at improving the flexibility, customization, and user interaction of the markup language. With the addition of new blocks, attributes, and support for rich media, Podlite is better equipped to handle a variety of documentation needs.

Concurrently, the deprecation and removal of certain features have simplified the toolset, reducing overlap and enhancing user experience. These changes reflect a commitment to the continuous improvement of Podlite, ensuring it remains a versatile and powerful tool for content creators.

Feedback and Contributions

Feedback is encouraged and can be provided through Github Discussions. This input is crucial for the ongoing development and enhancement of Podlite.

Thank You!

Find out more:

Specification : https://github.com/podlite/podlite-specs, [in html format]
Website: https://podlite.org
Web playground: https://pod6.in
Github: https://github.com/podlite ⭐️

Stay tuned for more updates and happy documenting!

Introducing Podlite, a lightweight block-based markup language

Alexandr Zahatski — Wed, 21 Feb 2024 08:20:54 +0000

Hey everyone! 🚀

I'm excited to introduce a new markup language called Podlite. It's designed to make documentation, blogging, educational materials, and much more, a breeze to create and manage.

Key features of Podlite include:

Blocks as the basic unit: Each document is built from blocks, which are the basic units that can have their own defined attributes.
Flexible linking: Link blocks together in various relationships.
Formula support: Perfect for academic and scientific documentation.
Markdown support: Love Markdown? Podlite does too. It includes a standard block for Markdown, so you can switch modes seamlessly.
Rich content support: Tables, images, table of contents, and all sorts of lists are all supported.
Extensibility: Extend Podlite with your own custom blocks and inline codes to fit your needs

Podlite doesn't adhere to any specific programming language. This allows it to be embedded in any programming language that supports block-level comments, or multi-line comments.

For example, in JavaScript:

/*
=head1 Documentation

=begin Mermaid
graph LR
        A-->B
        B-->C
        C-->A
        D-->C
=end Mermaid
=begin markdown

# header

 * text
 * text

=end markdown
*/

open this sample at pod6.in

Blocks can be represented in three equivalent forms: delimited style, paragraph style, and abbreviated style.

=begin table :caption<Summary>
  Constants           1
  Variables           10
=end table

=for table :caption<Summary>
  Constants           1
  Variables           10

=table
  Constants           1
  Variables           10