npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2023 – Pkg Stats / Ryan Hefner

format-microformat

v0.11.1

Published

Formats a Microformat JSON representation into eg. a Jekyll post

Downloads

144

Readme

Format Microformat

Build Status Coverage Status dependencies Status Known Vulnerabilities js-semistandard-style

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
  • encodeHTMLnon-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