building pages

So I’m at a bit of a crossroads here. What should I do to build this website? On the one hand, it’s not that hard to run it it’s current state. There are three basic steps.

Publishing With Hugo (Three Basic Steps)

1. Create page.
   • This involves me opening the terminal, and typing hugo new post/my-post-title.md. It takes a second.
   • This could be automated: Hugo doesn’t have to be aware of the new page, this just automates adding frontmatter.
2. Write page content.
   • This is obviously the hardest part. I have to try and write something coherent.
3. Build and Upload
   • Back to Terminal again, this time I just type hugo. That calls Hugo up, it builds the HTML in the ../public folder, and out it goes.
   • Now I open Cyberduck, and drag the folder over.

This all takes from the DangerGinger blog, which was an inspiration in getting me to set up Hugo again.

What’s really happening?

Ah, you caught me. There’s actually many more steps than that. Hugo isn’t your Dad’s CMS.

1. Create Page
2. Find and open file
   • Open Atom and find the file, or locate in Finder and open it from there.
   • The file gets created in ../content/post, so it’s not hard to locate it.
3. Set tags to my liking
   • The frontmatter default is specified in the theme archetypes.
   • In other words, the metadata is automatically filled in from a template. It currently looks like this: +++ date = "2014-07-11T10:54:24+02:00" draft = false title = "Post title" ...
4. Write post
5. Save File, Build Sit
6. Commit to GitLab CE install
7. Open Cyberduck, transfer files

That’s really it for the most part.

Now the question is - how do I make this easier?

Web Infrastructure

The files for the blog live locally on my iMac, but they also exist in a private GitLab repo¹. This is accessible from anywhere there is internet access, and I also have a shell account to make changes if needed.

The site is hosted on DreamHost, using their regular Shared Hosting platform. I’ve been using it for a few years, and it’s been pretty solid.

Edit (2018-01-13): The site was on Dreamhost, but is now hosted by the wonderful Boniface Labs.

Optimizing Desktop Publishing Workflow

This is an area where a bit of experimentation will be required. My current tools: - Atom, from GitHub - My text editor of choice, and really where I write everything. Code, plain text, Markdown, you name it. - SourceTree, from Atlassian - Simple, free, graphical Git client. There are other nicer ones, but you can’t beat free.

Atom has support for “Snippets”, so I can program the Hugo front matter in, and voilà - we have the start of a blog post. This still isn’t as automatic and easy as I would like, but it will work for now. If I used something like TextExpander, then I know I could set up a snippet that could also prompt me for a post title, tags, etc.

Once I save the file, or I’ve saved a version of it at least, I make my way over to SourceTree. I’ll usually commit at the end of the night, or at the end of a big writing push, and then I will push that to GitLab. If I can find a good package for Atom that allows me to push commits right through, then I’ll look into using that.

Creating A Mobile Workflow

There are a lot of apps that will handle Markdown on iOS, but I haven’t purchased any yet. They seem to have a lot of powerful features, or some other add-ins that I don’t really need.

Right now, I use these apps together: - Letterspace, from Sittipon Simasanti - An app that I installed when new, forgot about, and recently re-installed for many reasons - Working Copy, from Anders Borum - Comes with high praise from @vittici, and @ismh - Workflow, from DeskConnect, Inc. - Again, with high praise from MacStories

The gist is this - If I want to write a new post on mobile, I run a Workflow that I’ve created, called “Post for Hugo”. What this workflow does is bring up a few prompts: What is the Title of the post? Is this a draft or non-draft? Do you want comments enabled? Any tags? Basically it asks me all the questions that I think are pertinent from the Front Matter mentioned earlier. Once that’s done, it generates the correctly formatted date and time, and inserts that with all my answers into a formatted block of text. It takes all this content and URL Encodes it, so it can get passed to an undocumented x-callback-url, that creates a new entry with that text.

I had originally experimented with having Workflow create the file in iCloud Drive, where Letterspace stores its files, but I think just passing the content to the app is better in the long run. A disadvantage is that Letterspace uses the first line of the document as the title, so all I see is front matter when scrolling.

I am thinking of also creating the reverse of the workflow - Start a post in Hugo (then it will show the correct title at the top), and then use the Share Sheet to parse the content through Workflow. I can use RegEx to determine what the lead line is, use that as the title, and go from there. Another option for the Workflow automation is to add a Full/Quick prompt. That can let me choose if I want to go through all the “setup” prompts for the post, or just get a title and use trusted defaults for the rest.

At any rate, once the post is “done”, I can preview it in Letterspace to get an idea for what it will look like. The preview function gives me a word count and estimated read time at the bottom of the screen, which is handy for a quick proofread. Once I’m satisfied, the idea is to use an Action Extension to send it to Working Copy. Once in Working Copy, I can commit it to the repository I have set up, and I know it’s saved for later.

The Power of Git/GitLab

This is where the magic really happens. I don’t have this set up just yet, but the plan is this: If I commit to the blog repository and push it to the remote, I can push to one of two branches. There’s drafts, and production. Everything gets pushed to drafts by default, but if I push it to Production, GitLab takes over.

Once the push is complete, a GitLab Runner in the shell will take the content, and run the Hugo command. This will re-build the blog’s files, including any posts where draft = false. If a tagged draft sneaks in there, it doesn’t get published by default. The Runner will then rsync the files to my DreamHost account, and report back if the build passed/failed. This would effectively take my blog updating down to a fully automatic process.

Again, I don’t have this set up yet, but it’s on the horizon.

Closing Thoughts

So I’ve gone through a lot to get this set up. Could it be faster? Absolutely. That’s where I have to exercise some chops to streamline things a little bit. Could this be easier by using, say, Ghost, Tumblr, Medium, or WordPress? Absolutely - but I wanted something that would create static pages, do everything in a self-hosted fashion (not including web host), and stay within my control. The best part is that each component is interchangeable. If I decide to use BBEdit on the Mac, and start using 1Writer or Editorial on my iPhone, it’s a simple change to make them fit in the workflow.

The hardest parts are almost all behind me. You should see a lot more posts in the future. Welcome.