Format Microformat

Formats a Microformat JSON representation into eg. a Jekyll post

Requirements

Requires at least Node.js 6.x

Installation

npm install format-microformat --save

Current status

Alpha

Currently formats data into a hardcoded Jekyll style. This is intended to become more dynamic and configurable in the future to adapt to more styles.

Usage

Simple:

const MicropubFormatter = require('format-microformat');
 
const formatter = new MicropubFormatter();
 
formatter.formatAll(micropubDocument)
  .then(formatted => {
    // Lots of formatted data that one can do lots of fun stuff with. Publish somewhere or such perhaps?
    // Available keys are "filename", "url", "content" and lastly "files" if any files were uploaded
  });

Advanced:

const MicropubFormatter = require('format-microformat');
 
const formatter = new MicropubFormatter('http://example.com/');
 
formatter.preFormat(micropubDocument)
  .then(preFormatted => Promise.all([
    formatter.formatFilename(preFormatted),
    formatter.format(preFormatted),
    formatter.formatURL(preFormatted),
  ]))
  .then(([formattedFilename, formattedContent, formattedUrl]) => {
    // Lots of formatted data that you can do lots of fun stuff with. Publish it somewhere maybe?
  });

Constructor

new MicropubFormatter([options])

Options

• relativeTo – if set to a URL, then all formatted URL:s will be resolved to absolute URL:s relative to that one rather then be returned as relative ones.
• noMarkdown – if set to true then no conversion to Markdown will happen for the content.
• contentSlug – if set to true, then the slug creation will use the properties.content data as a fallback to properties.name prior to basing the slug on the timestamp.
• defaults – a micropubDocument with defaults that will be added as part of the preFormat(). Useful to eg. ensure that all documents have a language explicitly set.
• deriveCategory – a method that's provided the properties of the post and which returns a dervice category – or false to disable default category deriving
• deriveLanguages – an array defining what languages, using ISO 639-3, to autodetect – or true to try and autodetect everything
• filenameStyle – a filename style in the same form as the Jekyll permalink style. Should not include file extension. Defaults to: _posts/:year-:month-:day-:slug
• filesStyle – the filename style of uploaded files, in an extended form of the Jekyll permalink style. Should not include file extension, but should include :filesslug. Defaults to: media/:year-:month-:slug/:filesslug
• layoutName – the name of a layout that overrides the default micropubpost one, or false to remove the layout completely from the front matter
• permalinkStyle – a Jekyll permalink style. Defaults to Jekyll's default: date
• encodeHTML – non-standard – if set to false then HTML-encoding will not happen for the content value. Defaults to true

layoutName, filenameStyle, filesStyle and permalinkStyle can all be set directly or through a callback that's given some data and that callback might either return a value directly or return a Promise that eventually resolves to the value.

Methods

• formatAll(micropubDocument) – preFormat:s and formats everything. Returns a Promisethat resolves to an object with the keys filename, url, content, files and raw.
• preFormat(micropubDocument) – takes a micropubDocument and ensures that all necessary parts are there. Currently required to run a micropubDocument through this method before handing it to the rest of the methods (except formatAll()).
• formatFilename(preformattedMicropubDocument) – returns a filename based on the data in the micropubDocument. Includes the relative path to the file – which currently is always _posts/
• formatURL(preformattedMicropubDocument) – returns the url the formatted content is expected to live on when published
• format(preformattedMicropubDocument) – formats the actual content. Currently it's formatted as an HTML-file with Jekyll Front Matter. The content of the file is the properties.content of the micropubDocument – the rest of the data is put into the front matter.

Output formats

For exact implementation of how things are formatted, look at the code and the tests, this is just to get an overview of what one can expect the output to be.

Filename

The target is to get a filename similar to _posts/2015-06-30-awesomeness-is-awesome.html. The date first and then either the defined slug or a slug derived from title or content.

URL

The target is to get a relatuve URL similar to 2015/06/awesomeness-is-awesome/ where the slug is calculated in the same way as it is for the filename. In some cases the URL will be prefixed with a category name – that's the case for eg. replies, likes and bookmarks – the first two are prefixed with interaction/ and the last one with bookmark/.

Content

The actual content of the file is the HTML of the properties.content of the micropubDocument. All other properties are added to the Jekyll Front Matter together with a couple of other defaults.

Some micropubDocument properties receive special handling, the rest are included raw as arrays with an mf- prefix to avoid collisions with pre-existing Jekull properties.

The ones with special handling are:

• content – isn't part of the front matter but is the actual HTML content of the file
• name – inserted as title and if not specified, then a value of '' will be used to avoid automatic generation of titles
• slug – inserted as slug
• category – inserted as tags
• published – inserted as date and formatted as ISO-format

There's also some defaults and derived values:

• layout – by default set to micropubpost
• category – derived from other micropubDocument properties and only used in some cases, like eg. for replies, likes and bookmarks – it's set to interaction for the first two and to bookmark for the last one

An example of a generated Jekyll Front Matter:

layout: micropubpost
date: '2015-06-30T14:34:01.000Z'
title: awesomeness is awesome
slug: awesomeness-is-awesome
category: interaction
mf-like-of:
  - 'http://example.com/liked/page'

Files

An array of objects with a filename containing the full path where the file should be uploaded as well as a buffer key containing the same buffer object that was part of the original micropubDocument files data. Also calculates URL:s for the location of the files post-upload and adds them to the proper photo, video or audio property in the micropubDocument so that they are made available in the content.

Unlike the other formatting, file formatting happens fully in preFormat() as it needs to be done prior to the rest of the step to make the URL:s of the uploaded files available to the rest of the formatting.

Currently supported file keys from the original micropubDocument: photo, video and audio

Format of micropubDocument

The format closely matches the JSON-representation of Micropub.

See the micropub-express module for documentation of this basic object.

In addition to the properties defined by the micropub-express module, the preFormat() method adds a top level derived key that's used internally for values derived from.

The preFormat() also flattens the files object into an array of files and formats the filenames to the full path where a file should be uploaded.

Other useful modules

• micropub-express – an Express 4 Micropub endpoint that accepts and verifies Micropub requests and calls a callback with a parsed micropubDocument that can be used with this module
• github-publish – a module that takes a filename and content and publishes that to a GitHub repository. A useful place to send the formatted data that comes out of this module if one wants to add it to a GitHub hosted Jekyll blog of some kind, like eg. GitHub Pages.

Used in

• webpage-micropub-to-github – a self-hosteable Micropub endpoint that publishes posts to Jekyll sites by committing them to their GitHub repositories