micropub

This project allows you to create a serverless Micropub and media endpoint which can add files to your static sites' repository. After setup, you can use any Micropub Client to add posts to your site. Tested with Eleventy and Hugo.

To run this, checkout the serverless-micropub repository which provides a basic working example to get micropub setup using Netlify functions.

Install

npm install @benjifs/micropub

Usage

import MicropubEndpoint from '@benjifs/micropub'
import GitHubStore from '@benjifs/github-store'

const {
	ME, TOKEN_ENDPOINT,
	GITHUB_TOKEN, GITHUB_USER, GITHUB_REPO,
} = process.env

export const micropub = new MicropubEndpoint({
	store: new GitHubStore({
		token: GITHUB_TOKEN,
		user: GITHUB_USER,
		repo: GITHUB_REPO,
	}),
	me: ME,
	tokenEndpoint: TOKEN_ENDPOINT,
})

export default async (req) => micropub.micropubHandler(req)

Configuration

The following options can be added when initializing this project:

me (Required)

URL for your site with trailing slash

me: 'https://example.com/'

tokenEndpoint (Required)

Token endpoint to verify the access token submitted.

tokenEndpoint: 'https://auth.example.com/token'

contentDir

The main directory where your posts will be added to.

contentDir: 'src' // Default value

mediaDir

The directory where your media endpoint will add files to.

mediaDir: 'uploads' // Default value

translateProps

11ty uses different naming for properties (eg. name -> title, category -> tags). Settings this value to true (default) makes sure that these properties are translated between what 11ty and the expected valid microformats.

translateProps: true // Default value

formatSlug

You can configure if you want your posts of a specific type to go into a different directory. For example, you can configure all posts regardless of type to go into the same directory or all posts of type note and reply to go into a notes directory.

formatSlug: (type, slug) => `${type}/${slug}` // Default value

formatFilename

Use if you do not use markdown as your file types.

formatFilename: (dir, slug) => `${dir}/${slug}.md` // Default value

mediaFilename

File name for uploaded files. Can be useful if you want the filenames to share a common prefix, or to use a date format other than milliseconds.

mediaFilename: (mediaDir, filename) => `${mediaDir}/${timestamp}_${filename}` // Default value

config.media-endpoint

URL for your media endpoint. If not configured, Micropub clients will not know the endpoint exists.

See 3.6.1 Discovery.

config: {
	...
	'media-endpoint': 'https://micropub.example.com/media',
	...
}

config.syndicate-to

Syndicate target options.

See 3.7.3 Syndication Targets.

config: {
	...
	'syndicate-to': [
		{ uid: 'https://fed.brid.gy/', name: 'w/ Bridgy Fed', checked: true },
	],
	...
}

config.post-types

Define supported post types for a micropub client to show.

See discussion about proposed extension.

config: {
	...
	'post-types': [ // Default values
			{ type: 'note', name: 'Note' },
			{ type: 'photo', name: 'Photo' },
			{ type: 'reply', name: 'Reply' },
			{ type: 'bookmark', name: 'Bookmark' },
			{ type: 'like', name: 'Like' },
			{ type: 'article', name: 'Article' },
			{ type: 'rsvp', name: 'RSVP' },
			{ type: 'repost', name: 'Repost' },
			{ type: 'watch', name: 'Watch' },
			{ type: 'read', name: 'Read' },
			{ type: 'listen', name: 'Listen' },
			{ type: 'game', name: 'Game' },
		],
	...
}

Post Types

The current supported post types are:

• article
• bookmark
• like
• listen
• note
• photo
• play
• read
• repost
• rsvp
• watch
• reply

Note: If a post does not fit under a specific type, it will default to be of type note.

Scopes

• create - allows the client to create posts on behalf of the user
• update - allows the client to edit existing posts
• delete - allows the client to delete posts
• undelete - allows the client to undelete posts
• media - allows the client to upload files to the media endpoint

Troubleshooting

• ME should have a trailing slash

References

• Micropub spec
• Micropub media endpoint
• Handling a micropub request
• Micropub extensions