Every piece of content in Seed Hypermedia has a permanent, cryptographically-grounded address. The hm:// URL scheme provides a universal way to reference documents, specific versions, and even individual blocks — independent of any server or domain name.

Seed Hypermedia uses a custom URL scheme that encodes identity directly into the address. Unlike HTTP URLs that depend on domain ownership, hm:// URLs are self-certifying — the address itself proves who created the content.

hm://<account-id>/<path>?v=<version>#<block-ref>

Each component serves a specific purpose:

• hm:// — The protocol scheme, identifying this as a Hypermedia URL

• account-id — A z6Mk... public key identifier (who owns the content)

• path — Hierarchical document path within the account's space

• ?v=version — Optional version CID pinning to a specific state

• #block-ref — Optional fragment pointing to a specific block

The account ID is the most important part of an hm:// URL. It's a multibase-encoded Ed25519 public key, always starting with z6Mk. This means:

• Permanent — The ID never changes because it IS the cryptographic key

• Self-certifying — Anyone can verify content was signed by the account owner

• Decentralized — No registry or authority assigns these IDs

• Globally unique — Collision probability is astronomically low

# Example account ID
z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6

# This IS the public key, base58btc-encoded with a multicodec prefix
# z = base58btc, 6Mk = Ed25519 public key codec

The key derivation follows path m/44'/104109'/0' where 104109 is 'hm' in ASCII — a deliberate nod to the Hypermedia protocol baked into the cryptography itself.

Paths organize documents hierarchically within an account's space, similar to filesystem paths or URL paths on the web.

# Root document (account home page)
hm://z6Mk.../

# Top-level document
hm://z6Mk.../getting-started

# Nested paths
hm://z6Mk.../guides/publishing
hm://z6Mk.../concepts/urls
hm://z6Mk.../reference/http-api

Path rules:

• Use URL-safe characters: lowercase letters, numbers, and hyphens

• Hierarchical nesting is supported to arbitrary depth

• Each path segment creates a navigable level in the document tree

• The root path (/) is the account's home document

Paths also support special view terms for different perspectives on a document:

# View activity feed for a document
hm://z6Mk.../guides/publishing/:activity

# View discussions/comments
hm://z6Mk.../guides/publishing/:discussions

# View collaborators
hm://z6Mk.../guides/publishing/:collaborators

# View directory listing (child documents)
hm://z6Mk.../guides/:directory

Every document change produces a new version identified by a CID (Content Identifier). You can pin a URL to a specific version using the ?v= query parameter.

# Latest version (default)
hm://z6Mk.../concepts/urls

# Explicit latest flag
hm://z6Mk.../concepts/urls?l

# Pinned to specific version
hm://z6Mk.../concepts/urls?v=bafy2bzaced...

Version pinning is critical for citations and references. When you link to a specific version, you're guaranteed the content won't change — it's an immutable snapshot, verified by its content hash.

The ?l flag explicitly requests the latest version. Without any version parameter, the behavior depends on context — the desktop app typically resolves to the latest, while APIs may require explicit specification.

The fragment identifier (#) lets you point to specific blocks within a document. This enables precise citations — linking not just to a page, but to a specific paragraph, heading, or code block.

# Reference a specific block
hm://z6Mk.../concepts/urls?v=bafy...#blockId123

# Block with expanded context
hm://z6Mk.../concepts/urls#blockId123+

# Block with character range (start:end)
hm://z6Mk.../concepts/urls#blockId123[0:42]

The expanded format (block+) tells the viewer to show the surrounding context. Character ranges ([start:end]) highlight a specific text selection within the block. Note: block references are most useful when combined with version pinning, since block IDs may not persist across edits.

Since browsers don't natively understand hm:// URLs, gateways translate them to standard HTTPS. The public gateway at hyper.media provides HTTP access to any Seed Hypermedia content.

# hm:// URL
hm://z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6/concepts/urls

# Equivalent gateway URL
https://hyper.media/hm/z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6/concepts/urls

# Pattern: https://<gateway>/hm/<account-id>/<path>

The gateway URL format is straightforward: the hm:// scheme is replaced with the gateway host, and /hm/ is inserted before the account ID. All query parameters and fragments carry over.

You can also run your own gateway for self-hosted access. Any Seed daemon with HTTP enabled can serve as a gateway.

While hm:// URLs are permanent and verifiable, they're not exactly memorable. Aliases let you map a friendly domain name to an account, so visitors can access content at clean URLs.

# With alias configured:
https://yourdomain.com/getting-started

# Resolves to:
hm://z6MkYourAccountId.../getting-started

# The gateway handles the translation transparently

The key insight: aliases are convenience layers. The underlying hm:// URL with its cryptographic account ID remains the canonical, permanent address. If your domain expires, the content is still accessible via hm:// or any other gateway.

When someone accesses content, the URL goes through a resolution process that bridges the web and the Hypermedia network:

1. Browser requests a gateway URL like /hm/z6Mk.../path

2. Gateway parses the URL and extracts account ID + path

3. Gateway looks up the account in its local store or discovers it via P2P networking

4. If a version is specified (?v=), that exact version is retrieved

5. Otherwise, the latest known version is resolved

6. Content is rendered as HTML and served to the browser

For custom domains, the gateway first resolves the domain to an account ID (via the alias mapping), then follows the same process.

Gateways that support the .md extension can serve documents as clean markdown — perfect for AI agents, CLI tools, and programmatic access.

# Get markdown version of any document
curl https://seed-gateway.exe.xyz/hm/z6Mk.../concepts/urls.md

# Works with custom domain gateways too
curl https://yourdomain.com/getting-started.md

This is especially useful for agents that need to read Seed Hypermedia content without parsing HTML. The markdown output preserves document structure, headings, code blocks, and links.

How does hm:// compare to other addressing schemes?

• HTTP URLs — Depend on domain ownership; content moves or disappears when domains change hands. No built-in authenticity.

• IPFS CIDs — Content-addressed (hash of data), but no concept of updates or identity. Every change creates a completely new address.

• AT Protocol URIs — at://did:plc:xxx/collection/rkey — Similar cryptographic identity approach, but tied to specific record types and the Bluesky ecosystem.

• hm:// URLs — Combine cryptographic identity (who) with mutable paths (what) and optional version pinning (when). The best of identity-based and content-based addressing.

• Use version-pinned URLs for citations — ensures the referenced content never changes

• Use unpinned URLs for navigation — readers get the latest version automatically

• Keep paths human-readable — /guides/publishing is better than /doc-a7b3c

• Set up aliases for public-facing content — friendly URLs improve discoverability

• Share hm:// URLs when permanence matters — they survive gateway changes and domain transfers

• Use block references for precise citations — point to the exact paragraph, not just the page