How to Create Multimedia Posts Programatically

Jun 16, 2024 at 11:10:21 PM

If you have a large collection of multimedia files and want to move them into Planet in a programmatic way, this document is for you. It includes detailed steps and answers to some common questions.

Repo Location

Planet uses JSON files on disk for all metadata. You can find these JSON files here:

~/Library/Containers/xyz.planetable.Planet/Data/Documents/Planet/
repo location

There are several top-level folders inside:

  • My: JSON metadata files for all of your sites.
  • Public: Built sites and attachments.
  • Templates: Templates. You can create your own templates and put them here.

Inside the My and Public folders, you will see UUID folders. Each UUID folder represents a site.

Create New Article

You can create a new article by placing a new JSON file under My/:SITE_UUID/Articles/. The filename should be the article's ID. Here are all the required fields in the article JSON:

  • articleType: int - Default is 0, which means it's a blog post. Use 1 to make it a page. A page type does not appear on the homepage list and can only be accessed via its full URL.
  • attachments: [string] - A list of attachment filenames. If you add an attachment to the article, you need to place the attachment file in the Public/:SITE_UUID/:ARTICLE_UUID/ folder.
  • content: string - Article content in Markdown format.
  • created: timestamp - Timestamp using Swift's default epoch (seconds since January 1, 2001, in the UTC timezone). Add 978307200 seconds to convert it to a regular Unix timestamp.
  • id: UUID - Use the same value as the filename.
  • link: string - Include the UUID in this format: /A26DEDFD-4460-422B-A233-8B94C5366C08/.
  • title: string - Article title.

Optional fields:

These fields are not required, but if you provide them, templates will use them accordingly.

  • audioFilename: string - If one of the attachments is an audio file, please also put its filename here as some templates (such as Plain) depend on this variable to render an audio player.
  • videoFilename: string - If one of the attachments is a video file, please also put its filename here as some templates (such as Plain) depend on this variable to render a video player.
  • slug: string - Use lowercase letters and numbers to customize the post URL. For example, if you use about as a slug, then please make sure you put /about/ in the link field.

After placing the JSON files and attachments into the folders, start the Planet app and perform a Full Rebuild.

full rebuild

It will generate a working site and publish it as an IPNS name that can be accessed from various gateways. For example:

One Audio/Video Attachment Per Post

The default Plain template supports displaying video and audio content. However, please do not include more than one video or audio file. You can have one video and one audio per post, but not two or more, as the template currently only renders the first one.

podcast.xml and Podcast-related Settings

If your site has audio files attached, Planet will generate a podcast.xml file that can be subscribed to in podcast client apps.

You can right-click on your site and adjust podcast-related settings, such as cover art and categories:

podcast settings