Documentation Test

Gabo H Beaumont

15 July 2025, 07:55

Content

Untitled Document

A Document is the primary data structure for knowledge in the Hypermedia ecosystem. Every Document is a ChangeResource, so it is modeled with Refs and Change blobs.

The main building block for knowledge in the Hypermedia network is the Document.

Each Document is identified by the Site Id + Path

Content

The content of the document is a hierarchy of Blocks. Each Block Node contains one block and any number of children blocks.

Block Types

  • Paragraph
  • Heading
  • Code
  • Math
  • Image
  • Video
  • File
  • Button
  • Embed
  • WebEmbed
  • Query
  • Experimental Block Types
    • Nostr
      Note: Some Block types do not properly support children. TODO: research and explain this better

Metadata

A document has the following metadata fields to describe it. They are all optional but it is recommended to always have a name

name

The title of the Document. For Home Documents, this is the title of the Site.

icon

The IPFS url for the icon associated with this Document. For Home Documents, this is the icon (or favicon) for the Site.

cover

The IPFS url for the cover image. When present, displayed full-width at the top of the document.

siteUrl

For Home Documents, contains the https URL where the Site is published on the web.

displayPublishTime

TODO

showOutline

TODO

showActivity

TODO

contentWidth

TODO

theme

TODO

Experimental Metadata

seedExperimentalLogo

For Home Documents, contains the IPFS url for the logo to be used in the header, instead of the name+logo.

Deprecated Metadata

Some fields are no longer in use but they may appear in older Documents. They can be safely ignored.

  • layout
  • seedExperimentalHomeOrder

Shape

Contains the following fields

  • Signer
  • Delegate – The Account ID of the identity receiving new capabilities
  • Role
  • Label
  • Revoked – Boolean, true if the capability is being revoked
  • Path
  • Recursive
  • Deps – The CIDs of capabilities to depend on. Used to form a chain of capabilities
  • Signature – Cryptographic proof of this shape from the signer

Chaining

A capability might be granting permissions to another account, which might require a chain of capabilities.

The Resource is created by forming a graph of Changes and then using Refs to point to the latest heads of the change graph.

Currently, the protocol's only ChangeResource is the Document

The Change blobs describe the operations to add/remove data from the resource. They depend on other Changes, and you can walk through all changes, applying operations, until you reach the current state of the Resource.

Changes are the raw data with version history, and a Ref specifies the actual location.

Unlike basic Resources, the ChangeResource allows easy branching, redirecting, and re-publishing.

Branching

If you want to create your own branch of an existing ChangeResource, you can simply create a Ref that points to the desired set of Changes.

Deleting

To delete the resource, create a new "tombstone" ref which marks the resource as deleted.

Redirecting

You can create a special Redirect Ref, so that you will be moved to another location when attempting to open this Resource.

Republishing

In cases where you want to redirect but keep showing the current URL, we allow a republish flag to be set on a redirect.

Move

To move a ChangeResource, you should create a new Ref at the new location.

With the old location, you should probably set a redirect to the new location, so links won't be broken. But if you want to break links, you can delete the old Ref.

Note: For users who have already downloaded the content and who want to refer to exact versions, links will not break.

Generations

Generations are numbers used to manage the lifecycle of ChangeResource Refs. This number must be incremented when deleting or undeleting the Resource. It can also be incremented if your ref shifts to an entirely unrelated change history.

A Ref is a Signed Data Blob that points to the latest state of a ChangeResource according to the signer.

Version

A set of change heads, identified by their CID.

Location

The "space" and "path" which identifies the location of this ref.

Generation

The number which identifies which generation of Ref is changing. Useful for handling concurrent updates to the ChangeResource, like if the resource is deleted by one author while it is updated by another.

Tombstone/Deletes

...

Redirect

Points to another ref. Optional Republishing flag which specifies that the content is being redirected but the location should remain.

A Change is a Signed Data Blob that specifies some set of operations against a ChangeResource

Deps

Change dependencies

Ops

The operations that are happening in this change.

A Signed Data Blob is a Data Blob which has the "sig" and "signer" fields.

A generic data blob is any IPFS file which is encoded using DAG-CBOR and has a "type" field that references this documentation.

A Contact is metadata that an Account uses to describe itself or another Account.