Writing is hard, and the many, many different platforms for doing writing and sharing that writing are, more often than not, just adding steps to the process of getting started that just make things take longer. For example, Google Docs is great for some things, but there are several steps standing between me and my words.

I have to

  • log in to Google
  • find the Google Docs app
  • Wait for the Google docs editor to load
  • Give the document a heading and title of some sort
  • Finally start writing

Microsoft Word is on my computer but even more annoying to start up, and with both Word and Google Docs, I’m always distracting by fonts, typography and formatting.

WordPress is great for sharing blog entries, but takes even more steps. On this site, for example, I have to:

  • log into my Dashlane client
  • browse to my dashboard
  • log in
  • wait for the dashboard to load
  • hit the new post button
  • Finally start writing

Admittedly, not that many steps, but when the wifi is slow or, even when it’s not, WordPress can take 30 – 60 seconds to bootstrap itself before it finally loads on my screen. And once I’m in WordPress, the actual writing process is just as distracting as writing in Google Docs or Microsoft Word. The new Gutenberg is interesting, but it really just cranks the bells and whistles to 11.

What I need instead is something quick and minimal, because as it turns out I actually need to do quite a bit of writing. I haven’t published much lately, and I definitely don’t blog regularly, but between emails, letters of recommendation, class planning, committee work, and all of the other things that occupy my day, I’m probably cranking out a couple of thousand words a day.

I used Evernote for a couple of years, and I liked how quick and easy it was to just start writing. Eventually, though, I became frustrated with the lack of portability for my documents, and I also wanted a writing environment with native support for Markdown since I find that goes a lot faster than menu-based WYSIWYG formatting. It lets me mark up the parts that need to look different and then worry about how they actually look later.

So I came up with a process that works well for me. I realize it’s not for everyone, so I don’t necessarily write this as a recommendation for anyone else to try. If anything, I guess I wanted to reflect a little on my writing process and also document the relevant parts of my process in case I ever have to set up something like this again.

The upshot is that I’m doing a lot more writing than I used to. I’ve used this process to create drafts of this blog post, a couple of journal articles and a conference paper, and my day-to-day notes are now accessible, portable, and searchable.

This all relies on the following:

Here’s the whole process in GIF form:

And note, everything after the first few seconds in that GIF is optional. I usually just keep the note open in Sublime as long as I need it, and I rarely view it on the website unless I’m looking for something from a few days ago.

Here’s how it works.

Pico CMS

Pico is the engine that drives the web part of this, and even though I rarely use that platform directly, it makes sense to start by setting that up first because it will provide the directory structure for things that follow.

Pico is a flat-file content management system that looks for markdown-formatted files with appropriate headers and builds a website out of those using [Twig templating](https://en.wikipedia.org/wiki/Twig_(template_engine) and YAMLconfiguration files to render a website very, very quickly.

In my case, after installing Pico with a little customization, I ended up with a directory structure whereby every .md file in the directory /home/<username>/notes.zachwhalen.net/content/blog shows up as a formatted blog entry listed at the public URL on my domain that I set up for this.

Sublime Text and Sublime SFTP

I’ve used Sublime Text as my go-to texteditor for a few years now, and I like it so much I’ve even considered paying for it. The Sublime SFTP package is a nice add-on to Sublime that lets you open and work on remote files directly within Sublime Text.

It also has the ability to synchronize a local folder with a remote folder, including an option such that every time you create or edit a file locally, it uploades that new file to the remote location.

Setting this up takes a few steps, and it took me a bit to discover the key first step, since I don’t normally use the left side bar.

Here’s what I did:

  • In Sublime Text, make sure the side bar is visibly by going to View->Side Bar->Show Side Bar.
  • In my Finder (this is on a Mac) create the folder I want to keep my files in locallly.
  • Drag that folder and drop it onto the Sublime Text Side Bar.
  • Right-click the folder icon there, and choose “Map to remote …” to continue the process of editing a JSON file to add my server settings and.

I used these settings:

    "save_before_upload": true,
    "upload_on_save": true,
    "sync_down_on_open": true,
    "sync_skip_deletes": false,
    "sync_same_age": true,
    "confirm_downloads": false,
    "confirm_sync": false,
    "confirm_overwrite_newer": false,

At this point, I can make new files in that folder, save them, and they’ll automatically upload to my server. It’s already pretty convenient! But I still have to make sure that I save the file as some unique name that ends in .md, and I have to get the header information right or it won’t work, not to mention remembering which folder is mapped to which remote folder and how to open them properly in Sublime Text. Fortunately, I found a solution to all this problems in a bash script.

Bash Scripting

This is the part that may lose some people, if you’re trying to follow along. I use the Terminal on my Mac quite a bit, so there’s almost always at least one window open. I also don’t mind a little scripting, especially when I have an opportunity to automate something that would otherwise be tedious and repetitive.

Mac Terminals (and a lot of other similar environments) use a “shell” software called Bash which apparently stands for Bourne-Again SHell. This is the software that responds and processes the commands when I ls to see the list of files in a directory or cd to move to a different directory.

It’s possible to write scripts just in Bash’s language that perform a sequence of operations in the command line. In my case, and I assume this is standard on Macs and Linux systems, it’s possible to store custom Bash scripts in a normally-hidden file called .bash_profile.

To edit or create this file from a bash terminal, you’d type subl ~/.bash_profile, which will use Sublime Text to open and edit that file.

I want to use a terminal in a similar way to launch Sublime Text with the new note file ready to go, so I came up with a little script that will launch an appropriate-named file with the right header format whenever I type nn in a terminal. I added this to the end of my .bash_profile file:

nn() { 
    ft="---
Title: Untitled Note
Description: New Note
Date: $(date)
Template: blog-post
Tags: 
---";
    dn=$(date +%s);
    echo "$ft" > ~/pg/notes/note-$dn.md;
    subl ~/pg/notes/note-$dn.md;
}

The nn() creates the function that I can later call by typing nn in a terminal. The next part defines the header text into a variable, ft. The dn formats the current timestamp into the cleanest expression (just numbers) so that it will get used in the file name. echo “prints” the first variable, but instead of displaying it, it sends the output to a new file in the folder synced to my remote blog, then finally uses the subl command to launch sublime text where I need it.

At that point, I just start writing, and every time I hit save it uploads that file to my web server for safe keeping and later access.

Blog Options

On the server side, I did a few things to make it work a little better. After some debate and back and forth, I decided to password-protect the whole subdomain where this blog lives. I felt like this would make an easier default. I duplicated this whole process into a public subdomain , jot.zachwhalen.net, for notes that I want to share with people.

Added the “Search” and “Tags” plugins for Pico, though I rarely use the former and never fully configured the latter since they’re kind of redundant.

Conclusions

Overall, I’m quite pleased with this worfklow since it creates a situation where the mechanics of writing are quick and easy, and the key elements of it are things that I already use anyway. The one thing that’s missing I guess is images. I don’t usually need them in my private notes, but they’re often helpful on the public side. Sublime SFTP can handle image files pretty easily, but the workflow isn’t quite as natural since it has to incorporate folders and paths. I think I may set up an automatically-synced folder just as a common image dumping ground.

So that’s how I’ve set up a relatively friction-less writing workflow with Pico CMS, Sublime Text, and just a little customization!