Why post from spacemacs?
I use spacemacs a lot – for all of my coding, and for all of my personal organisation with org-mode. It’s my favourite place to edit text. I’ve been learning Emacs Lisp lately (the language in which much of Emacs is written) and setting up a Micropub client written in Emacs Lisp will be a fun project. In the process I should learn a bit more Elisp and also a bit more about how Micropub works. That’s enough justification for me!
(I should of course point out that there’s absolutely no necessity to go anywhere near Emacs to post to an indieweb site. There’s a million different ways to post to your site – I just happen to want to tinker around in Emacs.)
Micropubbing
My website is an Indieweb site, and as part of that it has a Micropub endpoint. Micropub is a standard for client-to-server communication for creating posts. It gives you a nice well-defined separation of concerns between client and server for creating new posts on your site. Any client that supports Micropub can post to any server that supports Micropub, via its Micropub endpoint.
My site is a WordPress site, but thanks to the Micropub spec (and the Indieweb WordPress implementation of that) I can post to it from a multitude of clients. I can use a browser plug-in (Omnibear), the command-line (shpub), my mobile (Indigenous), another web app (e.g. Quill), or, even better, from within an Indieweb reader (e.g. Monocle, Together, or Indigenous). None of these clients has to know a thing about WordPress, they just speak Micropub – and can work with any other site that speaks Micropub, whether that site is running on WordPress, Jekyll, rails, django, drupal, or some bespoke handrolled framework.
emacs -> micropub
So, lo and behold, there’s already a github repo out there with a spacemacs layer for micropub: https://github.com/hjertnes/micropub-layer.git
(A spacemacs layer “brings together one or more packages, as well as the glue configuration code required to make them play well with each other and Spacemacs in general.”)
The micropub layer is pretty simple, so the Micropub functions as they are could probably just as easily be loaded as a single .el file for standard Emacs.
After you’ve cloned the files into your .emacs.d/private, the first thing in the README is configuring the Micropub layer with the values for your micropub endpoint, and your authorization token, e.g.:
(micropub :variables
token "YOUR_AUTH_TOKEN"
endpoint "YOUR_MICROPUB_ENDPOINT")OK so we need the micropub endpoint and an auth token.
This is the end(point)
Your micropub endpoint should be linked in your site’s source. e.g. I have
<link rel="micropub" href="https://doubleloop.net/wp-json/micropub/1.0/endpoint" />so my micropub endpoint is https://doubleloop.net/wp-json/micropub/1.0/endpoint (provided by the WordPress Micropub plugin.)
gimme a token
A Micropub client needs to be authorized to post to your site. The Micropub authentication process is handled via IndieAuth, which is built on top of OAuth 2.0. Basically a client has to obtain a token from the site it wants to post to, and send that token every time it tries to do a post. The OAuth flow is a bit beyond my Elisp capabilities at this time, so to begin with I’m cheating and using gimme a token to get a token for my client. Later I’d like to add the auth flow into Emacs itself, but this will do for a start.
So follow the instructions at gimme a token to get a token.
(Side note: I hit an issue when using gimme a token with my WordPress authorization endpoint. It seems to be expecting a state parameter, but gimme a token doesn’t send one. The wiki page on authorization endpoints seems to suggest that it is optional. But without it I get the error Missing Parameter: state. Not sure what the issue is, but I’ll report it upstream when when I’ve figured out a bit more as to which upstream to report to. Anyway, if you just append some arbitrary value for state to the URL yourself, the WP auth endpoint is happy.)
Save the environment
I keep all of my dotfiles in source control, and I follow the tradition of sharing them in a public repo, too, in case any of what I’ve set could be of use to other people. My spacemacs config file is included in that.
As such, I can’t put my endpoint auth token in there, as suggested in the project’s README. With the token, anyone could post to my endpoint.
So to pull the values in, I set the values I need in a .local bash file of environment variables that should never leave my machine. I source that as part of my .bash_profile so that spacemacs can see them.
e.g.
#!/bin/bash
export EMUPUB_TOKEN=asdf
export EMUPUB_ENDPOINT=https://my.site/micropub(The endpoint doesn’t need to be secret, as it’s publicly discoverable anyway, but I just put it in to an env var anyway to go with the token.)
With that, my spacemacs config for the Micropub layer becomes:
(micropub :variables
token (getenv "EMUPUB_TOKEN")
endpoint (getenv "EMUPUB_ENDPOINT"))Give it all a refresh, and et voila – if you then put some text in a buffer and do:
M-x mp-updateyou’ll send the text of the buffer as a note to your site! Awesome.
future things
Some next steps I would like to add to the Micropub layer:
- I want to be able to send a region rather than a whole buffer
- I really want to be able to discover, and then subsequently choose to post to, my syndication targets
And beyond that, as mentioned earlier it would be cool to have the OAuth flow happen within Emacs itself.
But that’s it for now. micropub.rocks!
Reads