Formats a Microformat JSON representation into eg. a Jekyll post
Requires at least Node.js 6.x
npm install format-microformat --save
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.
const MicropubFormatter = ;const formatter = ;formatter;
const MicropubFormatter = ;const formatter = '';formatter;
- 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
truethen no conversion to Markdown will happen for the content.
- contentSlug – if set to
true, then the slug creation will use the
properties.contentdata as a fallback to
properties.nameprior to basing the slug on the timestamp.
- defaults – a
micropubDocumentwith 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
falseto disable default category deriving
- deriveLanguages – an array defining what languages, using ISO 639-3, to autodetect – or
trueto try and autodetect everything
- filenameStyle – a filename style in the same form as the Jekyll permalink style. Should not include file extension. Defaults to:
- 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:
- layoutName – the name of a layout that overrides the default
falseto remove the layout completely from the front matter
- permalinkStyle – a Jekyll permalink style. Defaults to Jekyll's default:
- encodeHTML – non-standard – if set to
falsethen HTML-encoding will not happen for the content value. Defaults to
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.
- formatAll(micropubDocument) –
preFormat:s and formats everything. Returns a
Promisethat resolves to an object with the keys
- preFormat(micropubDocument) – takes a
micropubDocumentand ensures that all necessary parts are there. Currently required to run a
micropubDocumentthrough this method before handing it to the rest of the methods (except
- formatFilename(preformattedMicropubDocument) – returns a filename based on the data in the
micropubDocument. Includes the relative path to the file – which currently is always
- 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
micropubDocument– the rest of the data is put into the front matter.
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.
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.
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
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.
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
titleand if not specified, then a value of
''will be used to avoid automatic generation of titles
- slug – inserted as
- category – inserted as
- published – inserted as
dateand formatted as ISO-format
There's also some defaults and derived values:
- layout – by default set to
- category – derived from other
micropubDocumentproperties and only used in some cases, like eg. for replies, likes and bookmarks – it's set to
interactionfor the first two and to
bookmarkfor the last one
An example of a generated Jekyll Front Matter:
layout: micropubpostdate: '2015-06-30T14:34:01.000Z'title: awesomeness is awesomeslug: awesomeness-is-awesomecategory: interactionmf-like-of:- ''
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
audio property in the
micropubDocument so that they are made available in the
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
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.
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
micropubDocumentthat 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.
- webpage-micropub-to-github – a self-hosteable Micropub endpoint that publishes posts to Jekyll sites by committing them to their GitHub repositories