Getting started with Hugo

I am finally getting ready to set up my new personal website! Though a Drupal fan, I have decided to use Hugo static site generator for this project. Indeed, Hugo reminds me of the Good Ol’ Days of using the venerable WML (Website Meta Language) for website generation back in late 1990s, except that Hugo is modern and extremely speedy! It is orders of magnitude faster than anything out there, written in the cool new Go programming language.

So, henceforth begins my adventure of buildling websites with Hugo!


Note: the following content, originally written in September 2014, is still a draft and is subject to change.

Installing and Upgrading Hugo from source

Installation

See http://hugo.spf13.com/overview/installing. The stable version was v0.11 (now v0.12), but there has been some bug fixes since then, so I am compiling from source using git (go get).

mkdir
export GOPATH=$HOME/go                  # or something else
go get -v github.com/spf13/hugo

# After "go get", I actually find a compiled "hugo" binary inside $GOPATH/bin.
# So, no "go build" is necessary?

go build -v github.com/spf13/hugo

# For "go clean", the -i flag is somewhat dangerous:
# While it would remove the "*.a" found in my local $GOPATH/pkg/linux_amd64/ directory,
# which is what I wanted,
# it would also attempts to delete system-wide /usr/lib/go/pkg/linux_amd64/*/*.a, which is NOT
# what I wanted.  Thank goodness that I was not using sudo ...
#
go clean -i -r -v github.com/spf13/hugo

Upgrade

Supposedly, I could run:

go get -v -u github.com/spf13/hugo

But I have not fully confirmed that it indeeds work that way, and I don’t have time to investigate deeper today.

Generate a site skeleton!

Following the example at http://hugo.spf13.com/overview/quickstart:

$ hugo new site /work/web/anthonyfok.org
$ cd /work/web/anthonyfok.org
$ vim config.toml	# And fill it out the way we want.
			# TODO: What to do with m17n sites?

Troubleshooting: Why can’t I see anything HTML files being generated?

  1. Nothing gets generated when we haven’t installed any themes! So, make sure we follow “Step 4. Install some themes” in the official documentation.

  2. Make sure you have included the -D flag, as in:

    hugo -w -D -t redlounge
    

    or, with long form flags:

    hugo --watch --buildDrafts=true --theme redlounge
    

because new pages are “drafts” and not built by default.

Sidenote: We used to have 2 themes only, but now we have 12 in August 2014!

Things to add to official documentation

What dialect of Markdown?

Answer: Almost the same as GFM (GitHub Flavored Markdown), with the exception of Syntax highlighting in code blocks (since Linguist isn’t used?) with syntax highlighting provided by either server-side (Pygments) or client-side (JavaScript) solutions.

Deploying to a local Apache web server on Debian/Ubuntu

Add something like

127.0.2.1   local.anthonyfok.org

to /etc/hosts.

Then, create /etc/apache2/sites-available/local.anthonyfok.org.conf with the following content:

<VirtualHost local.anthonyfok.org:80>

        DocumentRoot /srv/local.anthonyfok.org

        <Directory /srv/local.anthonyfok.org/>
                Options +FollowSymLinks
                AllowOverride All
                # order allow,deny
                # allow from all
                Require all granted
        </Directory>

</VirtualHost>

Note that “Required all granted” is needed for Apache 2.4 and up; otherwise, we would be greeted with a mysterious 403 Forbidden error. Apache 2.2 used “Order allow, deny” and “Allow from all”.

Then, run:

$ sudo a2ensite local.anthonyfok.org.conf
$ sudo service apache2 reload

Generate some test content:

$ sudo mkdir /srv/local.anthonyfok.org
$ sudo chown foka:foka /srv/local.anthonyfok.org
$ echo Hello > /srv/local.anthonyfok.org/index.html

And we should be able to see something when we access http://local.anthonyfok.org/.

$ cd /work/web/anthonyfok.org
$ hugo && cp -a public/* /srv/localhost.anthonyfok.org/

FAQ (or: Questions that I want answers for)

  1. Tutorial for newbies, especially those like me who haven’t worked with Jekyll before.

  2. How much is our website structure and content tied to a theme?

    1. For example, “fixed” vs “pages”; “posts” vs “blog”
    2. Adding items to “menu” done in the same way?
  3. How to make a multilingual website?

    A: There is an example in hugo/examples/multilingual

  4. Can we call external programs to generate some data? For example, to convert traditional Chinese to simplified Chinese.

    A: Perhaps something like https://github.com/stevenyao/go-opencc or https://github.com/BYVoid/OpenCC ? (Or cconv?)

  5. What is theme.toml for? Is it read during a site-generation run?

  6. What existing, ready-to-use themes are available for Hugo? What are their differences? (maybe not so much a question, but wish to add a “Theme Listings” in the docs.

  7. Say, I decide to base my website on an existing theme, but want to customize it. What is the recommended way to do so? Should I:

    1. “Fork it”, e.g. cp -avi themes/hyde themes/my-hyde (or use git branch)
    2. “Override it” by adding local files, e.g. mysite/layouts/index.html, to override whatever is in mysite/themes/my-favorite-theme/layouts/index.html? (Does it actually do that?)
      • Answer: Yes, it does! Since Hugo v0.12, the new partial call does this magically.