After trying desperately to find a Python-based static site generator I fell back on my friend Vincent’s excellent suggestion: Hugo. It was actually the first one I had looked into, and once I got thegist of it it was pretty simple.

Benefits include easy hosting on github, automatic push to netlifyand of course markdown edit and git everything.

Core principles

I’ve tried to work around some core features of hugo, and while the documentation is really good I had missed a few core points at the begining. Essentially, hugo is written in go but for all practical writing, markdown is where it’s at. The steps to get started are simple:

1. install hugo (brew install hugo on osx for example)

2. start a new site (hugo new site my-cool-site)

3. install a theme, and I suggest using the submodule command (git submodule add https://github.com/tomanistor/osprey.git themes/osprey in our case, from my-cool-site/

4. adapt the config.toml, possibly adding theme-specific parameters (‘Osprey’ by Toma Nistor takes logo locations as parameters,e.g.)

5. Start the server with hugo server -D so drafts are shown. From then on, open another shell to create content (and if you’re not vim-inclined, a markdown-capable editor). This part confused me at the first, but hugo server is meant for development not serving. It will watch, and render content on http://localhost:1313 (hence the opening a new shell)

6. create content, with hugo new new-page.md, and edit it.

7. once you’re happy with the new page, run hugo and a static build will show up in public/

8. There are a number of way to “push” this content to your hosting, but frankly the git+netlify is hard to beat. So effectively start a repo (private if you want), and set it as an upstream of your my-cool-site (you could init the repo before step #2)

9. Sign-up on netlify, follow the great documentation and you’re all set.

10. Each commit pushed will be rebuilt and reflected almost immediately.

Customization options are great, but since I have no knowledge of css I can’t really contribute much. However, shortcodes are cool, and instead of tweaking the theme repo (unless you want to do a pull request, of course), you can put a copy of a my-cool-site/themes/<theme name>/layout/partials/some_partial.html in my-cool-site/layouts/partials/. Hugo looks first for layouts and other at the website’s root, so you can change parameters here and overide default behavior.

Bonus

Vim is awesome, and with the Wordy and markdown plugins it offers a nice, distraction-free writing environment.