About This Sample

The sample below was created to document my own process of creating this site. This is written primarily for other content developers moving from a traditional content management system into a static site generator.

CriteriaDescription
ToolsHugo, Git, Markdown
SMEsnone
Othersnone

The sample begins below the line.


This portfolio site was built using Hugo, a static site generator (SSG). SSGs are becoming increasingly common as a publishing tool, particularly for API documentation and other docs-as-code scenarios. Unlike a traditional content management system (CMS) like Wordpress, SSGs don’t have databases. This enables them to build websites more quickly. They are also more secure because without a database, there is no threat of database hacks.

Hugo is one of the most popular SSGs available. For content developers interested in creating a portfolio site, follow this guide to create a Hugo site and deploy it to GitHub Pages.

Tools

  • command line interface (CLI) tool
    • Powershell: Windows users should use Powershell as their CLI tool. Not to be confused with Windows Powershell, which should not be used.
  • Notepad++, or text editor of your choice

Installation

Install the following. Note that the Dart Sass and Hugo installations require you to add new directories to your computer’s PATH environment variable. See instructions here.

Creating a Site

  1. Select a theme. Consider whether you need a single- or multi-page theme for your site. It’s also worth noting each theme’s documentation. This site uses the Gokarna theme, which provides extensive documentation. This makes it easier to configure compared to themes with sparse documentation.
  2. Follow Hugo’s quick start tutorial to create a site and a new page.
  3. Enable embedded link and image render hooks: Open the site configuration file, hugo.toml, in your text editor. Add the following into the file.
[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.link]
        enableDefault = true
      [markup.goldmark.renderHooks.image]
        enableDefault = true
  1. Create additional site content. To ensure proper image processing, site content should be organized in the structure below with global resources in assets/images and page resources bundled into separate content folders.
assets/
└── images/
    ├── a.jpg			<-- global resource, accessible sitewide
    └── b.jpg
content/
├── samples/
│   ├── sample1/
│   │   ├── c.jpg 		<-- page resource, accessible by sample1/index.md only
│   │   └── index.md  	<-- contents of sample1 page (without underscore)
│   ├── sample2/
│   │   ├── d.jpg
│   │   └── index.md
│   └── _index.md		<-- samples section list page (with underscore)
├── posts/
│   ├── post1/
│   │   ├── e.jpg
│   │   └── index.md
│   └── _index.md
└── _index.md			<-- site homepage (with underscore)

Deploying to GitHub Pages

Follow Hugo’s instructions for hosting on GitHub Pages. Note that for Powershell users, the touch filename.txt command is replaced by "" > filename.txt.

In addition, remove your public directory from source control using these steps.

  1. Create a .gitignore file using this command.
touch .gitignore

For Powershell users, the command uses this syntax.

"" > .gitignore
  1. Open the .gitignore file in your text editor. Add the following:
.hugo_build.lock
/public/
/resources/
  1. Remove the public directory from source control.
git rm -rf public/
  1. Commit and push your changes.
git add -A
git commit -m "Remove public directory from source control"
git push