Documents are the core data structure in Seed Hypermedia. Understanding how they work will help you create, update, and manage content effectively.

A Seed document is a versioned collection of content blocks. Each document has:

• An Account - The owner's cryptographic identity (z6Mk...)

• A Path - The location within that account (/docs/guide)

• A Version - A content-addressed hash of the current state

• Metadata - Title, timestamps, and custom attributes

• Content - A tree of blocks (paragraphs, headings, code, etc.)

Document content is organized as a tree of blocks, not a flat list. This allows rich nesting:

Document
├── Heading: "Introduction"
│   ├── Paragraph: "Welcome to..."
│   └── Paragraph: "This guide covers..."
├── Heading: "Getting Started"
│   ├── Paragraph: "First, install..."
│   ├── Code: "npm install ..."
│   └── Paragraph: "Then run..."
└── Heading: "Conclusion"
    └── Paragraph: "That's all!"

Headings can contain child blocks, creating sections. This structure is similar to HTML's nested elements or markdown's indented lists.

Each block has these components:

{
  "block": {
    "id": "b1a2c3d4",
    "type": "Paragraph",
    "text": "Hello, world!",
    "annotations": [...]
  },
  "children": [...]
}

• id - Unique identifier within the document

• type - Block type (Paragraph, Heading, Code, Image, etc.)

• text/code - The content (field name depends on type)

• annotations - Formatting and links within text

• children - Nested blocks (for headings and containers)

Every change to a document creates a new version. Versions are immutable - once created, they can't be modified. This enables:

• Full history - See every change ever made

• Time travel - Access any previous version

• Attribution - Know who made each change

• Integrity - Verify content hasn't been tampered with

Version IDs look like: bafy2bzace... (IPFS CIDs)

Documents have metadata separate from content:

{
  "metadata": {
    "name": "My Document Title",
    "createTime": "2026-02-06T02:54:00Z",
    "updateTime": "2026-02-06T03:00:00Z",
    "author": "z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6"
  }
}

You can also set custom attributes for domain-specific data like categories, tags, or external references.

Documents are addressed by their account and path:

hm://z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6/guides/quick-start
     └─────────────────── Account ID ────────────────────┘└───── Path ─────┘

You can also address specific versions:

hm://z6Mk.../guides/quick-start?v=bafy2bzace...

And specific blocks within a document:

hm://z6Mk.../guides/quick-start#b1a2c3d4

Every account has a root document at the empty path (/). This is your home page:

hm://z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6
# Same as:
hm://z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6/

Use your root document as an index or profile page that links to your other content.

Organize documents using path hierarchies:

/                         # Root/home document
/about                    # About page
/guides/quick-start       # Getting started guide
/guides/advanced          # Advanced topics
/reference/api            # API reference
/blog/2026-02-06/update   # Blog post with date path

Path segments are case-insensitive and should use lowercase with hyphens (kebab-case).

• Blobs & Signing - How documents are stored and signed

• Block Types - Available block types and their properties

• CLI Guide - Create and update documents programmatically