These are the bits that going into making up one of my blog posts.  I make decisions on each of these points and create something that is hopefully useful and satisfying to me and an artifact to share that others might draw inspiration or help from as well.  



## Types of Posts

I divide my writing into two kinds of posts: technical and non-technical thoughts.  

The technical post are recounting how to do specific things.  They are usually step-by-step instructions.  They help me remember things important to me.  They are useful to others as we often follow similar technology paths.

The thought posts are just things on my mind.  It's more free prose.  These are the things that I've been contemplating and consider of some importance.  Hopefully these posts can inspire others to create better lives for themselves as well.

## Choosing a Title

If I'm writing a technical post, I usually choose one that matches what my Google search term would be when trying to accomplish the task as I see it.  It's usually good for SEO and clarity.

If sharing my thoughts, I usually use something more abstract.  I like something with some whimsy, often hinting at the subject.  Having something to discover can be fun to read and to write.  Sometimes I draw rather tenuous connections here between the title and the subject content.

## Saving some Meta Data 

Meta data for the post usually consists of those things that help in blog organization or Internet discoverability.

### Category

Mapping well to the types of post I write, I currently assign posts on my site to 3 categories: "Code" (technical), "Leadership" (thought), and "Book".  (I also record short summaries and sometimes reviews of the books that I read on the site.)

The "Code" category is vast but easy to categorize.  The "Leadership" category can be about any number of things: soft skills, productivity, communication, teamwork, or culture, etc.

### Tags

I define a few tags for the post.  There is usually an attempt to reuse tags that are already on the site.  There is a view for reading posts one tag at a time.  I hope that this helps enable readers who are interested in a certain theme.

A few recent tags are: js, react, environment, productivity, rest, tdd, testing.  You can browse [all the tags](/tags) yourself.

### Description

This is a short summary that appears in the Google search results.  It supports the title.  It is usually one sentence, maybe two, that clarifies the content of the post and encourages reading.

## Making an Introduction

The intro is a slightly longer restatement of the description.  Sometimes it's an exact copy.  I try to include the "why" of the post if it's not obvious.  This is the value statement, telling why the reader should read more.  It often includes the essence of whatever thought or tech I'm about to explore in the post.

## Choosing Headings

I use headings to group my thoughts.  I like encountering these in articles that I read.  They help lead my mind through the aspects of a subject.  For me, these usually grow out of my outline or notes.  Sometimes they're a chance to turn an phrase. Other times I'm thinking of SEO help when I choose my headings.

Headings will group my related thoughts or label the next set of steps needed to accomplish a technical outcome.  There are usually just a few paragraphs per heading.

## Finding My Voice

I try not to be another whining, complaining voice on the Internet.  I want the post to sound positive and fun.  Many companies purposefully avoid the silly.  I am embrace it.

If the topic is objective, mostly technical, using "you" in the text feels quite natural.  "One" usually feels too formal for me.  If I'm expounding on a topic that's a more touchy-feely, I try to use "we" when addressing the reader.  I don't want to be too preachy, and I want to include myself in prose and in practice.

Most of the time I try to write like I talk and just let it -- flow.

## Creating Code Blocks

Essentially all my technical posts include code blocks.  This is often my favorite part of technical blogs that I read when I'm trying to figure something out.

I try to keep the code short.  I often draw from code I've written lately in real life or I sometimes make up something (that I hope visually compiles) on the spot.  I take time to remove cruft in order to expose the essence of the concepts.  If the code is not short or is dense with concepts, it usually has to be followed with lengthy explanations.  To keep these more terse and scannable, I sometimes use bulleted lists to organize these.

## At Length

My goal for a post is to have the final length about 500 words.  I believe that people lose interest after that.  Maybe I should say *we* lose interest after that.  I have lots of posts that are longer, probably in the 600-900 word range.  I have some that are much longer.  Most of those are long technical processes.  You might find me pontificating about some other topic too.  To get a post this short, I try to remove rambling sections, repetition, and edit for precision.

## Conclusion

My conclusions are usually quick.  They wrap it up by restating the essence of the intro really quickly.  Here's what we should have learned by reading this.  

I try to end with a question.  My hope is that this keeps the conversation going.  It is an attempt to get the reader to reflect on and apply what they've been reading to their own situation.  This is especially important in the thought pieces.  It's also an invitation for those readers of technical posts to share their own solutions.

## Banner

The banner is visually interesting, which I like.  It's an opportunity to bring more fun into the post.  It allows me a chance to do some illustration, which I enjoy.  It's often another place to include some abstract allusion to the subject.

And that's it.  I get those bits onto the page and ship it. If you're interested, I can share a bit more about my process in getting to those bits.  What are the things that you include in your blog posts or your approach that you find helpful?

These are the bits that going into making up one of my blog posts.

Anatomy of a Blog Post

There are a few options for client-side code highlighting.  [Highlight.js](https://highlightjs.org/) is one of the most popular, and it's super easy to integrate into your site.  Let's do it!



## Compared to Server Side

I usually default to server-side code highlighting.  It puts the complexity of code highlighting in the build phase and keeps the runtime simple.  The most popular server-side option is [pygments](http://pygments.org/).  I have used this for many years.  Unfortunately, in my latest [conversion to hugo](/post/conversion-from-octopress-to-hugo/), I realized that the support for server-side highlighting was not good.  Not only was it slow, I found out over time that many simple things weren't even getting correctly interpreted as code blocks (eg, anything json or html, which should be common types, right?).  So I switched to Highlight.js on the client side.  I was pleasantly surprised at its simplicity.  Besides the couple new network requests, it's really simple for the consumer of this library.

## Include the Script

First, include the script near the bottom of the page that has code blocks on it:

```html
<script src="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/highlight.min.js"></script>
```

Next, call the Hightlight.js initialize function:

```html
<script>hljs.initHighlightingOnLoad();</script>
```

When this function runs, it'll look for the `pre > code` blocks, like this:

```html
<pre>
  <code class="language-js">
    const nacho = anaconda => squeeze(anaconda)
    console.log(nacho())
  </code>
</pre>
```

And turn them into:

```html
<pre>
  <code class="language-js hljs javascript">
    <span class="hljs-keyword">const</span> nacho = <span class="hljs-function"><span class="hljs-params">anaconda</span> =&gt;</span> squeeze(anaconda)
    <span class="hljs-built_in">console</span>.log(nacho())
  </code>
</pre>
```

## Include the Stylesheet

Now that the code snippet has been parsed and class names added to elements representing the different parts of the code syntax, we want to color it.  There are [several options for styles](https://highlightjs.org/) available on the hightlight.js home page (though the ui is weird -- just click the "style" link under the code sample there to cycle through options).

I like one called `atom-one-dark`, so I will next include that stylesheet in the `<head />` of my page that contains code blocks:

```html
<link rel="stylesheet" href="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/styles/atom-one-dark.min.css" type="text/css" media="all" />
```

That's it.  You're now set.  Just load your page in the browser, and it should apply the highlighting.  That was easy, right?  Do you prefer client-side or server-side code highlighting?  Do you use Highlight.js or something else?  Any favorite highlighting themes?

Highlight.js is a great option to add client-side code highlighting to your blog

Add Client-side Code Highlighting to Your Blog

Several weeks ago, I decided it was time for me to move on from Octopress.  It's given me a good run.  But there were a couple of causes that pushed me over the edge.  My experience has been good with a few pains in the conversion.



## Outgrowing Octopress

The most fundamental and important reason for me converting from Octopress is that it was getting slow to build my site.  I'd write an article, run `rake generate`, and it'd take (anecdotally) 45 seconds.  Wow, impatient, right?  Well it was apparently enough to make it less fun to write on as a platform.

Updating my site's layout on Octopress was also troublesome.  I had written my own theme, but I had worked my custom theme into the existing `sass` and template hierarchy that exists in Octopress' default theme.  These files are a tangle and hard to work with.

Octopress has made rumblings about being updated and improved upon.  But these efforts have been silent as of late.  The last commits on Jekyll's Ferrari (v3), as of this writing, were a full year ago.

Finally, I usually welcome an opportunity to learn something new.  I was on the hunt for a platform that would enccourage my writing.

## Tried Hexo

I looked at Hexo.  It looked rather promising.  It's based on Node.  The docs were extensive.  Initial speed tests were pretty good.  It seems like a pretty cool project.  But then I pushed close to 300 articles into it, and it slowed down significantly -- about 30 seconds to build the site.  Then I read some github issues about how people were having similar problems.  Then I tried to extend it with different types of content beyond blog posts (a core use case for the next generation of my blog), and got lost in creating new Hexo generators.  So I kept looking.

## Fun with Hugo

Hugo was another static site generator that appeared high on a number of top 10 lists.  It is written in golang.  I picked it up.  I identified with a marketing slogan high on their list: "Make the web fun again."  Yes!  This is essentially how I wanted to feel when I thought about adding another post to my blog.

### Hugo is Fast

Initial tests with speed were mind blowing -- near instantaneous.  Then I added almost 300 articles.  The live server and blog generation were still quite fast (606ms):

```
278 regular pages created
210 other pages created
2 non-page files copied
287 paginator pages created
198 tags created
8 categories created
total in 606 ms
```

This is a fresh build.  The caching, however, makes it even faster.  Two builds in a row will yield a second build that's faster (barely, 596ms). 

I realized that part of the fast speed was because it wasn't doing code highlighting, which I wanted on.  I read through the docs at how to turn those on.  They're actually run in python by pygments, and the docs say they're slow.  Yes, the build time went way up (15s). But again, caching still helps significantly here (in a tests, anywhere from a total 800ms to 3s) -- and is a lot more important.  The dev cycle response time is enjoyably fast.

### Templates are Easy & Intuitive

As I have rebuilt my blog on Hugo, I've been pleasantly surprised at how easy things have been to figure out and implement.  Templates are written in go templates, which are pretty nice.  There are good built-in parameters for the site and each page available in the templates.

Creating arbitrary types of content is super easy with its cli tool (via `hugo new`) that doesn't really assume anything and doesn't try to be too clever.  I can easily start new "sections" of content.

Most things are driven by a template.  They go in intuitive locations and are easy to override -- for different sections, the sitemap, and rss feeds.  There's good template fallbacks with the `_default` section.  I can find simple instructions for desired features in the docs.

### Things I Wished Hugo Had

The theme install instructions are odd.  I suppose if you want a plug n play theme, they're fine.  But I have just put my custom theme straight into my blog git repo, not using a git submodule as instructed.  

There are a few features that I miss from Octopress, including the ability to give code snippets file names.  That's apparently not generally-accepted markdown, but it's super nice.  I could write a shortcode, equivalent to Jekyll's plugins, but I'm trying to keep my Markdown vanilla parseable.  It also seems that Jekyll was more forgiving of my sloppy markdown formats.

## Data Conversion

In order to make the migration to Hugo from Octopress, my source content markdown files needed some changing.  Lots of this was in the front matter.  There were a few issues in the body of the content as well where I was using things that Octopress supported but that Hugo did not.

### Date Format

The publish date in the front matter for Octopress was in the format of:

```
date: 2015-02-28 16:20
```

Hugo wanted it in the format of:

```
date: "2015-02-28"
```

I changed this with a sed script:

```
find ./ -type f -exec sed -i '' -E "s/(date: )([^ ]+).*$/\1\"\2\"/" {} \;
```

### Split Categories

As far as I know, Octopress didn't support categories.  So I mixed my categories in as tags for my posts.  Hugo can treat them as separate things, so I split out what looked like this:

```
from: categories: [Code, heroku, dns]
```

Into this:

```
categories: 
  - "Code"
tags: [heroku, dns]
```

This is partial step, not the final format.  We'll finish it soon. 

To get categories onto a new line, it turned out that I needed a new version of `sed`.  Instead of the BSD version that's on the Mac by default, I had to install the GNU version:

```
brew install gnu-sed
```

This is apparently because the BSD `sed` can't read newline charaters `\n` in a regex.  It needs the literal new line (as in, press enter).  That seems like a pain for a nice, copy-pasteable regex.  So, in this command, I used `gsed`:

```
find . -iname "*.md" -exec gsed -i -E "s/categories: \[(\w+)(, ?)(.*)$/categories:\n  - \"\1\"\ntags: \[\3/" {} \;
```

### Format Tags

The remaining comma-separated array of tags that I was using in Octopress land wasn't apparently real yaml at all.  Anyway, Hugo didn't like it.  So, I was going to make a bulleted list.  To go from this:

```
categories: [heroku, dns]
```

To this:

```
tags:
- heroku
- dns
```

I needed to run a couple `sed` commands in a row (because I couldn't figure out how to do this with a single command).  The first command is for the posts that have one tag, then 2 tags, and so on.  I'll show you the first two.  You can extrapolate from there:

```
find . -iname "*.md" -exec gsed -i -E "s/tags: \[([a-z-]+)]$/tags:\n  - \"\1\"/" {} \;
find . -iname "*.md" -exec gsed -i -E "s/tags: \[([a-z-]+)(, ?)([a-z-]+)]$/tags:\n  - \"\1\"\n  - \"\3\"/" {} \;
```

### Moving Cover Image Into Front Matter

For a couple years, I've put a cover image in the body of the post text, right at the end of the summary section.  I wanted to move this into the front matter.  It would give me a little more visual control.  I tried many, many `grep`, `sed`, and even `perl` commands to try to make this happen.  In the end, I went through articles manually.  That turned out to be a blessing in disguise (at least I tried to squeeze lemonade out of it), and I could make other adjustments to data, where my style has changed in various ways over the years.

I found files with images using this `grep` command:

```
grep -o -c "^\!\[.*\]$.*$" * | awk -F: '{if ($2 > 0){print $1}}'
```

### Remove Code Snippet Filenames

One of the features I really liked from Octopress was the out-of-the-box support for showing file names on code snippets blocks (the ones that use 3 backticks surrounding the block). Apparently, however, this is not standard Markdown trickery, or at least Hugo doesn't like it and stops all formatting if it detects it.  It would be much nicer if it just ignored it.

Again, I was stifled in my automated solution to this.  I spent a bit of time on this, but since it affected a relatively small amount of files, I learned my lesson from the pain of time spent on the cover image transform and just went for the manual editing. I think the problem had to do with the backticks not being well-supported (or at least understood by me) in the `sed` replacement command.  So I just found the files like this:

```
grep "^$\`\{3\}[a-z]\+$ [a-zA-Z_\-\.\/\-]\+" *.md
```

### Strict Hash Separation

In markdown, you make header text using the leading hashes.  Apparently, I had hashes that butted right up next to the header text in some cases.  Octopress dealt with that ok, but this new parser used by Hugo didn't like it and would render hash literals.  To make the strict separation, I ran:

```
find . -iname "*.md" -exec gsed -i -E "s/^(#+)(\w+)/\1 \2/" {} \; 
```

In all, the Hugo conversion has led to a fast development cycle of a fast static site.  It has brought some of the blogging fun back.  I did a visual redesign at the same time, and that's been fun too.  If it still looks like a painterly celestial scene when you read this, let me know what you think of it.  

Are you using Hugo?  What do you think of it so far?

A story of my migration from Octopress to Hugo static site generator

Conversion from Octopress to Hugo

Why would one choose Octopress over WordPress?  What are the pros and cons?  I've recently implemented a blog -- this blog -- in WordPress.  It was a difficult decision for me.  At the time, I looked at Octopress, but I was jazzed by the success of others on WordPress, and I wanted to try it out.  I'm glad that I did try it out, but now I'm glad that I've switched to Octopress.  Here's why.



## Just Posts
Octopress is so dead simple, it just makes sense.  The post is a file in a folder.  I edit it in my current favorite MarkDown editor, [Mou](http://mouapp.com/).  The workflow is thus very easy.  I'm not transferring my post which I wrote offline to a web interface only available online.

## Nerd Cred
Nerd cred or geek cred?  I don't know, but Octopress bumps it right up.  As it says, it's a "blogging framework for hackers".  Given that I'm a creator of software and that's the main topic of my blog, it seems fitting, doesn't it.  Plenty of coders have WordPress sites, I suppose.  Still, I didn't feel super awesome about running a WordPress PHP site as my home base.

## Performance
The whole idea of a generated static site seems genius.  It's blazing fast.  I'm on Heroku.  Currently, my site experiences very low volume traffic.  With one dyno, when the site goes without traffic for a certain amount of time, Heroku will power down the dyno.  WordPress takes a fair bit to come back up on the first request after that.  Octopress, no problem.  Pops back like it was never gone.  And why not?  There's really nothing to spin up.

## No Reinvention
I landed on Octopress for one of the same reasons I initially chose WordPress for this new blog.  It is a ready-made blogging platform.  I don't need to reinvent the wheel.  It works, and it works well.

## A Bit of Customization
I chose WordPress for the blog because I wanted to write blog posts, not tinker with the innards of the site.  (I do that plenty elsewhere.)  But it turns out that I couldn't quite bare just using an out-of-the-box theme.  I literally needed to add my own flair and customizations.  I still want to keep that to a minimum.  Octopress' classic theme (the only one?) is fantastic -- clean and crisp.  When I want to make a few changes, it's a much more straight-forward task to find the place that needs editing and get it done.  

## Ruby
I've hardly done any Ruby.  Octopress is an easy little touch of Ruby.  I don't have to mess with it unless I want to.  Ruby is much more appealing to me than PHP.

## Plugin Pluses
When I chose WordPress, I figured that if there was any feature that I desired, there was probably already a plugin for it.  And that turned out to be true.  Octopress certainly [has fewer options](https://github.com/imathis/octopress/wiki/3rd-party-plugins).  But on the whole, I think they cater well to the coder crowd.

## For Now
So, for now, I'm on Octopress.  It's nice to think that my data is just a folder of files that I could really recreate anywhere.  So, we'll see how long this lasts.  So far, it's a blogging platform for this hacker, and I'm liking it.

Octopress vs. WordPress.  Which should I use for my blog?  I chose WordPress first, then went to Octopress.  Here are some points of comparison.

Octopress vs. WordPress

I was inspired by [Michael Hyatt's book, Platform,](https://jaketrent.com/post/platform-book-review/) to start writing this blog.  As he suggested, I just started writing.  But also as he suggested, I've been percolating over what my blog topics will be.  I've just been writing for several weeks.  I've finally settled in on a number of categories that will help me focus a bit.  But each are plenty broad to be able to write on most any and all things related to software.



## [Code](https://jaketrent.com/post/category/code/)

I'm a coder.  This is probably my favorite category.  This is what I wake up in the morning and do.  Posts in this category will be heavy on the code snippets.  They will sometimes link to demos.  These will be the most technical of the posts

## [Design](https://jaketrent.com/post/category/software-design/)

I have a desire to use and expand my design skills.  I'll probably never commit enough time to really be a fantastic designer like many that I know, but here I'll post my own feeble designs and talk about all things having to do with look and feel and user experience.

## [Productivity](https://jaketrent.com/post/category/productivity/)

Software is such a malleable medium.  It is an art in many ways.  Thus there are many ways to make it happen.  Some methods work better for others.  Some processes improve upon those of the past.  Some ways are better than others to make a team work well.  Ideas similar to these will be posted here.

## [Reviews](https://jaketrent.com/post/category/reviews/)

The world of software and technology is rich with resources and activity.  With so much to choose from, sometimes its helpful to have a suggestion or two on where to (or not to) focus some time and energy.  Software, books, and conferences are subjects we've seen so far.  The reviews are worth the price of admission.  Get them here.

## [Announcements](https://jaketrent.com/post/category/announcement/)

Public service announcements will include things about me or the blog in particular that are informational but not to any end.  This post fits in this category.  Where a full review is not offered, tidbits about the software world in general might fit here.

## Blog Topics

It turns out that it's somewhat hard to choose topics to write about on one's blog.  At least it is for me.  The tech world is changing quickly.  I'm one that likes to change it and and change with it.  So, these topics may evolve.  They seem broad enough to continue to be applicable.

If you were to choose my next post, which category would it fit into?

Blog Topics

Some might ask why a guy who loves his life of code would choose WordPress as the framework for one of his websites. Well, I chose a WordPress blog. I almost didn't. It's been a long time coming. It's early in the game, but I think it was a good choice.



## Why I wouldn't choose WordPress blog

I only had one job about 7 years back that consisted of mostly PHP. The job was great for many reasons. PHP wasn't the highlight. We did some cool stuff with it. At the time, it was all right. Since, I have coded full time in Java, Python, XQuery, or JavaScript. I would count each as **more** enjoyable than PHP.

Secondly, I'm a coder. I love to build stuff. Custom software is way more fun than boxed software. WordPress is something that is literally accessible to anyone that's just computer savvy. I'm not breaking new ground on WordPress.

## An insightful article

A week or so ago, I ran into an article on a site called "Virtuous Code". That site name was cool enough. The article was typed ("penned" is such a cooler word) by Avdi Grimm and is named ["Why WordPress"](http://devblog.avdi.org/2012/08/09/why-wordpress/). I was caught off guard by how well it described my personal predicament.

## Why I chose a WordPress blog

When I read Avid's article, I realized that the reasons I, as a coder, had been avoiding WordPress were the very reasons I should embrace it:

1. As a coder, my tendency to jump into the internals and start toying around is strong. This hinders my writing ability. It competes for my time. Writing is something that I really want to do more of. By choosing a package that's tied up with a bow will encourage me to just use it instead of over-customize it. And since the innards of the package is a language that I don't want to devote a ton of my time to, I'm even less inclined to customize it.
2. PHP and WordPress are, in a way, like JavaScript -- they're everwhere, and everyone is using them. This means that probably just about everything that I could imagine wanting (ok, I'll probably come up with something innane) on a blog has already been built. I don't need to reinvent it.

## Driven to the edge

So, I made the jump. I just downloaded the latest [WordPress.org](http:://wordpress.org) package. I ran Apache on my local box and pointed my browser to `localhost:8888`. I was presented with the pleasant admin UI. I chose a new theme. It installed in place. It was a 2-click ordeal. I chose a few plugins to replace default functionality and add a bit more. I was pleasantly surprised by the smoothness of it all.

At the point I was getting the blog looking nice and doing what I wanted, did I care that the thing was written in PHP? No. I saw it just once when setting up my DB connection. I did cringe slightly upon seeing some [super globals](http://php.net/manual/en/language.variables.superglobals.php) again (`$_SERVER`), but I hastily committed the change and deployed the app.

We'll see if I continue to love it, but so far, so good. My fellow coders, I ask: Is my reasoning sound?