ℹ️ Photo collections

Documentation
1

Collections are a way to organize multiple photos and embed them into a blog post or standalone web page on Micro.blog. Collections can span across multiple blog posts and categories.

Collections are just for photos. You might create collections to group together photos from a trip, or for a particular subject that you often capture in photos.

When photos are added to a collection, all of those photos can be embedded in a new page by using a special shortcode with the collection name. If we have a collection of photos from a vacation to Disneyland, the syntax might look like this:

{{< collection "Disneyland" >}}

Micro.blog will replace this with the actual photos, creating a dynamic page that changes whenever the collection of photos change. Visitors to your blog can click a photo to open it and flip through to the next photo in the collection.

Starting your first collection

Whenever you use the {{< collection >}} shortcode, Micro.blog will create a placeholder collection using that name. At the top of the Uploads page on the web, you’ll see a “1 collection” link to show your collection. You can also create new collections from that page without first needing to reference them with a shortcode.

Add a photo to the collection by clicking the “…” context menu next to a photo. Micro.blog will list your available collections. Select one to copy that photo into it.

collections menu
collections menu770×636 253 KB

Managing collections on macOS

Micro.blog for the Mac has a new window with a list of collections. Choose Window menu → Collections to open the window. You can drag a photo directly from the Uploads section into this window to copy it.

Lightbox demo

Here’s a quick video showing how the photos will appear on your blog.

Styling with CSS

When you reference a collection using the shortcode {{< collection >}}, Micro.blog expands it to include thumbnails of the photos. By default these are about 200x200 and set to crop to square. You can customize how these are displayed by styling with the CSS class microblog_collection.

For example, to change the photos to be displayed as smaller thumbnails with rounded corners, while preserving the aspect ratio of each photo, use something like this in your blog’s custom CSS:

.microblog_collection img {
  width: 150px
  height: 150px;
  border-radius: 5px;
  object-fit: contain;  
}

All of the default styling and JavaScript is in a plug-in that is installed automatically whenever you use the shortcode.

Videos and other upload types

Collections were designed for photos. If you add videos and other uploads to a collection, currently those will be ignored. We may expand this in the future based on feedback.

Hugo data

Collections are available to Hugo as structured data. They can be accessed by themes and plug-ins using .Site.Data.collections.<name here>, where the name is like the filename version of a collection name. A collection called “Europe 2024” will become .Site.Data.collections.europe2024. The data is an array with fields such as url for the photo URL.

Export your site as a Markdown archive to see the details about the data.

Developer API

Collections are available as a special channel in the Micropub API. To get a list of collections, pass mp-channel to the Micropub endpoint with the usual authorization:

GET /micropub?q=source&mp-channel=collections
Host: micro.blog
Authorization: Bearer ABCDEFGH

The response will also include the number of uploads in each collection:

{
  "items": [
    {
      "type": "h-entry",
      "properties": {
        "uid": [ 1 ],
        "url": [ "https://example.org/collections/1" ],
        "name": [ "Disneyland" ],
        "microblog-uploads-count": 5
      }
    }
  ]
}

Note that users can have multiple blogs, and each blog will have its own set of collections. When writing clients for Micro.blog, it’s a good idea to get a list of blogs and always pass the current blog in the mp-destination parameter with any calls to the Micropub API.

To create a new collection:

POST /micropub
Host: micro.blog
Content-type: application/json

{
  "mp-channel": "collections",
  "mp-destination": "https://manton.micro.blog/",
  "properties": {
    "name": [ "Vacation photos" ]
  }
}

To delete new collection, pass the URL:

POST /micropub
Host: micro.blog
Content-type: application/json

{
  "mp-channel": "collections",
  "mp-destination": "https://manton.micro.blog/",
  "action": "delete"
  "url": "https://example.org/collections/1"
}

To copy a photo into the collection, use the action field, passing the url for the collection and the new photo to add:

POST /micropub
Host: micro.blog
Content-type: application/json

{
  "action": "update",
  "mp-channel": "collections",
  "url": "https://example.org/collections/1",
  "add": {
    "photo": ["https://example.org/...example.jpg"]
  }
}

To remove a photo from a collection, use the delete field:

POST /micropub
Host: micro.blog
Content-type: application/json

{
  "action": "update",
  "mp-channel": "collections",
  "url": "https://example.org/collections/1",
  "delete": {
    "photo": ["https://example.org/...example.jpg"]
  }
}

To get all the photos in a collection, there is a microblog-collection parameter that is the URL for the collection:

GET /micropub/media?q=source&microblog-collection=https://example.org/collections/1
Host: micro.blog
2 Likes