Hugo - freeCodeCamp.org

From WordPress to Hugo – How I Migrated a 250+ Page Site and the Scripts I Used

Lane Wagner — Tue, 30 Aug 2022 23:25:47 +0000

I recently decided to switch Boot.dev's blog from WordPress to a static site generator.

I decided on Hugo, partly because I’m a huge fan of the Go programming language, but also because it just seemed like the best option from a dev-experience perspective.

Here’s why I decided to move away from WordPress:

I wanted to write and store all my posts in Markdown.
I wanted to version control all my posts in Git/Github.
I wanted to be able to use ctrl+shift+f to find and edit the content on my blog.
I wanted a less buggy way to do “global blocks”
I didn’t want to spend hours fine-tuning performance. My posts are just text and images, so page speed scores should be 100 by default!
I wanted to use straight CSS for styling, making it easier for my blog and app to have identical styling.
I wanted to host the site for free

With all those goals in mind, Hugo was a perfect choice. I’ve been super happy since making the switch, but there were some hiccups along the way.

WordPress takes care of some of the nuances of SEO-tuning for you, and if you forget to redo them yourself, you’ll end up sacrificing rankings.

How to Export WordPress Posts as Markdown

Manually copying and pasting all of your posts out of the WordPress GUI into Markdown files could take a very long time. Especially if you have hundreds of posts like I do.

In order to speed up the process, I used this Markdown plugin to export all of my posts as markdown at once. It’s called “Gatsby Markdown Exporter”, but it works for Hugo just as well.

I’m not going to go over the basics of getting up and running with Hugo, as I’m going to assume you are already familiar with it. But if you’re not, you can read the quick start guide here.

How to Use Hugo’s Built-in SEO Templates

WordPress and its various SEO plugins take care of a lot of SEO-related hocus-pocus for you. So when you move to a static site generator you often have to do some of that stuff yourself.

As it turns out, Hugo has some turn-key solutions for most of this, so using the right internal templates can get you all the open-graph, schema, and Twitter meta tags out of the box.

For me, that meant simply adding these 3 lines to my layouts/partials/header.html file within the tag:

{{ template "_internal/opengraph.html" . }}
{{ template "_internal/twitter_cards.html" . }}
{{ template "_internal/schema.html" . }}

Now we'll get into the scripts I wrote to help me with this process.

Script 1 — Checking for Broken Links

You can solve a lot of your WordPress woes by installing plugins for various tasks. Well, assuming those plugins don’t break your entire WP installation.

With Hugo, I just write little text-manipulation or HTTP scripts to do my bidding.

This first script is just a simple iterator that crawls the site and reports any broken links. You can see the full source code here. It's small edit of the script the Go team uses to check for broken links on the Go programming language's website.

Script 2 — Minifying Images

When working with WordPress, you would typically upload a blog post image, and some SEO plugin would optimize that image’s size for you.

In Hugo, no such optimizations are made for you. It simply serves the exact image you add to your “static” folder.

I wrote a little script to optimize my images. It does the following:

Takes an input image of nearly any type (.png, .jpeg, .gif, etc).
Converts it to the .webp format (a performant format).
Shrinks the image to a max image size I've configured if it’s too large.

This script is written in Node.js and the source code can be found here.

Script 3 — Managing Global Shortcodes

WordPress had a feature called “global blocks”. They're super useful for things like newsletter signup boxes that show up in the middle of your articles, but that you want to be able to update in a single place.

In Hugo, you can use shortcodes to achieve a similar purpose.

Unfortunately, it’s the inserting and removing of the shortcodes themselves that actually becomes tedious at scale.

For example, let’s say I added my newsletter signup shortcode after the 5th paragraph in all my articles, but now I want it to come after the 7th paragraph. I have to go manually copy/paste the short code!

Well, not anymore. Again, this is the great thing about storing all your blog posts in a text format — we can script some simple solutions. I wrote two scripts, and their source code can be found here:

These two scripts allow me move my global blocks with ease. For example, to remove all instances of myshortcode from the blog:

rmshorts myshortcode

Then to add myshortcode as its own paragraph after the 2nd section of every blog post across the site:

addshorts myshortcode 2

This has been a huge time saver.

Script 4 — Converting .docx to Markdown

Last but not least, I work with some non-technical writers. My writers aren’t used to writing Markdown. Google docs is their tool of choice.

I have no problem with that, as I want them to be effective. My solution was to write a little bash script that uses pandoc under the hood to convert the Google Docs to Markdown files.

Wrapping Up

I hope some of these scripts are valuable to you, and I really can’t recommend enough making the switch to a static site generator. If you’re willing to put in a few hours to get a great working environment up and running for your blog it will save you a lot of time and money in the long run.

Remember, always automate the boring stuff!

Hugo vs Jekyll: an Epic Battle of Static Site Generator Themes

Victoria Drake — Mon, 27 Apr 2020 13:42:00 +0000

In this article, we'll compare the nuances of creating themes for the top two static site generators.

I recently took on the task of creating a documentation site theme for two projects. Both projects needed the same basic features, but one uses Jekyll while the other uses Hugo.

In typical developer rationality, there was clearly only one option. I decided to create the same theme in both frameworks, and to give you, dear reader, a side-by-side comparison.

This post isn’t a comprehensive theme-building guide, but is rather intended to familiarize you with the process of building a theme in either generator. Here's what we'll cover:

How theme files are organized
Where to put content
How templating works
Creating a top-level menu with the pages object
Creating a menu with nested links from a data list
Putting the template together
Creating styles
How to configure and deploy to GitHub Pages

Here’s a crappy wireframe of the theme I’m going to create.

If you’re planning to build-along, it may be helpful to serve the theme locally as you build it – and both generators offer this functionality. For Jekyll, run jekyll serve, and for Hugo, hugo serve.

There are two main elements: the main content area, and the all-important sidebar menu. To create them, you’ll need template files that tell the site generator how to generate the HTML page. To organize theme template files in a sensible way, you first need to know what directory structure the site generator expects.

How theme files are organized

Jekyll supports gem-based themes, which users can install like any other Ruby gems. This method hides theme files in the gem, so for the purposes of this comparison, we aren’t using gem-based themes.

When you run jekyll new-theme , Jekyll will scaffold a new theme for you. Here’s what those files look like:

.
├── assets
├── Gemfile
├── _includes
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
└── .gemspec

The directory names are appropriately descriptive. The _includes directory is for small bits of code that you reuse in different places, in much the same way you’d put butter on everything. (Just me?)

The _layouts directory contains templates for different types of pages on your site. The _sass folder is for Sass files used to build your site’s stylesheet.

You can scaffold a new Hugo theme by running hugo new theme . It has these files:

.
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── header.html
│       └── head.html
├── LICENSE
├── static
│   ├── css
│   └── js
└── theme.toml

You can see some similarities. Hugo’s page template files are tucked into layouts/. Note that the _default page type has files for a list.html and a single.html.

Unlike Jekyll, Hugo uses these specific file names to distinguish between list pages (like a page with links to all your blog posts on it) and single pages (like one of your blog posts). The layouts/partials/ directory contains the buttery reusable bits, and stylesheet files have a spot picked out in static/css/.

These directory structures aren’t set in stone, as both site generators allow some measure of customization. For example, Jekyll lets you define collections, and Hugo makes use of page bundles. These features let you organize your content multiple ways, but for now, let's look at where to put some simple pages.

Where to put content

To create a site menu that looks like this:

Introduction
    Getting Started
    Configuration
    Deploying
Advanced Usage
    All Configuration Settings
    Customizing
    Help and Support

You’ll need two sections (“Introduction” and “Advanced Usage”) containing their respective subsections.

Jekyll isn’t strict with its content location. It expects pages in the root of your site, and will build whatever’s there. Here’s how you might organize these pages in your Jekyll site root:

.
├── 404.html
├── assets
├── Gemfile
├── _includes
├── index.markdown
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── index.md
│   └── quickstart.md
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
├── .gemspec
└── usage
    ├── customizing.md
    ├── index.md
    ├── settings.md
    └── support.md

You can change the location of the site source in your Jekyll configuration.

In Hugo, all rendered content is expected in the content/ folder. This prevents Hugo from trying to render pages you don’t want, such as 404.html, as site content. Here’s how you might organize your content/ directory in Hugo:

.
├── _index.md
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── _index.md
│   └── quickstart.md
└── usage
    ├── customizing.md
    ├── _index.md
    ├── settings.md
    └── support.md

To Hugo, _index.md and index.md mean different things. It can be helpful to know what kind of Page Bundle you want for each section: Leaf, which has no children, or Branch.

Now that you have some idea of where to put things, let’s look at how to build a page template.

How templating works

Jekyll page templates are built with the Liquid templating language. It uses braces to output variable content to a page, such as the page’s title: {{ page.title }}.

Hugo’s templates also use braces, but they’re built with Go Templates. The syntax is similar, but different: {{ .Title }}.

Both Liquid and Go Templates can handle logic. Liquid uses tags syntax to denote logic operations:

{% if user %}
  Hello {{ user.name }}!
{% endif %}

And Go Templates places its functions and arguments in its braces syntax:

{{ if .User }}
    Hello {{ .User }}!
{{ end }}

Templating languages allow you to build one skeleton HTML page, then tell the site generator to put variable content in areas you define. Let’s compare two possible default page templates for Jekyll and Hugo.

Jekyll’s scaffold default theme is bare, so we’ll look at their starter theme Minima. Here’s _layouts/default.html in Jekyll (Liquid):

html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">

  {%- include head.html -%}

  <body>

    {%- include header.html -%}

    <main class="page-content" aria-label="Content">
      <div class="wrapper">
        {{ content }}
      div>
    main>

    {%- include footer.html -%}

  body>

html>

Here’s Hugo’s scaffold theme layouts/_default/baseof.html (Go Templates):

html>
<html>
    {{- partial "head.html" . -}}
    <body>
        {{- partial "header.html" . -}}
        <div id="content">
        {{- block "main" . }}{{- end }}
        div>
        {{- partial "footer.html" . -}}
    body>
html>

Different syntax, same idea. Both templates pull in reusable bits for head.html, header.html, and footer.html. These show up on a lot of pages, so it makes sense not to have to repeat yourself.

Both templates also have a spot for the main content, though the Jekyll template uses a variable ({{ content }}) while Hugo uses a block ({{- block "main" . }}{{- end }}). Blocks are just another way Hugo lets you define reusable bits.

Now that you know how templating works, you can build the sidebar menu for the theme.

Creating a top-level menu with the `pages` object

You can programmatically create a top-level menu from your pages. It will look like this:

Introduction
Advanced Usage

Let’s start with Jekyll. You can display links to site pages in your Liquid template by iterating through the site.pages object that Jekyll provides and building a list:

<ul>
    {% for page in site.pages %}
    <li><a href="{{ page.url | absolute_url }}">{{ page.title }}a>li>
    {% endfor %}
ul>

This returns all of the site’s pages, including all the ones that you might not want, like 404.html. You can filter for the pages you actually want with a couple more tags, such as conditionally including pages if they have a section: true parameter set:

<ul>
    {% for page in site.pages %}
    {%- if page.section -%}
    <li><a href="{{ page.url | absolute_url }}">{{ page.title }}a>li>
    {%- endif -%}
    {% endfor %}
ul>

You can achieve the same effect with slightly less code in Hugo. Loop through Hugo’s .Pages object using Go Template’s range action:

<ul>
{{ range .Pages }}
    <li>
        <a href="{{.Permalink}}">{{.Title}}a>
    li>
{{ end }}
ul>

This template uses the .Pages object to return all the top-level pages in content/ of your Hugo site. Since Hugo uses a specific folder for the site content you want rendered, there’s no additional filtering necessary to build a simple menu of site pages.

Both site generators can use a separately defined data list of links to render a menu in your template. This is more suitable for creating nested links, like this:

Introduction
    Getting Started
    Configuration
    Deploying
Advanced Usage
    All Configuration Settings
    Customizing
    Help and Support

Jekyll supports data files in a few formats, including YAML. Here’s the definition for the menu above in _data/menu.yml:

section:
  - page: Introduction
    url: /intro
    subsection:
      - page: Getting Started
        url: /intro/quickstart
      - page: Configuration
        url: /intro/config
      - page: Deploying
        url: /intro/deploy
  - page: Advanced Usage
    url: /usage
    subsection:
      - page: Customizing
        url: /usage/customizing
      - page: All Configuration Settings
        url: /usage/settings
      - page: Help and Support
        url: /usage/support

Here’s how to render the data in the sidebar template:

{% for a in site.data.menu.section %}
<a href="{{ a.url }}">{{ a.page }}a>
<ul>
    {% for b in a.subsection %}
    <li><a href="{{ b.url }}">{{ b.page }}a>li>
    {% endfor %}
ul>
{% endfor %}

This method allows you to build a custom menu, two nesting levels deep. The nesting levels are limited by the for loops in the template. For a recursive version that handles further levels of nesting, see Nested tree navigation with recursion.

Hugo does something similar with its menu templates. You can define menu links in your Hugo site config, and even add useful properties that Hugo understands, like weighting. Here’s a definition of the menu above in config.yaml:

sectionPagesMenu: main

menu:  
  main:
    - identifier: intro
      name: Introduction
      url: /intro/
      weight: 1
    - name: Getting Started
      parent: intro
      url: /intro/quickstart/
      weight: 1
    - name: Configuration
      parent: intro
      url: /intro/config/
      weight: 2
    - name: Deploying
      parent: intro
      url: /intro/deploy/
      weight: 3
    - identifier: usage
      name: Advanced Usage
      url: /usage/
    - name: Customizing
      parent: usage
      url: /usage/customizing/
      weight: 2
    - name: All Configuration Settings
      parent: usage
      url: /usage/settings/
      weight: 1
    - name: Help and Support
      parent: usage
      url: /usage/support/
      weight: 3

Hugo uses the identifier, which must match the section name, along with the parent variable to handle nesting. Here’s how to render the menu in the sidebar template:

<ul>
    {{ range .Site.Menus.main }}
    {{ if .HasChildren }}
    <li>
        <a href="{{ .URL }}">{{ .Name }}a>
    li>
    <ul class="sub-menu">
        {{ range .Children }}
        <li>
            <a href="{{ .URL }}">{{ .Name }}a>
        li>
        {{ end }}
    ul>
    {{ else }}
    <li>
        <a href="{{ .URL }}">{{ .Name }}a>
    li>
    {{ end }}
    {{ end }}
ul>

The range function iterates over the menu data, and Hugo’s .Children variable handles nested pages for you.

Putting the template together

With your menu in your reusable sidebar bit (_includes/sidebar.html for Jekyll and partials/sidebar.html for Hugo), you can add it to the default.html template.

In Jekyll:

html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">

{%- include head.html -%}

<body>
    {%- include sidebar.html -%}

    {%- include header.html -%}

    <div id="content" class="page-content" aria-label="Content">
        {{ content }}
    div>

    {%- include footer.html -%}

body>

html>

In Hugo:

html>
<html>
{{- partial "head.html" . -}}

<body>
    {{- partial "sidebar.html" . -}}

    {{- partial "header.html" . -}}
    <div id="content" class="page-content" aria-label="Content">
        {{- block "main" . }}{{- end }}
    div>
    {{- partial "footer.html" . -}}
body>

html>

When the site is generated, each page will contain all the code from your sidebar.html.

Create a stylesheet

Both site generators accept Sass for creating CSS stylesheets. Jekyll has Sass processing built in, and Hugo uses Hugo Pipes. Both options have some quirks.

Sass and CSS in Jekyll

To process a Sass file in Jekyll, create your style definitions in the _sass directory. For example, in a file at _sass/style-definitions.scss:

$background-color: #eef !default;
$text-color: #111 !default;

body {
  background-color: $background-color;
  color: $text-color;
}

Jekyll won’t generate this file directly, as it only processes files with front matter. To create the end-result filepath for your site’s stylesheet, use a placeholder with empty front matter where you want the .css file to appear. For example, assets/css/style.scss. In this file, simply import your styles:

---
---

@import "style-definitions";

This rather hackish configuration has an upside: you can use Liquid template tags and variables in your placeholder file. This is a nice way to allow users to set variables from the site _config.yml, for example.

The resulting CSS stylesheet in your generated site has the path /assets/css/style.css. You can link to it in your site’s head.html using:

<link rel="stylesheet" href="{{ "/assets/css/style.css" | relative_url }}" media="screen">

Sass and Hugo Pipes in Hugo

Hugo uses Hugo Pipes to process Sass to CSS. You can achieve this by using Hugo’s asset processing function, resources.ToCSS, which expects a source in the assets/ directory. It takes the SCSS file as an argument.

With your style definitions in a Sass file at assets/sass/style.scss, here’s how to get, process, and link your Sass in your theme’s head.html:

{{ $style := resources.Get "/sass/style.scss" | resources.ToCSS }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}" media="screen">

Hugo asset processing requires extended Hugo, which you may not have by default. You can get extended Hugo from the releases page.

Configure and deploy to GitHub Pages

Before your site generator can build your site, it needs a configuration file to set some necessary parameters. Configuration files live in the site root directory. Among other settings, you can declare the name of the theme to use when building the site.

Configure Jekyll

Here’s a minimal _config.yml for Jekyll:

title: Your awesome title
description: >- # this means to ignore newlines until "baseurl:"
  Write an awesome description for your new site here. You can edit this
  line in _config.yml. It will appear in your document head meta (for
  Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
theme: # for gem-based themes
remote_theme: # for themes hosted on GitHub, when used with GitHub Pages

With remote_theme, any Jekyll theme hosted on GitHub can be used with sites hosted on GitHub Pages.

Jekyll has a default configuration, so any parameters added to your configuration file will override the defaults. Here are additional configuration settings.

Configure Hugo

Here’s a minimal example of Hugo’s config.yml:

baseURL: https://example.com/ # The full domain your site will live at
languageCode: en-us
title: Hugo Docs Site
theme: # theme name

Hugo makes no assumptions, so if a necessary parameter is missing, you’ll see a warning when building or serving your site. Here are all configuration settings for Hugo.

Deploy to GitHub Pages

Both generators build your site with a command.

For Jekyll, use jekyll build. See further build options here.

For Hugo, use hugo. You can run hugo help or see further build options here.

You’ll have to choose the source for your GitHub Pages site. Once done, your site will update each time you push a new build. Of course, you can also automate your GitHub Pages build using GitHub Actions. Here’s one for building and deploying with Hugo, and one for building and deploying Jekyll.

Showtime!

All the substantial differences between these two generators are under the hood. All the same, let’s take a look at the finished themes, in two color variations.

Here’s Hugo:

Here's Jekyll:

Wait who won?

Both Hugo and Jekyll have their quirks and conveniences.

From this developer’s perspective, Jekyll is a workable choice for simple sites without complicated organizational needs. If you’re looking to render some one-page posts in an available theme and host with GitHub Pages, Jekyll will get you up and running fairly quickly.

Personally, I use Hugo. I like the organizational capabilities of its Page Bundles, and it’s backed by a dedicated and conscientious team that really seems to strive to facilitate convenience for their users. This is evident in Hugo’s many functions, and handy tricks like Image Processing and Shortcodes. They seem to release new fixes and versions about as often as I make a new cup of coffee - which, depending on your use case, may be fantastic, or annoying.

If you still can’t decide, don’t worry. The OpenGitDocs documentation theme I created is available for both Hugo and Jekyll. Start with one, switch later if you want. That’s the benefit of having options.

How to self-host a Hugo web app

freeCodeCamp — Sun, 29 Mar 2020 18:10:07 +0000

By Jared Wolff

After hosting with Netlify for a few years, I decided to head back to self hosting. There are a few reasons for that, but the main reasoning was that I had more control over how things worked.

In this post, I'll show you my workflow for deploying my Hugo generated site (www.jaredwolff.com).

Instead of using what most people would go for, I'll be doing all of this using a FreeBSD Jails-based server. Plus I'll show you some tricks I've learned over the years on bulk image resizing and more.

Let's get to it.

Where to host?

If you want to host your own service, you'll need a server. That's where a VPS provider like Digital Ocean or Vultr comes in. I've been a fan and have used Digital Ocean for a while now.

To set up a new server here are some steps:

Login to Digital Ocean. If you don’t have Digital Ocean and would like to support this blog click here to create an account.
Go to Account Settings -> Security and make sure you have an SSH key setup.
Create a new FreeBSD droplet. Make sure you use the UFS version
Make sure you select the $5 a month plan. For simple installs, this is more than enough!
Make sure your SSH key is selected
Finally click that green Create Droplet button!
SSH in once you’re done: ssh root@

Setting up your FreeBSD server with Bastille

Up until recently, everything was running on a Docker based platform using Exoframe. It was easy and almost brainless.

The downside was that Docker takes up wayyyy too many resources. Plus managing files within a Docker container is as much or more work than hosting it natively. Oh, and have you checked how much space Docker has been using on your machine lately? On my development machine its was about 19GB of space. ?

So what's the alternative?

FreeBSD Jails using Bastille.

I've been playing with Bastille for a few months now. The more I use it, the more it makes 100% sense.

Bastille allows you to create (now) portable lightweight FreeBSD based jails. These jails are "containers" that have virtually no overhead. There's no daemon (the operating system is the "daemon"!). Plus, jails are secure compared to the can of worms that Docker is. Yes, you may have to compile and port some utilities. Most though are already supported in FreeBSD's package manager pkg.

In this section you'll learn how to get a jail running with caddy so you can securely host your site.

Let's keep the momentum going!

Once you get the IP address for your server, you should login:

ssh root@123.456.789.10

You should get a MOTD message and an sh prompt. Woo!

FreeBSD 12.1-RELEASE-p2 GENERIC

Welcome to FreeBSD! ...

Let's install a few important bits using pkg (FreeBSD's package manager):

pkg install restic rsync bastille

We'll be using restic for backups, rsync for transferring files and bastille for jail setup.

You also have to set up some static routes in your pf.conf. Here's an example of mine:

ext_if="vtnet0"

# Caddy related
caddy_addr=10.10.2.20

set block-policy return
scrub in on $ext_if all fragment reassemble
set skip on lo

table  persist
nat on $ext_if from  to any -> $ext_if

# container routes
rdr pass inet proto tcp from any to port 80 -> $caddy_addr port 8880
rdr pass inet proto tcp from any to port 443 -> $caddy_addr port 4443

# Enable dynamic rdr (see below)
rdr-anchor "rdr/*"

block in all
pass out quick modulate state
antispoof for $ext_if inet
pass in inet proto tcp from any to any port ssh flags S/SA keep state

This is a standard pf.conf file for bastille. Make sure you edit caddy_addr to the IP you chose.

Now let's start the firewall. You will get kicked out of your ssh session:

sysrc pf_enable="YES"
service pf start

Then let's get some bastille configuration out of the way:

# set up bastille networking
sysrc cloned_interfaces+=lo1
sysrc ifconfig_lo1_name="bastille0"
service netif cloneup

# bootstrap the base jail and start bastille
bastille bootstrap 12.1-RELEASE update
sysrc bastille_enable="YES"
service bastille start

This will set up your networking, and fetch the latest default base jail you'll use later.

Next, let's set up the jail:

bastille create caddy 12.1-STABLE 10.10.2.20
bastille start caddy

Then install caddy

#install the binary
fetch https://github.com/caddyserver/caddy/releases/download/v1.0.4/caddy_v1.0.4_freebsd_amd64.tar.gz
tar xvf caddy_v1.0.4_freebsd_amd64.tar.gz caddy
bastille cp caddy caddy /usr/local/bin/
rm caddy

#create the caddy user
bastille cmd caddy pw useradd caddy -m -s /usr/sbin/nologin

#install ca root file
bastille pkg caddy install ca_root_nss

When installing ca_root_nss , pkg will have to initialize. Accept the prompts. Once you're done here we'll move on to the next step!

Once installation is complete, we should also configure caddy to start on boot. The easiest way to do that is use this rc.d script:

#!/bin/sh

# $FreeBSD: head/net/caddy/files/caddy.in 452063 2017-10-14 12:58:24Z riggs $
#
# PROVIDE: caddy
# REQUIRE: LOGIN
# KEYWORD: shutdown
#
# Add the following lines to /etc/rc.conf.local or /etc/rc.conf
# to enable this service:
#
# caddy_enable (bool):    Set to NO by default.
#                Set it to YES to enable caddy.
# caddy_user (user):        Set user to run caddy.
#                Default is "caddy".
# caddy_group (group):    Set group to run caddy.
#                Default is "caddy".
# caddy_conf (path):        Path to caddy configuration file.
#                Default is /usr/local/etc/caddyfile.conf

. /etc/rc.subr

name=caddy
rcvar=caddy_enable

load_rc_config $name

: ${caddy_enable:="NO"}
: ${caddy_user:="caddy"}
: ${caddy_group:="caddy"}
: ${caddy_conf:="/usr/local/etc/caddyfile.conf"}
: ${caddy_log:="/home/caddy/caddy.log"}
: ${caddy_env:="CADDYPATH=/home/caddy/"}
: ${caddy_https_port:="4443"}
: ${caddy_http_port:="8880"}

pidfile="/var/run/caddy.pid"
procname="/usr/local/bin/caddy"
command="/usr/sbin/daemon"
command_args="-f -p ${pidfile} /usr/bin/env ${caddy_env} ${procname} -agree -http-port ${caddy_http_port}  -https-port ${caddy_https_port} -conf=${caddy_conf} -log=${caddy_log} ${caddy_args}"
extra_commands="reload"

start_precmd=caddy_startprecmd
reload_cmd=caddy_reloadcmd

caddy_startprecmd()
{
      if [ ! -e ${pidfile} ]; then
              install -o ${caddy_user} -g ${caddy_group} /dev/null ${pidfile};
      fi
}

caddy_reloadcmd()
{
      kill -s USR1 $(cat ${pidfile})
}

run_rc_command "$1"

Remove the caddy executable if you haven't already. Then create a new file with vi. This will be your rc.d script!

vi caddy

Then paste the contents of the above script in there, save and exit.

Make sure the file is executable by using chmod and copy to the Caddy container.

chmod +x caddy
bastille cp caddy caddy /usr/local/etc/rc.d/

Finally, we'll need a Caddyfile. Here's an example of one:

stage.jaredwolff.com {
  tls hello@jaredwolff.com
  log /home/caddy/stage.jaredwolff.com.log
  root /var/www/stage.jaredwolff.com/
  gzip
  log stderr
}

log refers to this site specific access log.

root refers to where the root public folder is on your machine. In my case it's the common /var/www/. Set your paths and remember them. We'll need them later!

To have Caddy generate certs for this subdomain, you'll have to set the tls option. An email is all that's needed.

For more on the Caddyfile structure check out the documentation.

Make a file called caddyfile.conf and copy it to /usr/local/etc/ in your Caddy container:

vi caddyfile.conf
# Paste your caddyfile contents and save
bastille cp caddy caddyfile.conf /usr/local/etc/

You should now redirect your DNS to the server IP. That way Caddy can generate/fetch the correct certificates. Then you can start Caddy with:

bastille service caddy caddy start

You can check the log at /usr/home/caddy/caddy.log to make sure that your domain provisioned correctly.

Side note: Getting setup with SSL certs is tough at first, especially if you're migrating from another server. Your site will have to go down for a little bit while you switch your DNS settings and start caddy.

(That's if you're using standard caddy 1.0. You can also use the DNS provider plugins here which make things a little easier.)

Now that we have caddy up and running it's time to copy our hugo generated assets over using rsync. We're off to the next step!

Make building and deploying easy

I spend a ton of time writing C code, and that means I spend tons of time using Makefiles. For many, make (or gmake for GNU make) is the bane of their existence.

For building and deploying, make makes it easy to create reusable recipes. That way you know you can deploy with confidence every time.

My Makefile borrows from the one that Victoria Drake had posted not too long ago. I changed it up a bit to match my needs.

Let's take a tour and see what's inside:

.POSIX:

HUGO_VERSION := 0.66.0

OPTIMIZED_DIR := optimized
CONTENT_DIR := content
DEST_DIR := public

SERVER := 123.456.789.10
USER := user

The first section contains all the variables that I use to tell the functions later on what to do. It also has a reference to the .POSIX target. This means that the Makefile will be as portable between different versions of make.

Then, I popped in some logic to determine whether I'm deploying to stage or production:

# Set the place where it's deployed to.
ifdef PRODUCTION
$(info Building for production. ?)
TARGET := www
else
$(info Building for development. ?)
BASEURL := --baseURL "https://stage.jaredwolff.com"
TARGET := stage
endif

By default, recipes below will use the development workflow. To use the production workflow, you can invoke make like this:

PRODUCTION=1 make build

This does add some extra friction to the deploy process. It's a good step though. That way you're sure the deploy is going to the right place!

# Full path
DEPLOY_DIR := /usr/local/bastille/jails/caddy/root/path/to/$(TARGET).jaredwolff.com

Using the TARGET variable above, I then define the path to my server assets. I'm using Bastille to organize my jails, so the path is extra long. (yea, lengthly long) This allows us to use rsync to deploy the files with ease.

Now here come the fun bits. To do a full bulk resize, I'm using the wildcard functionality of the Makefile.

IMAGES := \
$(wildcard $(CONTENT_DIR)/*/images/*.jpg) \
$(wildcard $(CONTENT_DIR)/*/images/*.JPG) \
$(wildcard $(CONTENT_DIR)/*/images/*.jpeg) \
$(wildcard $(CONTENT_DIR)/*/images/*.png) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.jpg) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.jpeg) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.png) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.JPG) \

In this case it will create a huge space delimited list of every image that is within my content directory. The biggest drawback of this method is that it's not space tolerant. An easy fix to this is to make sure that all my photos do not have spaces.

Here's a quick and dirty bash command. You can use to rename files that have spaces and replace them with '_' characters:

for f in *\ *; do mv "$f" "${f// /_}"; done

Next, we rename these entries so the prefix is now the target directory. This will be useful when we want to resize:

OPTIMIZED_IMAGES := \
$(subst $(CONTENT_DIR)/,$(OPTIMIZED_DIR)/,$(IMAGES))

Now check out the optimize recipe:

.PHONY: optimize
optimize: build $(OPTIMIZED_IMAGES)
@echo "? Optimizing images"
rsync -r $(OPTIMIZED_DIR)/ $(DEST_DIR)/
du -sh $(CONTENT_DIR)/
du -sh $(DEST_DIR)/

$(OPTIMIZED_IMAGES):
convert -strip -compress JPEG -resize '730>' $(subst $(OPTIMIZED_DIR)/,$(CONTENT_DIR)/,$@) $@

It first calls the build recipe and then also the $(OPTIMIZED_IMAGES) recipe. The later will optimize the image using the convert command from Imagemagick. In this case I'm only resizing files that are larger than 730px wide. Change yours accordingly so you can reap the benefits of an optimized site.

After resizing, the recipe uses rsync to copy the files from the OPTIMIZED_DIR to DEST_DIR.

If we take a look at the build recipe, I first building the assets. Then, I copy the photos from the content dir to optimized dir. The nice thing is that rsync will only move files that have changed. Thus it doesn't have to copy the files over and over and over again every time you build.

Finally, the deploy recipe.

.PHONY: deploy
deploy:
@echo rsync to $(DEPLOY_DIR)
@rsync -r --del public/ $(USER)@$(SERVER):$(DEPLOY_DIR)/
@echo making restic snapshot
@scp scripts/backup.sh $(USER)@$(SERVER):/root/backup.sh
@ssh $(USER)@$(SERVER) sh /root/backup.sh $(DEPLOY_DIR)
@echo "? Site is deployed!"

You can see again that I'm using rsync to sync the contents of public/ to the server. Make sure you set the USER , SERVER and DEPLOY_DIR. In my case DEPLOY_DIR comes out to /usr/local/bastille/jails/caddy/root/var/www/www.jaredwolff.com

When you do finally get a successful deploy you can double check everything is in the correct place. Then once everything looks good you can start up your caddy server using:

bastille service caddy caddy start

deploy will also do something extra handy here. It will deploy my restic backup script and run it. I'll talk about this more in the backup section.

All in all, here's the full Makefile:

.POSIX:

HUGO_VERSION := 0.66.0

OPTIMIZED_DIR := optimized
CONTENT_DIR := content
DEST_DIR := public

SERVER := 155.138.230.8
USER := root

# Set the place where it's deployed to.
ifdef PRODUCTION
$(info Building for production. ?)
TARGET := www
else
$(info Building for development. ?)
BASEURL := --baseURL "https://stage.jaredwolff.com"
TARGET := stage
endif

# Full path
DEPLOY_DIR := /usr/local/bastille/jails/caddy/root/var/www/$(TARGET).jaredwolff.com

IMAGES := \
$(wildcard $(CONTENT_DIR)/*/images/*.jpg) \
$(wildcard $(CONTENT_DIR)/*/images/*.JPG) \
$(wildcard $(CONTENT_DIR)/*/images/*.jpeg) \
$(wildcard $(CONTENT_DIR)/*/images/*.png) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.jpg) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.jpeg) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.png) \
$(wildcard $(CONTENT_DIR)/*/*/images/*.JPG) \

OPTIMIZED_IMAGES := \
$(subst $(CONTENT_DIR)/,$(OPTIMIZED_DIR)/,$(IMAGES))

.PHONY: all
all: build optimize

.PHONY: clean
clean:
rm -rf public/
rm -rf optimized/

.PHONY: serve
serve:
@hugo serve -D

.PHONY: ssh
ssh:
@ssh $(USER)@$(SERVER)

.PHONY: build
build:
@echo "? Generating site"
hugo --gc --minify -d $(DEST_DIR) $(BASEURL)
rsync -av --del -f"+ */" -f"- *" $(CONTENT_DIR)/ $(OPTIMIZED_DIR)/

.PHONY: optimize
optimize: build $(OPTIMIZED_IMAGES)
@echo "? Optimizing images"
rsync -r $(OPTIMIZED_DIR)/ $(DEST_DIR)/
du -sh $(CONTENT_DIR)/
du -sh $(DEST_DIR)/

$(OPTIMIZED_IMAGES):
convert -strip -compress JPEG -resize '730>' $(subst $(OPTIMIZED_DIR)/,$(CONTENT_DIR)/,$@) $@

.PHONY: deploy
deploy:
@echo rsync to $(DEPLOY_DIR)
@rsync -r --del public/ $(USER)@$(SERVER):$(DEPLOY_DIR)/
@echo making restic snapshot
@scp scripts/backup.sh $(USER)@$(SERVER):/root/backup.sh
@ssh $(USER)@$(SERVER) sh /root/backup.sh $(DEPLOY_DIR)
@echo "? Site is deployed!"

There are a few other handy nuggets in there you may want to use. clean, serve and ssh have been very helpful when testing and connecting.

In the end you'll have a two step deploy process. The first generates your site with optimized images. The second is deploying to a server for static hosting.

Incremental Backup

After discovering Restic I've been sold on how handy it has been for all my incremental backup needs. In the case of my server, I'm using to back up the root folder of my site. That way, if I need to roll back, I can do so with a few short steps.

Here's how you can set up a local restic repo.

Setting it up

Initializing the repo is simple. The most important part is making sure you don't lose/forget your password!

    # restic init -r /root/backups
    enter password for new repository:
    enter password again:
    created restic repository 32e14c7052 at /root/backups

    Please note that knowledge of your password is required to access
    the repository. Losing your password means that your data is
    irrecoverably lost.

Set the RESTIC_PASSWORD environment variable to avoid entering your password. To make it permanent you'll have to place export RESTIC_PASSWORD="Your password here!" within the .profile file in /root/.

Backing Up

Invoking restic over SSH is tough. So our next best bet?

Transfer a (very brief) shell script to the server and run it after a deploy. Here's the contents of what I'm using today:

#!/bin/sh
export RESTIC_PASSWORD="Your password here!"
restic backup $1 -r /root/backups/

Side note: As I sit here and look at this script, for security reasons you can replace "Your password here!" with $2 which is the second argument to the script. That way you don't need to commit/push the password stored in a static file!

This first sets your backup password. Then it runs restic using the first command line argument as the path. So, to run a backup with this script, it would look something like this:

./backup.sh /path/to/your/public/folder/

Note: you do need to initialize your restic backup before you start backing up. It will barf at you otherwise!

In my case I'm placing the incremental backups on a different folder of my machine. That way they're easily accessible and fast.

Viewing your backups

To view your backups you can run the following command:

restic snapshots -r /root/backups -g paths -c

enter password for repository: repository e140b5e4 opened successfully, password is correct snapshots for (paths [/usr/local/bastille/jails/caddy/root/var/www/www.jaredwolff.com]):

ID Time Host Tags

d3328066 2020-03-10 00:30:58 vultr.guest f3360819 2020-03-10 04:03:03 vultr.guest 231dd134 2020-03-10 04:44:00 vultr.guest 3c1be26a 2020-03-10 04:56:19 vultr.guest e96c947c 2020-03-10 05:03:00 vultr.guest 34c3682a 2020-03-10 14:01:37 vultr.guest fbccdb8c 2020-03-10 14:04:26 vultr.guest 9ce11146 2020-03-10 15:38:49 vultr.guest 046b3da3 2020-03-10 15:47:06 vultr.guest 9c28d4bc 2020-03-10 15:48:25 vultr.guest 469dc228 2020-03-10 15:48:54 vultr.guest 6f78af72 2020-03-10 17:00:21 vultr.guest 29ad17b2 2020-03-10 20:18:23 vultr.guest ed22ce1f 2020-03-10 20:20:24 vultr.guest 9c8c1b03 2020-03-11 13:56:40 vultr.guest b6cfcfec 2020-03-11 14:08:14 vultr.guest e8546005 2020-03-11 14:27:22 vultr.guest 49a134fe 2020-03-17 00:47:58 vultr.guest

c0beb283 2020-03-18 20:44:52 vultr.guest

You can use this list to determine if you need to roll back a deploy.

Restoring

Restoring from a backup, especially in a live environment, needs to be quick. After viewing your backups you can restore a specific backup by using its ID.

restic restore d3328066

This will restore the files back to the backup made on 2020-03-10 00:30:58. Awesome. Plus it won't overwrite every single file. It will only apply the differences from the current state and the stored state.

Conclusion

We've covered a ton of ground in this post. You've learned how to:

Deploy your own server using Vultr
Use Bastille to create Container-like Jails
Set up Caddy to serve static file assets with TLS
Deploy the files using a fairly simple Makefile and rsync
Back up after every deploy using restic

In the end we have a robust, secure and simple platform for hosting static files and services.

Stay tuned as there are more posts like this coming your way soon! In the meantime check out my other posts.

Thanks for reading and see you next time! ?

You can find other articles like this at www.jaredwolff.com.

How to Publish a no-code website in 10 minutes

freeCodeCamp — Sat, 28 Mar 2020 20:59:47 +0000

In this article, I'll introduce a no-code, no-software and no-cost solution to publishing sophisticated web sites managed by non-technical people. The full codebase is on GitHub here.

Sir Issac Newton discovered the law of gravity when practicing “social distancing” during the Plague. What will YOU do? One silver lining of quarantine is that all this free time brings out the entrepreneur spirit and creativity in us.

However, especially because of the quarantine, now more than ever, any new idea or project must have a web site. Traditional CMS solutions like Wordpress, Squarespace, or Wix are difficult to use, look dated, are expensive, or all of the above!

We wanted to create a web site that has a sophisticated look and feel, yet is easy to customize. A non-technical person should be able to edit the source files and see the changes appear on the live web site in a few minutes. Ideally, it should also be free (forever free, not just free-for-now), and can scale to handle millions of visitors if it becomes popular.

Is this possible?

In this short article, I will walk you through a solution based on the Hugo framework, GitHub Pages, and GitHub Actions. You can get up and running with your shiny new website by the end of this article.

It is so easy that my 9-year-old son did it. He now manages a web site for his fictional country called Arenztopia. Check out the back story.

TL;DR

If you just want to get started with a working web site as soon as possible, first make sure that you have a free GitHub account.

Go to this GitHub repository, and click on the “Fork” button on the top right, and fork it to your own account.

Go to your forked repository, and click on the Actions tab. You will see a message like the one in the picture below. Click on the “I understand my workflows …” button.

Go to the Settings tab of your repository, and then scroll down to GitHub Pages. Re-select the gh-pages from the dropdown for the web site to build.

Go to the Code tab of the repository, open the config.toml file, and edit it. Change its title attribute to something else, and click on the “Commit changes” button at the bottom. We need this step to trigger the workflow at the new repository.

Wait a few minutes, go to the “published at” web address at GitHub Pages and you will see the template web site.

Next, you can customize the site by editing the config.toml file and the files in the content folder. Go to the “Add your own content” section at the end of this article to see how. You can check out the instructions for the Ananke theme here.

That’s it for the quick start! In the next several sections, I will explain in more detail the concepts and processes.

Hugo basics

Older generation CMS solutions like Wordpress are too difficult to adapt to new web site designs, and commercially hosted solutions like SquareSpace are too expensive and not flexible enough. Static web site generators like Hugo offer a good balance among features, flexibility, and ease of authoring.

Hugo web sites can be customized and modified through configuration files.
New pages and content sections can be written in markdown instead of HTML. That makes content authoring much easier.
There are many modern design themes to choose from.
The output of Hugo is a static HTML web site that can be deployed on any low-cost hosting provider.
Together with static web site hosting services like GitHub Pages and Netlify, they can offer a completely free solution.

The Hugo software distribution is available on all major operating systems. You can learn about it here. But, since we will use GitHub Actions to automatically build our Hugo web sites, we do not actually need to install Hugo software here.

Here is how to do it.

Create a template website

First, select a Hugo theme. There are many. Some are geared toward web sites with one or more content web pages, while others are optimized for blog-like sites with timestamped posts.

Hugo themes

Find one you like, download a zip package or clone a GitHub repo, and unpack the theme into a folder. Let’s assume that the theme distribution is unpacked into a folder called my-theme. The following are commands in a Linux terminal. You could use the Terminal app on Mac or PowerShell on Windows.

Next, create your web site project directory on your computer.

$ mkdir -r my-site/themes

Copy the theme folder into your project.

$ cp -r my-theme my-site/themes

Next, copy the theme’s exampleSite to the project’s top-level directory.

$ cd my-site
$ cp -r themes/my-theme/exampleSite/* ./

Edit the config.toml in the project root directory my-site/ to point to the right theme.

baseURL = "/"themesDir = "themes"theme = "my-theme"

Next, create a GitHub repo called my-site, and push the my-site directory onto its master branch. Here are the steps for uploading files from GitHub’s web UI. Now we are ready to publish the theme example site.

For a Hugo-based system to be useable to a non-developer (or a young developer who has yet to master the command line tools), we must automate the process of building and deploying the static web site.

Automate deployment

In the GitHub project, go to Settings and enable GitHub Pages. Select the source to be the gh-pages branch.

Settings, GitHub Pages

Next, we create a GitHub Actions workflow to run the Hugo command on the source files from master branch, and push the generated HTML files to the gh-pages branch for publication. From the project’s Actions tab, click on the “set up a workflow yourself” button.

Set up a workflow yourself

The workflow is stored in the master branch as .github/workflows/main.yml file. The content of the file is as follows.

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v1  # v2 does not have submodules option now
        # with:
        #   submodules: true

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.62.2'
          extended: true

      - name: Build
        run: hugo

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

What happens here is that the web site authors and editors will change content and files on the master branch. Whenever new content is pushed to the master branch, the automated GitHub Actions workflow will set up the Hugo software, run the hugo command, and turn those files into HTML files for a static web site.

The HTML files are pushed to the gh-pages branch of the same repository. They will be published on the specified web address by GitHub Pages as configured.

Notice the cname attribute in the last line. That is the custom domain name we set up with GitHub Pages. If you do not have a custom domain name, just remove this line, and you can access your web site at the domain provided by GitHub Pages.

Now go to the web site, and you should see the theme’s default web page.

The HugoSerif template for one of our web sites.

Add your own content

To change the default theme web site to your own content, you just need to change the files on the master branch. Please refer to the documentation of your selected theme. In general, Hugo templates work like this:

The web pages are authored in markdown format and the md files are in the content folder.
Each md file has a header section with properties such as the page’s menu placement, priority, timestamp, excerpt, etc.
The overall configuration, such as the menu items and properties used by multiple pages, are stored in the data folder.
Static content such as raw HTML files, JavaScript files, and image files can be placed in the static folder.

In particular, here is how you customize the Ananke theme that comes with our template:

The config.toml file allows you to configure the website title, social icons on all pages, and the big featured image on the home page.
All images should be uploaded to the static/images folder.
The content/_index.md file contains the text for the home page.
To add pages to the site, you can just create markdown files in the content folder. An example is the contact.md file. Notice that at the top of the file, there are attributes to control whether this page should be on the website menu.
To add articles to the site, you can create markdown files in the content/post folder. Those are blog-like content articles that have dates and titles at the top. The most recent two articles will show up on the home page.

If you are interested in learning more and see how we did it, you can watch our progress at

The Country of Arenztopia [GitHub] [Web site]
Second State blog [GitHub] [Web site]

Good luck and stay healthy!

About the author

Dr. Michael Yuan is the author of 5 books on software engineering. His latest book Building Blockchain Apps was published by Addison-Wesley in Dec 2019. Dr. Yuan is the co-founder of Second State, a VC-funded startup that brings WebAssembly and Rust technologies to cloud, blockchain, and AI applications. It enables developers to deploy fast, safe, portable, and serverless Rust functions on Node.js.

Prior to Second State, Dr. Yuan was a long time open source contributor at Red Hat, JBoss, and Mozilla. Outside of software, Dr. Yuan is a Principal Investigator at the National Institutes of Health, with multiple research awards on cancer and public health research. He holds a PhD in astrophysics from the University of Texas at Austin.

How to Create Your First Hugo Blog: a Practical Guide

Flavio Copes — Wed, 08 Jan 2020 08:44:58 +0000

Hugo is a great tool to use if you want to start a blog.

I use Hugo myself for my blog, flaviocopes.com, and I've been using it for more than two years. I have a few reasons for loving Hugo.

First of all, it is simple, boring, flexible, and fast.

The main reason is that it is simple. There’s not much you have to learn to get started.

You write content in Markdown, a format that lets me use my favorite editor (Bear) to write posts.

Hugo is boring. Don’t get me wrong, this is a very positive thing. As a developer I am tempted to tweak things here and there all the time. There’s no fancy technology underlying Hugo. It’s built using Go, one of the languages I love the most, but that does not mean I want to dive into the internals of Hugo and change how it works.

And it does not surface any cool or next-generation stuff like many JavaScript frameworks tend to do.

Hence it is boring, which gives me a lot of time to do what is really useful when working on a blog: writing content. I focus on the content, not on the content container.

That said, Hugo is pretty darn flexible. I started my own blog with an open source theme, then changed it completely over time. Sometimes I want to do things in my website that are out of the scope of a simple blog, and Hugo allows me to create those things.

Finally, another reason I love Hugo is that it is fast. Why? First, it has Go at the core, which is known to be a very fast language. And in the Go ecosystem, there’s no concept of 100 megabytes dependencies. Things are made to be as fast as possible. Plus, Hugo does not need to do some of the fancy stuff that is needed when using fancy technology. This is a by-product of being boring.

Anyway, enough with words.

Hugo is amazing, especially if you are a developer and you’re willing to write in Markdown. Non-tech people might just refuse to use Markdown, and it’s perfectly understandable.

Also, you have to be prepared for a Git-centric workflow to make things really click.

This is the process for writing a blog:

write a post using Markdown,
then commit your changes to a Git repository, most commonly on GitHub,
and then some glue technology deploys the changes on the server that hosts the site.

Hosting a Hugo website

A Hugo blog is completely static. This means you don’t need to host your own server, or use a special service for it.

Netlify, Now and GitHub Pages are three great places where you can host a Hugo blog, for free.

The only cost is the one you have to sustain for the domain name. I can’t stress enough the importance of having your own domain name. No .github.io or .netlify.com or .now.sh sites, please.

My own Hugo sites are hosted on Netlify.

Choose a domain

Put your blog under your own domain. Pick one. Use your own name. And use .com or .blog. Don’t try to be clever by using a localized domain - for example, don’t use .io. .com just gives a better impression and it’s reusable for all your future projects, not just to host your blog. I picked that one.

Oh and if you have an old domain lying around, just use that. Why? The older your domain is, the better.

Note on subdomains: every subdomain, to Google, is a different website. So if your domain is flaviocopes.com, and you create your blog in blog.flaviocopes.com, then that’s a completely new website to Google, and it will have its own ranking separate from the main domain.

My suggestion is to avoid subdomains completely.

Install Hugo

To install Hugo on macOS, from your terminal run

brew install hugo

The brew command does not exist on your Mac? Check the Homebrew guide.

For Windows and Linux, check the official installation guide.

Create a Hugo site

Once Hugo is installed, you can create a Hugo site by running

hugo new site myblog

I suggest that you run this into a www folder in your Home directory, because the command will create a new myblog folder where you run it.

Pick a theme

Now before you can start you need to pick a theme. I wish Hugo included a default theme to make things straightforward, but it does not.

There are a lot of choices on https://themes.gohugo.io. My personal recommendation is to start with https://themes.gohugo.io/ghostwriter/ and tweak it later.

I also recommend that you avoid the git clone workflow they suggest on that page. You’ll surely be tweaking the theme in the future, and I find it best to have a single repository for both content and theme. It simplifies deployment.

So, go to https://github.com/jbub/ghostwriter/archive/master.zip to download the current version of the theme.

Then unpackage it in the themes/ghostwriter folder in your newly created Hugo website:

Notice there is an exampleSite folder in the themes/ghostwriter. Open it, and open its content subfolder. In there, you can see the page, post and project subfolders.

Copy page and post in the content folder of the site:

The configuration

The sample data also provide a sample config.toml file in themes/ghostwriter/exampleSite/config.toml. This is the Hugo configuration file, which tells Hugo some details of the configuration without you having to hardcode information in the theme.

I recommend that you not copy that, because it has too many things, and instead use this:

baseurl = "/"
title = "My blog"
theme = "ghostwriter"

[Params]
    mainSections = ["post"]
    intro = true
    headline = "My headline"
    description = "My description"
    github = "https://github.com/XXX"
    twitter = "https://twitter.com/XXX"
    email = "XXX@example.com"
    opengraph = true
    shareTwitter = true
    dateFormat = "Mon, Jan 2, 2006"

[Permalinks]
    post = "/:filename/"

You can freely customize the information in this file later.

Now from the command line, run:

hugo serve

Open http://localhost:1313 in your browser, and you should be able to see the site live!

This is the site home page.

There is a list of posts that is taken from the content/post folder of your website:

Click the first, called “Creating a New Theme”:

You can open the file content/post/creating-a-new-theme.md to change anything in the post.

If you save, the website will automatically update with the new content.

This is pretty awesome, right?

You can create a new post by creating a new .md file, prefixing it with anything you want. You can use incremental numbers, if you prefer. Or use a date.

If something doesn't look the way you want, you can open the themes/ghostwriter/layouts folder and tweak it.

The “post” template is defined in themes/ghostwriter/layouts/post/single.html:

Hugo uses Go templates. The syntax can be pretty unfamiliar but the Hugo website does a very good job at explaining them in this Go templates introduction.

However, try to not look at customizing your template now.

If you want to tweak the colors, add a