Every Monday, I publish a new blog post here. I have a few posts I’m working on at once at the moment – but I thought I’d take a week out from them to write about how I manage these posts while working on them. This will be particularly useful if you use Jekyll yourself but may also be of interest if you’re into writing and editing. I’ll explain some code I wrote this week to help my writing.
Back at the end of March, I restarted my blog with Jekyll. I wrote a post to mark the occasion of this blog’s relaunch and since then have been publishing a post once a week.
Jekyll makes writing a blog easy. You simply write a Markdown file, with some properties like the date and title, at the top. Markdown is easy to master and the properties you need at the top for Jekyll’s purposes are called “YAML front-matter” and again are very easy to learn. You can read Jekyll’s own page on how it uses YAML to find out more.
I host my blog on GitHub Pages, which automatically takes care of hosting my files and turning them into static webpages for me. But because I’m using GitHub I became interested, as ever, in the possibilities of versioning my blog and tracking my writing.
Shortly after relaunching my blog I discovered that Jekyll allows for a
Just as it’s possible to view your main posts locally, by using
jekyll serve before you push them to GitHub, it’s also possible to see everything in the
_drafts folder alongside your already published posts by using
jekyll serve --draft. A help page about drafts on the Jekyll site explains this.
I started using this feature almost straight away. But I quickly hit a problem. I didn’t want to commit my drafts, many of which are half-finished posts, to a GitHub repository that might be public. I wanted a place to jot down ideas and develop them gradually into posts before anyone could see them.
So I added
_drafts to my
.gitignore file to ensure they would be passed over by Git. But this left another problem. If everything that wasn’t published wasn’t in my repository, how could I work on my drafts remotely?
I decided to use the fairly simple idea of making the
_drafts folder within my local Jekyll repository a repo in its own right.
When I take the terminal into the
_drafts folder and run
git status instead of seeing the status of my overall blog, I see only the status of draft posts.
And I have set up Atom to see the
_drafts folder as a separate project area, even though on my file system it sits within my GitHub pages repository.
And I push commits within that folder to a private GitHub repository. (I pay $7 a month for my GitHub account so that I have use of unlimited private repositories.)
Thinking in this way has enabled me to think about my
_drafts repo as having its own workflow.
I have five main sub-folders within
_drafts as part of the workflow:
I also have a “zeroth” folder called
reading, which I use for capturing notes while I am studying something. I’ll explain how that works in another post perhaps.
Whenever I have an idea for a post, I create a Markdown file for it. There might be nothing in the file to begin with but the name of the file can serve as a reminder of something I want to write about.
Some ideas haven’t got beyond this “empty file” stage but, if and as I develop an idea, I eventually start to think about how I might structure it as a post.
As the ideas develops, I start creating headers in my Markdown file. The headers act as the main points I might want to cover in the post. This gives me an indication as to whether my idea is actually one post or several.
It also means I’m thinking about the structure from the outset – what am I trying to say and what are the key parts of what I’m trying to say.
Not to get too “meta” about this but you can see this in action in this post. The headers existed before this text did, although I might later adapt headers to fit what I’ve written.
By the time I’ve created my headers I’ve already been thinking about what I want to write. I’m even excited about it; I can see the post already taking shape! In my enthusiasm, I have sometimes even already placed in some draft paragraphs or notes between headers, which I’ll then seek to elaborate.
Once I’m doing this, I tend to move my file from the
2-outlining folder to the
One doesn’t necessarily want the process of editing to get in the way of getting the initial thoughts and feelings flowing. I find it more effective to write a first draft, get it all out into the structure I’ve outlined, and come back to it later to review if there’s time.
I try and leave time between writing the first draft of a post and then editing it. So once I’ve written the first draft, I’ll move it from the
3-writing folder to the
4-editing folder where it will, in theory, sit for a bit. I can then drop in to that folder when I’m in an editing mood and when I’ve sufficient time and distance from the original writing session.
It doesn’t always happen like that – sometimes I will edit as I write. But I always feel less productive when I do so. I try to encourage a good habit of keeping the two activities of writing and editing separate by recognising them as such in my workflow.
When I’m happy with the post (or as happy as I can be within my self-imposed deadline), I’ll then look at publishing it. The first part of this is moving the post to the
blog folder. I call it
blog rather than
5-blog for the same reason I have a folder simply called
images; I want links to other posts in my blog to work whether I’m in draft or in the live blog. And in my live blog, all my posts use
/blog/ in their pathname.
At this point, when I’m moving things into the blog folder, I also include the date and time details in the filename. So this post, whose filename is
workflow-for-jekyll.md as I write on my first draft becomes
201606131900-workflow-for-jekyll.md in the
blog folder to mark the date and time I want it to be published.
Publishing my post
Of course when publishing my post, I want to copy it to the
_posts folder where it will be committed to my main Jekyll repository and appear on the live site.
But I still want a copy in my
_drafts/blog folder because I may need to do further editing in future and I want to, again, do that separately from the live site.
Automating boring bits
So now I have a script that does this work for me.
Until last week, I was manually taking all these steps – moving my finished post to
_drafts/blog, giving it a date and time stamp, then copying it to
_posts but also renaming it there… Don’t forget that Jekyll requires the filename of posts to be a certain format – like
2016-06-13-1900-workflow-for-jekyll.md. (The timestamp is not actually needed but I prefer to keep it.) And Jekyll requires that YAML front-matter, namely:
--- title: "Workflow for Jekyll" date: 2016-06-13 19:00 ---
It was only a matter of time before got too tired or lazy to go through the same process every week, particularly as something like this is so easily automated.
If you like the sound of my workflow and want to adopt it for your own writing and blogging, this script might be helpful.
My script basically assumes that I’ve done the work of putting the file in the
_drafts/blog folder already. At that point I run my script from my GitHub pages repository, by simply typing
./post.sh followed by the name of the file I want to publish:
My script checks the file exists, checks it has a valid date and time string – basically, just looks for a string of 12 numbers in a row – and then copies to
_posts, renames it, and adds the YAML front-matter at the same time. To get the title of the post, it simply strips out the first H1 it finds, removes it from the file and replaces it with the YAML.
This is all pretty basic stuff and achieved in 42 lines (if you include comments and line-spacings) of BASH script. I’ve added the script on GistHub for convenience.
At the end it returns to the console a short-form Git status update showing all the modified files in my GitHub pages repository. This way I can commit several changes at once, which is useful if I’m not just publishing a new post but also correcting some old posts.
For the post to actually go live, I still have to commit it to the repository and push it to the remote repository on GitHub itself.
Because I still have to duplicate effort in some places – for example, commiting changes to my
_drafts repository and to the overall GitHub pages repository, I can see the potential for other scripts around this one. I could do with writing code for handling images, for checking broken links, even for automating tags and categories.
I’d like to explore doing some of these things with Ruby, the language Jekyll uses, rather than BASH which I used here as a quick and dirty method to see the results. Automation-wise, there’s much more I could be doing to save myself time – when I have time.
But writing-wise, I think there’s more to say about my approach to reading and coming up with ideas for posts, as well as the sorts of things I’d like to achieve which would be unique to writing for a blog rather than any kind of writing, which I think my current workflow serves just as well.