Why Use Hugo?
Hugo is a fast, customisable static website generator written in the Go programming language. Using Hugo as your static website generator of choice provides quick build times, a flexible template language, customisable themes, and reduces the complexity for running basic websites providing improved performance and speed.
Installation
MacOS or Linux
The easiest way to download Hugo on MacOS or Linux is using Homebrew.
brew install hugo
Windows
If you are on Windows, you can get Hugo using the Chocolatey package manager.
choco install hugo-extended -confirm
Other Methods
For further details on installing Hugo see the official installation guide.
Setup
Once Hugo is installed, open a terminal and choose the directory where you wish to keep your website by initialising a new site with Hugo. In this example, we will use the path ~/demo/my-website.
hugo new site ~/demo/my-website
After running the command, a new template should be generated with the initial default folders and files as shown below.
my-website ├── archetypes │ └── default.md ├── config.toml ├── content ├── data ├── layouts ├── static └── themes
Version Control
Its good practice to keep projects under version control, so lets set up a repository for our website using the Git command.
cd ~/demo/my-website && git init
If we run git status, we can see that we need to commit the new files generated from the hugo command. Notice how Git is only interested in folders with files and ignores the empty folders.
On branch master No commits yet Untracked files: (use "git add <file>..." to include in what will be committed) archetypes/ config.toml nothing added to commit but untracked files present (use "git add" to track)
Let's add the new files to Git to track. We can add everything with the git add . command or individual files as in the example. We will also need to add a commit message to complete the staging process.
git add archetypes config.toml
git commit -am "Initial Hugo website"
Theme
Next, select a Hugo Theme that you like and follow their instruction to install it into your Hugo website.
For example, to install the Fuji theme clone the Git repository as a submodule into the themes folder.
git submodule add https://github.com/amzrk2/hugo-theme-fuji themes/fuji
Your directory structure should look something like this.
my-website
├── archetypes
├── content
├── data
├── layouts
├── static
└── themes
└── fuji
├── assets
├── exampleSite
├── i18n
├── images
├── layouts
├── resources
└── static
Copy a post entry from the theme's exampleSite directory to verify that Markdown formatting is being rendered correctly.
mkdir content/post cp themes/fuji/exampleSite/content/post/markdown-syntax.md content/post/
Lastly, to get Hugo to use the theme we downloaded set the theme name in the config.toml file. This should be found in your website's directory.
echo 'theme = "fuji"' >> config.toml cat config.toml
Server
Let's check everything is working. Test that the website is working by running a local server through Hugo. If you have any draft posts then don't forget to use the -D flag with the command
hugo serve -D
Start building sites …
| EN
-------------------+-----
Pages | 18
Paginator pages | 0
Non-page files | 0
Static files | 8
Processed images | 0
Aliases | 8
Sitemaps | 1
Cleaned | 0
Built in 61 ms
Watching for changes in ~/demo/my-website/{archetypes,content,data,layouts,static,themes}
Watching for config changes in ~/demo/my-website/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
If Hugo has been configured correctly, there should be a similar output to the example and the website should now be available to preview. To view the server enter the server address displayed into your web browser, for example. http://localhost:1313 and the home page should load. Keep in mind that that localhost post numbers are mutable and therefore may differ from the example.
Commit Changes
If we run git status, Git will shows us that we have uncommitted changes.
On branch master Changes to be committed: (use "git restore --staged <file>..." to unstage) new file: .gitmodules new file: themes/fuji Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: config.toml Untracked files: (use "git add <file>..." to include in what will be committed) content/ resources/
Therefore, let us save the changes that we have made so far. We don't need to track the resources folder to the repository at the moment. So let's ignore it by adding it to a .gitignore file.
echo "resources/" > .gitignore
Now we can stage and commit the new changes.
git add .
git commit -am "Set theme"
Conclusion
🥳 Congratulations! You now have successfully configured a locally served website ready to use. You can play around with your theme settings to customise the site as you like, or start writing blog posts using the example in the content/posts/ folder.
Alternatively, you can use the command hugo new to generate an empty post template to work on. This command creates a file relative to your context folder, therefore hugo new post/hello-world.md will create a file in the content/post/ directory which contains some metadata.
--- title: "Hello World" date: 2021-03-18T18:00:01Z draft: true ---
What's Next?
Coming up we will learn how to easily host your new website online and share it with the world!