A Publishing Workflow

I am a big fan of the static-site movement. As such, I have been going through all of my web sites and converting the ones that can be served as flat files to this type of simple platform. We have recently converted the Behance Tech site from WordPress to static files and would like to document our new content publishing workflow publicly so that others may learn from it or perhaps offer their own opinions.

I’ll begin by saying, as a technologist writing for the web, I find the Github pull request workflow combined with the benefits of static site platforms to be liberating and invigorating. Here are some of the key reasons why:

  • Served using Github Pages (no server costs)
  • Inherently secure
  • Write in your preferred editor, not some substandard web editor
  • Write in Markdown with “markup” that stays out of the way
  • Write limited meta data at the top of the file
  • Open a pull request to get review of the post
  • Merging the pull request publishes the post

There are many benefits and not many downsides, IMHO, and it seems to be a no-brainer decision to move to this approach. This may be partly because as a technologist I am comfortable in the world of text editors and versioning repositories, but I think other non-tech people could get on board too.

Here are the basic steps for a contributor to get involved:

tl;dr

  1. fork; clone; branch (basically, get a copy of the code locally)
  2. write;
  3. commit your work; pull request; merge/publish

More Details:

  1. If you haven’t already, fork the master repo, clone it locally
    * optional: for this workflow, it is best to create a branch for your post
  2. Add yourself to the authors file if this is your first contribution
  3. Write in markdown (.md) with the minimal meta information at the top of the document
    * optional: use the _drafts folder if you are not publishing on merge (scheduled posts)
    * optional: commit the work to manage “revisions”; push to your remote to keep your work “backed up”; open the pull request only when you are ready
  4. When ready for review (final or incremental), push the post to your remote and open a pull request
    * note: if it is a post scheduled to be published at a later date or if you are looking for comments and not ready to publish, keep the post in the _drafts directory; if the post is ready to be published immediately, move the file to the _posts directory and prefix the filename with the date (2015–09–27-my-fence-post.md) before opening the pull request
  5. Colleagues can then view and comment on the content (potentially with a “diff” of a previous version, if one exists in the “upstream”)
  6. Once you and the reviewer(s) are satisfied, merge the PR. If the content was moved to the _posts directory in the PR, then you are now “published”

There may be some unfamiliar terms above (depending on your skill level and experience with these particular tools and techniques), but hopefully the bullet points and steps were conceptually descriptive enough to walk you through the flow at a high level and demonstrate the benefits.

This post originally appeared on BehanceTech.net

Show your support

Clapping shows how much you appreciated joe sepi’s story.