Channels

[aaronpk]

Channels

This is a proposal to introduce a new organizational concept to Micropub for creating and editing posts: Channels.

• A post can be created within one or more "channels"
• The server can define its own list of channels, and can decide whether the user is allowed to create new ones or not
• The server is assumed to have a default channel, where posts created that don't specify a channel are created in the default channel
• Clients must not assume the names, IDs, presence or absence of any channels at the micropub endpoint
• A website may not support channels at all, in which case none of this matters to the micropub endpoint and it can ignore channels in requests completely.

Why not "categories"? "Tags" and "categories" have existed in practice for many years, but lately have converged to mean essentially the same thing, as will be made apparent below. Repurposing the term "category" for this would add confusion with existing systems.

Micropub Requests

• This would add a new property to the Micropub request when creating or editing a post: channel. Absence of this property would create the post in the "default" channel, whatever that means to the server.
• The query for post list (Query for Post List #4) would include a new property, channel, to choose which post list to return. Absence of this property would return the "default" list of posts, whatever that means to the server.

If a server does not support this organizational pattern, no change is needed, since it would ignore this property in queries or requests.

This would resolve the discussion on Pages, since CMSs can define a special channel to collect these pages under.

Mapping to existing CMSs

WordPress

WordPress has three primary organizational structures: Pages, Categories and Tags.

• Pages - Pages in wordpress are a top-level type. They do not display a published date, pages can be created within a hierarchy of other pages, and pages cannot be added to categories or tags. Pages do not contain date components in their URL.
• Posts - Posts are a top-level type. Posts are always dated, and often include date components in their URL. Posts can be organized by categories and/or tags, and both categories and tags have their own permalinks which list out all posts within them.
  • Categories - The user can define a list of categories in their website. Categories are hierarchical and can exist within other categories. Posts can be added to one or more categories. In the post creation UI, the complete list of categories is shown to the user to select one or more.
  • Tags - Posts can be added to one or more tags. In the post creation UI, the tags are autocompleted when typing but the full list is not shown.

WordPress can expose these organizations by using a combination of Micropub channels and categories. ("category" in Micropub is from the Microformats vocabulary, and is what most people would think of as "tags" on a post.)

• Micropub "category" maps to WordPress "tags"
• Micropub "channels" would be the combination of the user's WordPress "categories" plus the addition of the specially-named "Pages" channel which WordPress would treat separately

(The current version of the Micropub plugin combines categories and tags into a single list. If a category in a micropub request matches an existing wordpress category or tag then it's used, but if it doesn't exist, a tag is created.)

Micro.blog

Micro.blog has two primary organizational structures: Pages and Categories.

• Pages - Like WordPress, Pages in Micro.blog exist outside of the flow of other posts. Their URLs typically don't have date components. Some pages are treated specially, such as the "Photos" page where Micro.blog will collect the user's photo posts and show them in a grid.
• Categories - The user can define a list of categories in their website. Posts can be added to one or more categories.

Adopting Micropub "channel":

• Micropub "category" maps to Micro.blog categories
• Micro.blog would have only two defined Micropub "channels": Pages and Posts. New posts would be created in the "Posts" channel by default, unless the "Pages" channel is specified in the request.

Kirby

TODO

Ghost

TODO

Usage in Custom CMSs

aaronparecki.com

My posts exist in three main organizational concepts: channels, tags, and pages.

• Tags - any post can have one or more tags. The posts will appear on that tag's page. When creating a post, hashtags used in the post will be added as post tags.
• Channels - any post can exist in one or more channels. Channels get top-level URLs such as /articles, /likes, /travel. Note that even though the names of some of these might suggest certain post types, there is no requirement that only posts of a certain type are added to a particular channel.
• Pages - there is nothing special within a post that designates it as a page, the thing that makes something a page is that it does not exist in any categories, and has a URL with no date component.

Adopting Micropub "category":

• Micropub "category" maps to tags
• Micropub "channel" maps to channels, and I would create a new channel "Pages" and add my current pages to that channel. This channel would be treated specially and would not be given its own top-level URL to display the list of pages in that channel, unlike other channels.

[dshanske]

Interesting idea. I need to stew on it.

[manton]

One advantage to this approach is that it avoids any overlap with Microformats in terms of defining a new "page" post type. I'm still thinking about this, but it is simpler to isolate changes to only the Micropub side.

In the WordPress notes you have:

Micropub "channels" would be the combination of the user's WordPress "categories" plus the addition of the specially-named "Pages"

Are we sure this is how it would work? Couldn't categories still be their own thing, and channels via WordPress would (like Micro.blog) only include "Posts" and "Pages"?

[aaronpk]

I should note: My website already supports this via the vendor-specific property p3k-channel, and Quill has support for querying the list of channels and specifying a channel for the Event creation UI.

[aaronpk]

Are we sure this is how it would work? Couldn't categories still be their own thing, and channels via WordPress would (like Micro.blog) only include "Posts" and "Pages"?

Given that the current plugin merges wordpress categories and tags into the micropub "category" property, it may be better to have "channels" be only posts and pages like you described. Either way is fine with me, it's up to the WordPress folks really, and has no effect on the actual protocol here!

[manton]

Sounds good. I agree, this should be up to each server implementation. However, I think it could be confusing if some servers included categories in the channel list, and some didn't. It's fine as long as clients don't make assumptions that categories will be returned in the channel list.

But I could see user features related to this. For example, maybe there's an option in Micro.blog to mark a category as being included in the client sidebar along with Posts and Pages channels, basically elevating the category to a higher prominence in the UI.

[manton]

To expand on the proposal, here are some request/response examples to make sure we're all talking about the same thing. Let me know if this looks right. This is from the Micro.blog perspective.

Get the channel list

GET /micropub?q=channel

{
  "channels": [ "Posts", "Pages" ]
}

Create a new page (form-encoded)

POST /micropub

h=entry&mp-channel=Pages&content=Hello

Create a new page (JSON)

POST /micropub

{
  "type": "h-entry",
  "properties" {
    "mp-channel": "Pages",
    "content": "Hello"
  }
}

[dshanske]

Why "Pages" as opposed to "Page" or "page" ?

[dshanske]

Suggest, per chat, channels have a uid and display name.

[dshanske]

That uid could actually be Pages.

[aaronpk]

The names of the channels are entirely up to the server and don't need to be specified in Micropub.

However I'd recommend matching the Microsub method of channels so that they can have identifiers separate from the display name.

e.g.

GET /micropub?q=channel

{
  "channels": [
    {
      "uid": "posts",
      "name": "Posts"
    },
    {
      "uid": "pages",
      "name": "Pages"
    }
  ]
}

Specifying the channel in the request would use the uid value instead of the display name.

POST /micropub

{
  "type": "h-entry",
  "properties" {
    "mp-channel": "pages",
    "content": "Hello"
  }
}

[dshanske]

How would the existing category property work with channels? What would you expect to happen if category was sent as a channel and a property?

[dshanske]

I see the note about this further up, but just curious about scenarios

[aaronpk]

Not sure what you mean @dshanske, these are two completely separate organizational patterns and can exist together.

[manton]

I'm good with adding the uid. In addition to being consistent with Microsub, it matches mp-destination.

[dshanske]

@aaronpk Just thinking of where someone will be confused in future.

[manton]

If there are usually only a handful of channels, what about including it directly in the q=config response, similar to destination and post-types?

[manton]

I've reimplemented my support for pages to now use channels. I think my initial concerns that this would be confusing with categories (or that it would be an unnecessary extra abstraction) were unfounded. Works pretty well.

[aaronpk]

Awesome!

Yes I think including it in the initial q=config response is completely reasonable.

[vikanezrimaya]

Channels would map perfectly to the concept of "feeds" in Kittybox. I have a "feed" as an organizational unit of my posts, along with categories (which I internally call "tags" - they have feeds of their own too). The default channel would be the main feed - every single post (with some exceptions) will end up in the main feed, channels would be alternative feeds.

Creating a channel would probably involve posting an (optionally empty) h-feed at a certain URL which will then be registered as a new channel. Alternatively, unknown channel UIDs can result in creation of new channels (TODO brainstorm UI in Kittybox Companion for this) or be rejected.

Additionally (this bit isn't specific to Kittybox but may be applied to other implementations as well), a Micropub client could have settings to automatically preset channels for certain post types.

[jalcine]

Revisiting this post and this perfectly satisfies a lot of the stuff I wanted re: pages and introduces a new approach to handling content. I’ll see if I can implement this in Koype in the coming months.

(Originally published at: https://v2.jacky.wtf/post/e6adaf2b-7e5d-458b-adf4-1b288d9f8d13)

[jalcine]

Throwing a small wrench into this, how should we consider creation of channels? I do want to be able to add and remove channels somehow from a Micropub client (this is also coming from me wanting to keep my Micropub server as headless as possible.

[manton]

Microsub can create channels, so it might make sense to borrow from that interface. As long as creation is optional… Micro.blog won't support creating new channels.

[vikanezrimaya]

I am planning to support creating new channels via posting an MF2 object of type "h-feed". It should at least have a name and preferably an mp-slug to generate a pretty URL (note: Kittybox never generates pretty URLs automatically, this is currently intended behavior). A UID will be generated automatically for internal bookkeeping and it will be added to the channel list in the database. On the next ?q=config request the new channel will appear in the channel list with its name and UID. This is already implemented in the new version of the software.

[jalcine]

This is an interesting approach. Using `h-feed` feels a bit weird but _correct_ to me because channels are best represented as a feed from Aaron's explanation and comparison above when it's not in the editing context.

…

On Sun, Jul 4, 2021 at 10:50 AM, Vika ***@***.***> wrote: I am planning to support creating new channels via posting an MF2 object of type "h-feed". It should at least have a name and preferably an mp-slug to generate a pretty URL (note: Kittybox never generates pretty URLs automatically, this is currently intended behavior). A UID will be generated automatically for internal bookkeeping and it will be added to the channel list in the database. On the next ?q=config request the new channel will appear in the channel list with its name and UID. — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[jalcine]

I have this working for my site's apps in a few ways:

• I can add channels over Micropub to my Micropub endpoint ("action": "channel", "name": "channel-name")
• I can fetch them from my site via q=channel and see just the UIDs in q=config

I think that those designing their system should opt for their Micropub systems to have a default channel that q=source uses to help with filtering.

[manton]

For what it's worth, Micro.blog does use the uid "default" channel ("Posts") from q=source when no mp-channel is specified.

[manton]

Also, I don't support q=channel and personally don't see the need for a separate request when the channels can easily be included in q=config. I think it makes Micropub harder to implement if clients are sending lots of different "q" queries.

[jalcine]

Also, I don't support q=channel and personally don't see the need for a separate request when the channels can easily be included in q=config.

I currently ran into an issue with Quill (though undocumented in this regard) because my default channel body would provide its "expanded" form (with the name and uid fields). I changed it to work to return just a string. My site doesn't hold any of its Micropub logic and works as another client so it'd be necessary to get more information (be it semantic) about channels for me. This could be an implementation specific issue but I do think allowing for this (also potentially for syndication targets) would allow for more flexible uses of channels. Some that I have upcoming:

• Marking some posts and content as pinned by adding them to a special channel. My site could request (and recognize) this and use it to adjust feeds accordingly
• Controlling the presentation of content in a particular channel - things in a "work" channel or "poems" channel could be rendered differently

I think it makes Micropub harder to implement if clients are sending lots of different "q" queries.

IIRC, this is what ?q=config#q is supposed to solve. If the particular vocabulary doesn't exist there, it's a query (and maybe also action?) that isn't supported by the endpoint. This works for media endpoints exposed via q=config as well.

[manton]

@jalcine I wonder if it would help if you pasted a couple example responses here? I just want to make sure I understand how you're supporting this… I might've been confused in my recent question.

For Micro.blog, here's what my q=config looks like (with types and destination edited out for clarity):

{
  "channels": [
    {
      "uid": "default", 
      "name": "Posts"
    }, 
    {
      "uid": "pages", 
      "name": "Pages"
    }
  ], 
  "post-types": [],
  "destination": [],
  "media-endpoint": "https://micro.blog/micropub/media"
}

[jalcine]

Yeah! So my hope/goal is to allow for the creation of channels and also allow for querying for more information about them (a bit similar to how we do categories right now).

The two cases I gave above are very specific to the content rendering content of my site but my hope is to have something like this for the creation of a channel:

POST /mp
Host: jacky.example
Content-Type: application/json

{
  "action": "add-channel",
  "name": "Pinned Content"
}

which would return something like

{
   "name": "Pinned Content",
   "uid": "492kz23"
}

This way, an editor can show this in its interface to allow for association (or if in the settings for an editor, you can specify which channel would cause a particular action, like pinning a post so it'd present it merely as a checkbox).

---

For querying, we could do it similarly to how we do it for categories

GET /mp?q=channel
Accept: application/json
Host. jacky.example

{
   "channels": [{
      "name": "Pinned Posts",
     "uid": "madfjhdf"
   }]
}

Which now could also be used in things like q=source as a filtering option (for all of the pinned posts or things in a channel).