Extension Item Specification

An Extension Item is a simple dictionary with data about an extension.

The following key/value pairs are supported:

key value
extensionName

Name of the extension.

string

required

repository

URL of the Git repository containing the extension.

If not provided, an infoPath and zipPath must be set.

string

not required

extensionPath

Path to the .roboFontExt file inside the repository or zip file.

string

required

description

A short description of the extension.

string

required

developer

Name of the developer

string

required

developerURL

Site URL of the developer.

string

required

tags

A list of tags related to the extension.

list

required

infoPath

Path to the info.plist file inside the extension package.

If not provided, the infoPath will be constructed from the repository and extensionPath.

string

not required

zipPath

Path to the .zip file containing the extension.

If not provided, the zipPath will be constructed automatically for known services like GitHub, GitLab and BitBucket.

string

not required

icon

Path to an image file with the icon for this extension.

string

not required

Extension icons

Mechanic 2 supports optional extension icons, which are displayed in the extensions overview list if available. Icons make it easier to identify and remember extensions.

Here are some additional recommendations for icon images:

attribute recommendation
file path save the image outside of the .roboFontExt package
file name <extensionName>MechanicIcon.png
format .png with transparent background
size 512 × 512 px

Usage

Extension items can be distributed by themselves or collected into extension streams.

The extension item format is not tied to a particular data format:

  • single extension items are stored in yaml format
  • extension streams are served as json data

Extension items

Here is an example extension item in yaml format:

extensionName: myExtension
repository: http://github.com/robodocs/rf-extension-boilerplate
extensionPath: myExtension.roboFontExt
description: A boilerplate extension which serves as starting point for creating your own extensions.
developer: RoboDocs
developerURL: https://github.com/roboDocs
tags: [ demo ]
infoPath: http://github.com/roboDocs/rf-extension-boilerplate/blob/master/build/myExtension.roboFontExt/info.plist?private_token=myPrivateToken
zipPath: http://github.com/roboDocs/rf-extension-boilerplate/archive/master.zip?private_token=myPrivateToken
icon: http://github.com/roboDocs/rf-extension-boilerplate/blob/master/build/myExtension.roboFontExt/resources/icon.png?private_token=myPrivateToken

Single extension items can be stored under different filenames, depending on the desired distribution channel:

<extensionName>.yml
for registration in the Mechanic 2 extension stream
<extensionName>.mechanic
for distribution as single extension item

Extension streams

An extension stream is a .json file containing a list of extension items and a date (when the list was last updated).

Here is an example extension stream:

{
  "lastUpdate" : "2018-06-08 21:21",
  "extensions" : [
    {
      "extensionName": "myExtension",
      "repository" :  "http://github.com/robodocs/rf-extension-boilerplate",
      "extensionPath" : "build/myExtension.roboFontExt",
      "description" : "A boilerplate extension which serves as starting point for creating your own extensions.",
      "developer" : "RoboDocs",
      "developerURL" : "https://github.com/roboDocs",
      "tags" : ["demo"],
      "icon" : "http://github.com/roboDocs/rf-extension-boilerplate/blob/master/build/myExtension.roboFontExt/resources/icon.png"
    },
    /* ... more extensions here ... */
  ]
}

Extension streams can be created dynamically (by a server) by aggregating data from several single extension item files. See the Mechanic 2 extension stream for an example.

Private access tokens

Extensions in private repositories are supported as long as a valid private token is provided. This private token is needed to access individual files inside the extension’s repository: infoPath, zipPath, and icon (if available).

The yaml extension item sample above shows private tokens in use – search for occurrences of private_token.

Creating private access tokens

Private tokens can be created using the web interface of your favorite Git platform:

Last edited on 08/09/2018