Hypermedia sites should enable an expressive intellectual structure for creators. Good organization should be easy to create, but the responsibility for creating well-organized content ultimately lies with the creators.

The site and document structure should declare a framework for how content should be presented. It does not need to be pixel-perfect, but instead provide a guideline for client implementers so that content can be presented roughly in-line with the expectations of the creators.

Site and document model should have well-defined terms, and the API should reflect the goals and principles described here.

The Hypermedia API should be consistent throughout, when it comes to naming and design patterns.

Hypermedia Sites should avoid extra complexity, to reduce the implementation cost and to make it easier to learn.

Seed Hypermedia has an existing implementation with certain constraints. This proposal does not take any limitations from the existing system. Instead it is a clean approach and may make backwards-incompatible changes. If we decide that sites+documents should have this structure, we can decide what the migration strategy is. Or if we want to bend this proposal to the existing implementation

Here we are focusing on the approach to the design, not on specific features. Some features described are very low-priority, and we won't ever need to implement them. The idea is to sketch our current feature requests into this model so we can figure out how they would be implemented if we do decided to build them.

Every Site must have a Document with an empty Path, which is used as the main Document to introduce readers to the content.

Any Document with a Path is a Sub-Document because it is organized within another document.

The Path of a Sub-Document is prefixed with the Path of the parent Document. For example:

A Document contains the following Attributes which are used to describe the Document, as well as some presentation preferences:

Every Document has a Document Navigation. By default, the Navigation will be the Navigation View of the Document Content. (Previously known as the outline).

The Document may have a navigation field defined, which will override the Content that is used to generate the Navigation. This allows authors to control how readers will go deeper into the content, and will probably contain Cards and Queries that expose Sub-Documents.

A Document Navigation can include an embed of the document itself, which allows an "outline" to appear in the Navigation UI, helping the reader jump around headings inside the document.

Values from the theme field are special because they affect the syle of Sub-Documents in addition to the document itself.

The Seed app will probably only allow theme customization from the Site Home, but the protocol theoretically supports the Theme on any document.

"theme": {
  "colors": {},
}

{
  "name": "My Document",
  "icon": "ipfs://1234",
  "content": BlockNode[]
  "navigation": BlockNode[],
  "theme":  {...}
  ...attributes
}

A Block is a single node of content, and it often contains text.

The Block Node is the fundamental building block for creating structures of content within a document. It contains a single Block as well as an ordered set of children BlockNodes. Generally, a BlockNode may contain any type of child blocks.

Generally, Blocks and Block Nodes form Content in the Hypermedia Structure

Many Block types contain the text value. If a Block does, it may contain a list of Annotations to make the text more expressive.

The Site Header is meant to show the reader what Site they are inside, and give access to the Site Navigation and other features that the Client provides, such as access to the mobile menu.

The Home Document may specify a layout for the header that the Client should respect, to enable different visual styles for the Header. For example, a layout for center-aligned Navigation under the Site Logo.

The Navigation Views of a Document should always be easily accessible while the Document is open. For a Site Home Document, it should appear in the Site Header (or be accessible from the Header, if there is not enough space). If space allows, the Navigation should be visible in the Sidebar.

Shows the parent Documents and may give access to the Home Document

Note: The Breadcrumb may have different presentation styles— it does not have to take the form factor of traditional breadcrumbs (for example it may be a dropdown or a vertical list of parents) This would be decided by the Client and may be informed by Document Attributes.

To support phone-sized screens, a Client should give easy access to the Navigation of the document. To ease navigation across the site, the navigation should have its own Breadcrumb that helps the user access the Navigation of Parent Documents and the Site Home.

This strikes a balance of keeping the UI minimal and focused, while giving the reader easy access to navigate across the site.

Header Blocks are rendered with larger bold text, and nested Headers should be smaller to help the reader visually understand the structure of the Content.

Children Blocks are generally indented, unless they appear within a Header block. Under a Header, the hierarchy should be visually apparent without using blank horizontal space to indicate it.

Clients should support the ability for a reader to Collapse, hiding all children of a Block Node. This will help the reader hide content they are not interested in, or aren't ready to read yet.

A hierarchy of links

When the Navigation Content includes an Embed Block, the view attibute is critical to define the Navigation Presentation.

Q: What if an author wants the sidebar to be used for navigating within the Home Document of a site

A:

A document snapshot of a Home Document:

{
  "name": "F1 Fans",
  "content": [
    {
      "block": {
        "id": "block1",
        "type": "Heading",
        "text": "Teams",
        "style": "h1"
      },
      "children": [
        {
          "block": {
            "id": "block2",
            "type": "Heading",
            "text": "Ferrari"
          },
          "children": [
            {
              "block": {
                "id": "block3",
                "type": "Paragraph",
                "text": "Founded by Enzo Ferrari in 1929"
              }
            }
          ]
        },
        {
          "block": {
            "id": "block2",
            "type": "Heading",
            "text": "Mercedes"
          },
          "children": [
            {
              "block": {
                "id": "block3",
                "type": "Paragraph",
                "text": "First raced in 1954"
              }
            }
          ]
        }
      ]
    }
  ]
}

A Sub-Document may embed the navigation of a parent document. Imagine there is a document /teams/ferarri:

{
  "name": "Ferrari",
  "content": [],
  "navigation": [
    {
      "block": {
        "id": "block1",
        "type": "Heading",
        "text": "Drivers",
        "style": "h1"
      },
      "children": [
        {
          "block": {
            "id": "block2",
            "type": "Embed",
            "link": "hm://123/teams/ferrari/drivers/louis-hamilton",
            "view": "Card"
          }
        },
        {
          "block": {
            "id": "block3",
            "type": "Embed",
            "link": "hm://123/teams/ferrari/drivers/charles-leclerc",
            "view": "Card"
          }
        }
      ]
    }
  ]
}

This Document will have the navigation structure:

The driver document is located at /teams/ferrari/drivers/louis-hamilton:

{
  "name": "Louis Hamilton",
  "content": [],
  "navigation": [
    {
      "block": {
        "id": "block1",
        "type": "Embed",
        "link": "hm://123/teams/ferrari",
        "view": "Navigation"
      }
    }
  ]
}

The navigation structure matches the drivers doc. When you click on "Louis Hamilton" from the drivers navigaion, the Louis page highlights and the navigation content stays the same.