Building a Documentation Site from Scratch using Hugo
November 21, 2020
Documentation is a must in every software development project. Reliable documentation provides an accurate overview of your software, good insight on how to use your software, and easy onboarding for new users of your software.
In this tutorial, I will teach you how to build a documentation website for your software projects using Hugo and the Docsy theme. Hugo is a speed optimized static site generator written in the Go programming language. Hugo can generate documentation websites, blogs portfolio websites, etc. directly from a markdown file and HTML files.
Table of contents
- Install Hugo.
- Create your website.
- Install and set up the Docsy theme.
- Add a content section to your website.
- Add a documentation page to your website.
- Preview your website.
- Build your website.
This guide assumes that you have th following installed:
- Go installed on your local machine - visit ednsquare.com for instructions on how to install Go on macOS, Windows, and Linux.
- Homebrew (macOS and Linux) - visit brew.sh for instructions on how to install homebrew on macOS and Linux.
- Chocolatey (Windows) - visit chocolatey.org for instructions on how to install chocolatey on Windows.
- npm: Download Nodejs to install npm on your local machine.
Step 1 - Install Hugo
The Docsy theme uses the Hugo-extended version of Hugo. Install the Hugo-extended version on macOS and Linux with Homebrew.
brew install hugo
Verify your installation.
$ hugo version Hugo Static Site Generator v0.64.1/extended darwin/amd64 BuildDate: unknown
Install the Hugo-extended version on Windows with Chocolatey.
choco install hugo-extended -confirm
Verify your installation.
$ hugo version Hugo Static Site Generator v0.78.1/extended windows/amd64 BuildDate: unknown
Step 2 - Create your website
Create a new Hugo website with the
hugo new site command.
$ hugo new site documentation-website Congratulations! Your new Hugo site is created in /Users/sheriff/hugo-project. Just a few more steps and you are ready to go: 1. Download a theme into the same-named folder. Choose a theme from https://themes.gohugo.io/ or create your own with the "hugo new theme <THEMENAME>" command. 2. Perhaps you want to add some content. You can add single files with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>". 3. Start the built-in live server via "hugo server". Visit https://gohugo.io/ for quickstart guide and full documentation.
hugo new site command will also generate a directory with the following file structure:
hugo-project/ ├── archetypes ├── config.toml ├── content ├── data ├── layouts ├── static └── themes
The following files are:
archetypes: Directory for storing content template files.
config.toml: Hugo configuration file.
content: Directory for content files.
data: Directory for storing configuration files.
layouts: Directory for storing .html template files.
static: Directory for storing all static contents.
themes: Directory for storing your themes.
Step 3 - Install the Docsy theme
The Docsy theme is a Hugo theme that is built specifically for creating medium to large technical documentation websites. The theme comes preloaded with basic documentation features like the search bar, the menu, etc.
To install the Docsy theme, we can follow these steps:
- cd to your project’s directory.
- Install postCSS and autoprefixer.
- On macOS and Linux.
sudo npm install -D --save autoprefixer sudo npm install -D --save postcss-cli
- On Windows.
npm install -D --save autoprefixer npm install -D --save postcss-cli
- Install the Docsy theme by adding it into your project as a git submodule.
git init git submodule add https://github.com/google/docsy.git themes/docsy echo 'theme = "docsy"' >> config.toml git submodule update --init --recursive
Step 4 - Add a content section to your website
All your website’s content files are stored in the
content folder found in your root folder. The top-level subfolders in the
content folder will determine the sections of your website by default, and the nested subfolders inside these top-level subfolders combine to form your website structure as they are organized in their top-level subfolders.
content <-- Content folder |--- Documentation <-- Top level subfolder(main section in your website). | |---- New Documentation <-- Nested subfolder(subsection found in the documentation section).
To add a custom section to your website, we can do the following:
- cd to the
- Create a new subfolder with the custom section name ie
- Add the new section to your
menufor easier navigation by editing your config.toml file.
[menu] [[menu.main]] identifier = "documentation" name = "Documentation" pre = "<i class='fa fa-heart'></i>" url = "/documentation/" weight = 20
Note: Most editing apps will encode your cofig.toml file incorrectly. Make sure to open your config.toml file with notepad++ on windows
start notepad++ .\config.toml, or use a code editor like Visual Studio Code.
Visit gohugo.io to learn more about creating sections.
Step 5 - Add a documentation page to your website
Add pages to your website by creating markdown or HTML files inside the subfolders found in the content folder, and then specify the page layout in the page’s frontmatter. Layouts in Hugo determine your page’s header, footer, navigation, and are provided by your theme.
Docsy ships with layout for 3 type of content,
docsfor documentation content.
blogfor blog content.
communityfor your community-oriented content.
To add a documentation page to our documentation section:
- Create and add the markdown or HTML file into the documentation folder.
or for Windows.
- Add the following yaml frontmatter to configure the page’s information and layout type.
--- title: "A new documentation page" weight: 1 type: docs summary: A new page for our Hugo documentation website. ---
- Add markup to your page.
# Hugo project website This is our new documentation page.
Visit docsy.dev to learn more about adding content to your website.
Step 6 - Preview your website
Hugo ships with a web server that has live reload built-in. This allows you to preview your changes in real-time when your web server is running.
Start your web server with the following command:
hugo server command
The web server will be hosted at http://localhost:1313, and will automatically reload when you make any changes in your website’s files.
Step 7 - Build your website
Build your website with the
hugo command. The command will generate all your website’s static files and store them in the
Documentation is an essential part of any software development project and can determine the success of failure of your project. By following this tutorial, you can have your Hugo documentation website set up easily with all your static files generated.
There are tons of other configuration options you can edit to improve the look and feel of your website.
Peer Review Contributions by: Gregory Manley