webpage-micropub-to-github

webpage-micropub-to-github

Self-hosteable Micropub endpoint that publishes to Jekyll by committing to GitHub

#micropub#indieweb#jekyll#api#micropub-endpoint
jekyll logo

Want a Jekyll website built?

Hire a Jekyll developer
Download

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 micropubDocument as 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-microformat can be published to a Jekyll blog hosted on a GitHub, or a GitHub Pages site.
minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog
jekyll logo

Want a Jekyll website built?

Hire a Jekyll developer