Micropub to GitHub
An endpoint that accepts Micropub requests, formats them into Jekyll posts before pushing them to a configured GitHub repository. This enables updating a Jekyll blog through a Micropub client.
Early alpha
Supported:
- Creation of posts
- Uploading of media
- Replacing an existing post with a new version
Unsupported:
- Partial update
- Deletes
Requirements
Requires at least Node.js 14.0.0.
Installation
Install as a normal Node.js application. Add the required configuration values via environment variables or similar mechanism. Or deploy to Heroku:
Endpoint discovery
Once deployed, your Micropub endpoint can be found at /micropub/main e.g. https://example.com/micropub/main.
If you specified more than one site using the MICROPUB_SITES_JSON variable, then each endpoint will be available under the name of its respective key, i.e. /micropub/key-name.
To enable automatic discovery for your Micropub endpoint and token endpoint, you will need to add the following values to your site's <head>:
<link rel="micropub" href="https://example.com/micropub/main">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
Configuration
Required values
The following variables are required to enable a Micropub client to push content to your GitHub repository.
| Variable | Description |
|---|---|
MICROPUB_TOKEN_ENDPOINT |
URL to verify Micropub token. Example: https://tokens.indieauth.com/token |
MICROPUB_TOKEN_ME |
URL to identify Micropub user. Example: https://johndoe.example |
MICROPUB_GITHUB_TOKEN |
GitHub access token to grant access to repository. Example: 12345abcde67890fghij09876klmno54321pqrst |
MICROPUB_GITHUB_USER |
Username/organisation that owns repository. Example: johndoe |
MICROPUB_SITE_GITHUB_REPO |
GitHub repository in which site files are found. Example: johndoe.github.io |
MICROPUB_SITE_URL |
URL where site is published. Example: https://johndoe.example |
Syndication
The following variables can be used to set syndication target(s).
| Variable | Description |
|---|---|
MICROPUB_SITE_SYNDICATE_TO_UID |
Unique identifier of syndication target. Example: https://social.example/johndoe |
MICROPUB_SITE_SYNDICATE_TO_NAME |
User readable name of syndication target. Example: @johndoe on Example Social Network |
MICROPUB_SITE_SYNDICATE_TO |
Complex syndication target. Provided as a JSON array, e.g.: [{"uid":"https://social.example/johndoe","name":"@johndoe on Example Social Network","service":{"name":"Example Social Network","url":"https://social.example/","photo":"https://social.example/icon.png"},"user":{"name":"johndoe","url":"https://social.example/johndoe","photo":"https://social.example/johndoe/photo.jpg"}}]. Not compatible with MICROPUB_SITES_JSON. |
Output style
The following variables allow you to configure the name and destination for files pushed to your repository. These variables will also accept conditional values (described below).
| Variable | Description |
|---|---|
MICROPUB_FILENAME_STYLE |
File name and path for post. Example: _posts/:year-:month-:day-:slug |
MICROPUB_MEDIA_FILES_STYLE |
File name and path for media files. Example: media/:year-:month-:slug/:filesslug |
MICROPUB_PERMALINK_STYLE |
Jekyll permalink style. Example: /:categories/:year/:month/:title/ |
MICROPUB_LAYOUT_NAME |
The name of the Jekyll layout to use for the posts. Set to false to have no layout be added. Defaults to microblogpost |
MICROPUB_OPTION_DERIVE_CATEGORY |
Override the default category |
MICROPUB_GITHUB_BRANCH |
Branch to use for pushes. Useful to test out if things end up where you want them to. Example: micropub |
Complex output styles
These configuration options can all be given different values for different types of content by setting up conditions under which each configuration applies. See conditional values.
Complex configuration
| Variable | Description |
|---|---|
MICROPUB_SITES_JSON |
Complex settings and/or multiple sites (including their syndication targets) provided as JSON, e.g.: '{"site1":{"url":"https://site1.example/","github":{"repo":"site1"},"token":[{"endpoint":"https://tokens.indieauth.com/token","me":"https://site1.example/"}]},"site2":{"url":"http://site2.example/","github":{"repo":"site2"},"token":[{"endpoint":"https://tokens.indieauth.com/token","me":"http://site2.example/"}]}}' |
MICROPUB_OPTION_NO_AUTO_CONFIGURE |
Auto-configure permalink status from the Jekyll repo config. Boolean |
MICROPUB_OPTION_DERIVE_LANGUAGES |
Comma separated list of language codes to auto-detect. Example eng,swe |
MICROPUB_HOST |
Domain name to enforce. Will redirect requests to all other domain names and IP addresses that the endpoint can be accessed on. |
MICROPUB_ENCODE_HTML |
(non-standard) Option to opt out of HTML-encoding of text content if set to false. Defaults to true. |
Conditional values
Conditions are set up by assessing the environment variables using a JSON object of the format:
[
{
"condition": "bookmark OR name",
"value": "value-one"
},
{
"condition": "bookmark OR name",
"value": "value-two"
}
]Conditions are fulfills expressions that apply to the properties of the document being saved. Pretty much any property that can be inserted into a YAML front matter can be matched against. All values explicitly set in the Micropub request are available, but some defaults and derived values may not be available, depending on the option configured.
Please open an issue and let me know what conditions you would like to set up.
Modules used
- micropub-express β an Express Micropub endpoint that accepts and verifies Micropub requests and calls a callback with a parsed
micropubDocument. - format-microformat β a module that takes a
micropubDocumentas its input, and converts this data into a standard that can be published elsewhere. Currently supports the Jekyll format. - github-publish β a module that takes a filename and content and publishes it to a GitHub repository. The formatted data generated by
format-microformatcan be published to a Jekyll blog hosted on a GitHub, or a GitHub Pages site.
Related
- My 2015 in IndieWeb β post from 2016-03-12 by @voxpelli
- miklb/jekyll-indieweb β a Jekyll theme built with the IndieWeb in mind
- voxpelli/voxpelli.github.com β first Jekyll blog to use this Micropub endpoint
- webmention.herokuapp.com β another IndieWeb project suited for Jekyll, this one for Webmention