After having tried Ghost in early 2015 for Hipster Pixel, I figured it would be either impossible or way too much work to setup a proper iOS publishing workflow. Therefore I decided to switch to a performant and simple solution for Hipster Pixel. Jekyll seemed to be a great platform with renewed interest and in Ruby, a simple language I can easily write code in. Another solution would have been HuGo, but I did not know it existed and discovered it way too late in the rewrite.
The ultimate goal would be to make a simple workflow that I could use in the bus to write and publish articles on the blog. This mind set forces me not to simply sync the post on Dropbox and resume on the Mac. Everything has to be accomplished on my iPhone 6S Plus!
Here is the mental list I made that if all supported would define a successful endeavour:
- Create a new article (post and link)
- Insert images found online
- Insert images from Photos
- Easily insert links and images, with caption
- Insert affiliate links to the Apple Store
- Insert affiliate links to Amazon
- Add Review summary to articles
- Publish article
- Make small code changes
As of today, I’m almost there and the remaining tasks are mostly making things simpler or faster, but they all work. By the time I’m done with this series of articles I will have put the finishing touches on the small kinks left.
Software and Continuous Delivery
Jekyll, falling in the static site generator category, is a system for which a new post is actually a new file that gets transformed into an .html file when the Jekyll build command is run. John Gruber of Daring Fireball and Jason Snell of Six Colors do it similarly with an old version of Movable Type. We will cover the publishing part in this section, as simply as possible but it might be complex so I prefer to warn you in advance. If you are only interested in writing using Workflow, 1Writer, please jump to the next section.
There are three main things you need:
- Private Git repository
- Scripts to auto generate the site from source
- Web servers configured with sources and generated sites
We will cover each of them in detail. But first here’s the summary:
When a new article is pushed to the Git repository, a script executes a Git pull from the source folder on the web server, it then builds the site with the Jekyll command and syncs changes from the source folder to the live site’s folder.
All in all, the process takes between 5 and 15 seconds. I usually frantically refresh the site to see if it works. Worst case scenario, I broke either the YAML or wrote some weird Markdown that breaks the rendering of the site. I have added an email notification that actually sends me the whole script output so I can quickly glance at it for any errors if there are any.
Git Repository and Magic
You can host this on GitHub, BitBucket or even Gitlab. I choose BitBucket because I knew it had a web hook that is executed when a new commit is pushed. GitHub also has it albeit with more granular control (but you need to pay for private repositories), and GitLab probably has them too, but I did not verify.
I use this web hook to trigger a cascade of actions that does everything needed up until the site is refreshed.
I keep all of the source files on BitBucket, no generated site, this way every time my server does a pull it has the very latest files and no junk from a previous regeneration.
Pull New Version of the Site
The commit trigger is sending a POST request to a PHP script I have installed on my server. This script only has one thing to do, run a Git Pull command on the source directory.
Here is the script, please note that you have to customize it to your own server. I have added comments in the script to guide you.
Personally, I have setup a custom API and the “deploy” action is one of the endpoints of my API.
Generate and Sync the new Site
Once the pull is complete, a
post-merge hook setup on the local Git repo of the server is executed. This is a bash script that will build the Jekyll site from the freshly pulled source and do a rsync to the destination folder. This destination folder is where the love site resides and is served from Nginx.
post-merge hook resides inside the repo directory, under
.git/hooks/post-merge and needs execution rights.
That is it, the changes are now live on the site! And with the use of a command line on the computer or Git2Go on my iPhone I can do all sorts of changes on the site!
Writing and publishing
The basic task I need to do is write an article and publish it. We already covered in the previous section what happened when something is sent to the site. This section will cover how to write something for the site.
Generation of the File
Because of the way Jekyll works each post has a YAML section at the top of the file, I invite you to read on Jekyll if you do not know about YAML. All the information regarding the date, title, categories and tags are automatically filed for me in a workflow.
This workflow will ask me for titles, tags and present me a list of categories. The workflow will then take this information to generate a file name according to Jekyll’s standard with the following format:
Today’s date is easy to get and format but the title is a bit more complicated. Being a developer, I used a custom API, I built for many little tasks and one of its actions is to “slugify” the title to make it filename safe.
I will not cover the art of API making but will still share the function so if you want to do it yourself it’s going to be much easier. If you know PHP, you can use Slim or Phalcon (the latter is my favourite because of its performance).
With the answers I gave the workflow, it generates a YAML similar to this one:
--- title: "Git2Go, Your Git Repo on the Go!" category: Review tags: ["git2go","ios","app","review"] date: 2015-12-05 19:32 link: excerpt: seo_description: image: layout: post type: post author: alexandre.valliereslagace --- content goes here!
This is the content of the file and the file name has been generated with the Slugify script. We are now ready to send this new file to 1Writer.
Here is a modified version of my workflow (for the Workflow app on iOS), feel free to adapt it to your needs.
Then it’s writing time! Most of the YAML is already pre-filled so it’s basically just a question of writing the post content using the 1Writer toolbar to help with headers, links and photos.
In a future article I will give you tips, actions and tricks to go even faster and reduce friction when writing (nobody likes writing a ton of symbols).
For this step you will need to create a 1Writer action, I’ve made this simple for you, here it is:
Open in Git2Go (1Writer Action)
Simply use it and update it to fit your repository, service and username. It will add the file to Git2Go and you will then be able to add it to the index, commit and Pull to sync.
Once the file is pushed, the cascade of action from the first part of the tutorial will trigger and in 5 to 15 seconds, your website will be updated!
First of a Serie
In future articles of this series I will detail how I handle images, host images on a CDN with Rackspace Cloud Files, image compression with Kraken.io, easily add links, captions and affiliate links. As I did with this article, I will be sharing many Workflows and actions to help you out as much as I can.
Questions and ideas
I welcome your questions and ideas to make my workflow even better and if you have questions, please share them in the comments below. This way the information you provide will be available to all who are interested in this tutorial!