Here’s how I setup my blog with Hugo, I hope that some of these tips may be helpful to you.

Setup git on your remote server⌗

1
2
3
4


SITE=your.web.site
mkdir -p git/$SITE
cd git/$SITE
git init

Setup a hook to generate your website:⌗

Please note that SITE in this section really is the variable $SITE and not the value setup above.

Continue in the same directory:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


ln -s ~/bin/hugo-post-receive-hook hooks/post-receive
cat <<EOF > ~/bin/hugo-post-receive-hook
#!/bin/sh

unset GIT_DIR

SITE=\$( basename $PWD )

cd "/var/www/html/\$SITE" && git pull && /usr/local/bin/hugo -D --cleanDestinationDir
EOF
chmod a+rx ~/bin/hugo-post-receive-hook

Create your website’s directory⌗

Your website’s document root will be tracking your git repository and automatically updated by the hook above, but in order for a web server to serve it, it needs to be there.

1
2
3
4



SITE=your.web.site
cd /var/www/html
git clone ~/git/$SITE $SITE

Setup the web server⌗

For my example, I’ll be using Apache httpd. In short, the configuration below…

redirects http to https (and provides a path for Let’s Encrypt certificate renewal)
points to the public directory were he pages are generated
setups a 404 page pointing to Hugo’s 404 page; as I migrated from another blog engine, I wanted to keep some link compatibility so I’m using server side includes to auto generate the link, but only on 404.html.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


<VirtualHost *:80>
        ServerName your.web.site
        ServerAdmin rms@1407.org

        AddDefaultCharset UTF-8

        TransferLog logs/http-your.web.site-access_log
        ErrorLog logs/http-your.web.site-error_log

        RewriteEngine On
        RewriteRule ^/(.*) https://your.web.site/$1 [R=301,L]

        Alias /.well-known/acme-challenge /var/www/html/letsencrypt/.well-known/acme-challenge
</VirtualHost>

<VirtualHost *:443>
        ServerName your.web.site
        ServerAdmin your@e.mail

        AddDefaultCharset UTF-8

        TransferLog logs/https-your.web.site-access_log
        ErrorLog logs/https-your.web.site-error_log

        SSLEngine On
        SSLCertificateFile /.../your.web.site.crt
        SSLCertificateKeyFile /.../your.web.site.key
        SSLCertificateChainFile /...

        DocumentRoot /var/www/html/your.web.site/public

	# Automatically redirect to old blog if missing page has an equivalent in the old site
        RewriteEngine on
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond /var/www/html/old.web.site/%{REQUEST_FILENAME} -f [OR]
        RewriteCond /var/www/html/old.web.site/%{REQUEST_FILENAME} -d
        RewriteRule - https://old.web.site/%{REQUEST_FILENAME}

	# This part is very important, it's magic! Remember to activate mod_includes!
        <Directory "/var/www/html/your.web.site/public">
                Options +Includes
                <FilesMatch 404.html>
                        SetHandler server-parsed
                </FilesMatch>
                ErrorDocument 404 /404.html
        </Directory>

Quick Start Hugo…⌗

Now you’re ready for the first steps of the Hugo instructions, from the [Quick Start][https://gohugo.io/getting-started/quick-start/]…

Step 1: Install Hugo⌗

This step may widely vary on how you install Hugo, so it is out of scope for this entry.

Do this both on your server and on your own computer.

Step 2: Create a New Site⌗

Wait, what about Git? Let’s not forget about it…

First, clone your repository, then initialize your Hugo website and commit the newly generated files.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


git clone you@your.server:git/your.web.site your.web.site
hugo new site your.web.site
cd your.web.site
cat <<EOF > .gitignore
public
.hugo_build.lock
resources
EOF
git add .
git commit -a -m "First files of my brand new Hugo web site"

Step 3: Add a Theme⌗

At this point you should only add the git submodule of your theme, also I preferred to use the configuration in yaml format rather than toml, but it’s your taste, do as you wish. :)

You’ll need to commit your changes to your server’s git:

1
2


git commit -a -m "I've chosen my theme"
git push

And now you need to go back to your server and change into your.web.site’s document root directory in order to pull the changes and initialize the theme’s submodule:

1
2
3


cd /var/www/html/your.web.site
git pull
git submodule init

Step 5: Start the Hugo server⌗

You can skip this step if you don’t care much for drafts, and you already have your own web server, don’t you? :)

Step 6: Customize the Theme⌗

On your computer, edit your.web.site’s configuration file (config.yml or config.toml) and adjust the values accordingly.

One configuration you may do just now is to take advantage of that 404.html magic mentioned above, remember that?

Create a layouts/404.html with the following content (please, adjust to suit your fancy):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{{ define "main"}}
    <main id="main">
      <div>
       <h1 id="title">Content may have moved elsewhere...</h1>
       <p>I used to have <a href="https://your.old.web.site/">another blog</a>
       so the page you were looking for
       <a href="https://your.old.web.site<!--#echo var='REQUEST_URI' -->">may
       still reside in this link</a>.
       <h1 id="subtitle"><a href="{{ "" | relURL }}">Go Home</a></h1>
      </div>
    </main>
{{ end }}

Remember to git add, commit, and push so your changes get published by the git hook, which will take care of running hugo -D for you.

And now enjoy the beginning of your publishing with Hugo.

Tips for Hugo Websites