Tag: golang

Porting Jekyll to Hugo
Importing content is always the bane of moving systems.

Now one of the things Hugo has is a cool command called $ hugo import jekyll – and yes, it does exactly what you think it does. This was interesting to me since I wondered if I could switch my library from Jekyll to Hugo and yes, yes I can.

The site I have on Jekyll has a few more posts than the first one I built on Hugo. This one has around 1500 pages. Excited, I ran the command:
```
Importing...
Congratulations! 0 posts imported!
```
That’s not right. I spent a few hours trying to run it in various permutations, but I was never able to get it to run right. Thankfully, I didn’t need to since I could just copy my content over. There was no translation needed, as I was already using yaml headers in my .md files so that actually was a pretty painless transition.

The theme on the other hand… Well. I had a complex site with data files and weird junk being thrown around. That was just learning how to translate for-loops for ranges, with some where clauses tossed in.

Was it hard? Yes. But that’s not what you’re really asking.

Was it worth it?

Excuse me while I whip this out:
```
Change detected, rebuilding site
2015-12-11 21:42 -0800
0 draft content
0 future content
1479 pages created
0 paginator pages created
16 categories created
66 tags created
in 4611 ms
```
Yes. The site builds faster, which is a win. It also creates tags and categories that can automatically cross link. I can make ‘sections’ without having to define them in my config file, just by making folders. I can spin up templates quickly. I have a little more redundancy than I’d like, but as I master GoLang, this becomes less and less.

Build time ranges from 11737 ms to 2116 ms. Milliseconds. They were into the minutes with Jekyll, even though Jekyll 3 was notably faster than version 2. It was still taking me about 2 minutes to rebuild the Jekyll site, even with incremental builds working. Plus I had to build and rsync every time, in addition to Git pushing. Now I just Git and done.

Oh and JSON works remotely out of the box. I just have to get better at my range calls now.

What’s Different?

Making a ‘static front page’ with Hugo is harder. In fact there’s still an open trac ticket on it. I was able to use an idea I already had, a custom post param called “type” for tagging ‘index’ posts in the news pages so I didn’t get a list of my indexes when I wanted to list all news from 2002. I leveraged that and tagged my primary index ‘mainindex’ and put a quick check in my index.html in my theme:
```
{{ range .Data.Pages }}
    {{if eq .Type "mainindex" }} 
        {{ partial "content.html" . }}
    {{end}}
{{ end }}
```
Instead of doing a normal loop where, like a blog it shows me posts in reverse order, it just showed that specific content.

But…

If there’s a file in that Section with the type of ‘Index’ then it shows that. Of course… While index.md doesn’t get used in the main content folder, it does in Sections. If I have a file named index.md in a section, that makes index.html like I expected. Since I still wanted lists in the majority of cases, I tweaked the content of my default list file (list.html) so that I could always show a ‘main’ file:
```
    {{ range .Data.Pages.ByTitle }}
        {{ if eq .Type "index" }}
            {{ .Content }}
        {{ end }}
    {{ end }}

    <ul>
    {{ range .Data.Pages.ByTitle }}
        {{ if ne .Type "index" }}
            <li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
        {{ end }}
    {{ end }}
    </ul>
```
Then I renamed all the index.md files in the Sections to main.md but this created another issue. Now I had two URLs that worked. I could have put this into the template for the section to avoid this, but I want to separate content and theme as much as humanly possible. WordPress habits. For now, I’ve left this alone. If someone is clever enough to go to a non-linked, non-sitemaped page instead of the index, I think my SEO will live. It’s more than I wanted to play around with loops.

Speaking of the loops and lists, getting a list of a ‘sub section’ is not currently possible either. Rather, they do work, but there’s no default templates for sub-sections. This was a small problem since I structured my site like this:
```
.
└── content
    ├── news
    |   ├── index.md          // /news/
    |   ├── 2001
    |   |   ├── loch-ness.md  // /news/2001/loch-ness/
    |   |   └── monster.md    // /news/2001/monster/
    |   └── 2002
    |       ├── nessie.md     // /news/2002/nessie/
    |       └── spock.md      // /news/2002/spock/
    └── posts
```
Now, I don’t need a custom template for each sub-section, but I did want to use my custom list template for each sub-section. To work around this, I made a template in /layout/section/news.html that had this:
```
	{{ range .Data.Pages.ByTitle }}
		{{ if and (eq .Type "index") (ne .Params.topic "index") }}
			{{ .Content }}
		{{ end }}
	{{ end }}
```
I know this is weird. The Type of index means “I am the main index file of the section” while the topic index means “I am an indexing file and not a normal news article. This gives me my main index of /news/ giving me a custom content page with information like I wanted, using the main.md format I use in all sections.

Then in each sub-section, I use a very simple index.md file:
```
---
title: News Articles (1992)
author: Mika Epstein
layout: news
topic: index
date: 1992-01-01
permalink: /news/1992/
categories: ["News"]
tags: ["1992"]
---

{{< news >}}
```
That weird bit in the content is a shortcode ala Hugo, which calls the file /layouts/shortcode/news.html that has this:
```
{{ $date := $.Page.Date.Format "2006" }}

<table class="infobox">

    <thead><tr>
        <th>Date</th>
        <th>Source</th>
    </tr></thead>

    <tbody>
    {{ range where $.Page.Site.Pages.ByDate "Section" "news" }}
        {{ $thisdate := .Date.Format "2006" }}

        {{ if and (eq $date $thisdate) (ne .Params.topic "index") }}

            <tr>
                <td>{{ .Date.Format "01 January" }}</td>
                <td><a href="{{ .Permalink }}">{{ .Title }}</a></td>
            </tr>

        {{ end }}
    {{ end }}
    </tbody>
</table>
```
That spits out a table of all the pages in that section by date.

What’s Next?

It took a lot to get here, or so it may seem. This took me two nights to work out. That’s it. So now I have to figure out the next steps that have vexed me:
1. How do I properly mimic a for-loop with range?
2. Can I make a responsive gallery out of Hugo?
3. Can I power a Hugo site with WordPress JSON?
And that’s a whole ‘nother story.
28 December, 2015
Hugo
I’ve been playing with Jekyll a lot. After WordCamp US, I started toying with the idea of a JSON powered Jekyll site, where WordPress output its posts as JSON and Jekyll pulled in the posts and converted them. This ran into many snags. It wouldn’t be ‘dynamic’ for one, but the biggest issue is that Jekyll’s JSON reading ability was terrible. It didn’t like the complex JSON that WordPress put out.

That sent me hunting down other things like Hugo. Unlike Jekyll and it’s use of Liquid, Hugo uses Go (hence the Go in the name you see).

Installation (on a Mac) is easy.

brew install hugo

Done. It’s harder on my server, but still easier than Jekyll, which started to become a ‘thing’ as I worked through all this.

Using Hugo is remarkably similar to Jekyll except that it works faster and a little more smoothly. The site builds incredibly fast and it dynamically refreshes. So if I edit a post, the page refreshes itself. This let me tweak my theme and posts and sort out the new language incredibly fast. Edit a file, boom, I see what’s wrong.

It’s about as logical as Jekyll too, so it took me one DayQuil addled afternoon to sort out how to make things work.

The Basics

The basic are simple. You have a basic structure like this:
```
▸ archetypes/ 
▸ content/
▸ data/
▸ layouts/
▸ static/
▸ themes/
config.toml
```
The config file is what you think it is. Your posts go in content and the html-ized version shows up a public folder that gets created on the fly. The data folder is for your static data like a .json file or a .yaml.

Independant to your theme, you can put css and js in the static folder, and layouts in the layout folder. Ditto archetypes, which are post-types. So if you know you’re always going to have a post type of ‘musician’ and you want it to have special headers, then you can have an archetype called musician.md with all that pre-filled in. Then when you want to make a new entry for Clifford:

$ hugo new musician/clifford.md

You can also have those in your theme if you wanted, but generally I use the same theme and separate projects. At this point, I was impressed enough to be swayed from Jekyll. I’m not going to explain how to write a post, since it’s just markdown and a header, just like Jekyll or GitHub Pages.

Building Your Site

The commands are basic. Running $ hugo server will build your demo server. Of course, you’ll want to post your drafts, so you need to add the param --buildDrafts … Oh and you want a theme …

$ hugo server --theme=utility-pro --buildDrafts

That’s silly, right? Why do I have to define all that? Thankfully I can edit my config.toml file:
```
baseurl = "http://example.com/videos"
languageCode = "en-us"
title = "My Super cool Video Library"
theme = "utility-pro"
buildDrafts = "true"
[params]
Subtitle = "Videos about cats, collected from the internet."
```
Now every time I run the command ‘hugo’ it will build my drafts with my theme!
```
$ hugo
45 of 45 drafts rendered
0 future content
45 pages created
42 paginator pages created
14 tags created
3 categories created
in 254 ms
```
That’s incredible fast seeing as it built everything. Of course the other site I have is a great many more pages.

Theming

Since I’d already mastered Jekyll theming, this was trivial. Go and Liquid are weirdly similar and most of it was transposing. There’s not much to say here except that there’s a Twenty Fourteen Theme for Hugo and it’s pretty much what you expect. For WordPressers, it’s a good place to start.

Shortcodes

The neat thing is that Hugo has shortcodes! They’re not like WordPress ones, but you can see the similarity between WordPress and Hugo.
```
[video mp4="video.mp4" flv="video.flv"]
```
vs.
```
{{< video mp4="video.mp4" flv="video.flv" >}}
```
Sadly there’s no oEmbed. And I had to write the shortcode on my own, but again, if you know the basics of logic all this stuff is easy. Here’s the magic behind the shortcode:
```
<video class="video-js" width="{{ if .Get "width" }}{{ .Get "width" }}{{ else }}640{{ end }}" height="{{ if .Get "height" }}{{ .Get "height" }}{{ else }}385{{ end }}" controls>

	{{ if .Get "mp4"  }}<source src="{{ .Get "mp4" }}" type="video/mp4">{{ end }}
	{{ if .Get "ogg"  }}<source src="{{ .Get "ogg" }}" type="video/ogg">{{ end }}
	{{ if .Get "webm" }}<source src="{{ .Get "webm" }}" type="video/webm">{{ end }}

Your browser does not support the video tag.
</video>
```
Once you look at it, it’s remarkably like WordPress. Only I don’t need a plugin. Everything in /layouts/shortcodes/ are like mu-plugins.

And So?

And so Hugo won enough of my attention that I’m going to keep playing with it and see what’s next.
14 December, 2015

Tag: golang

Porting Jekyll to Hugo

Was it worth it?

What’s Different?

What’s Next?

Hugo

The Basics

Building Your Site

Theming

Shortcodes

And So?