Create Repo For Hugo On GitHub

This tutorial covers the creation of a private and public repo including the setup of workflows for automated deployment.

Tutorial

What you will learn

In this document, I’ll show how to create your own website using Hugo, a template, and GitHub pages. I struggled setting up my very first page and was thankful for getting help on the setup. I want to share my experience and help you create the infrastructure for your own website.

Requirements

The editor of my choice is Visual Studio Code. There are plugins for almost everything e.g. GitHub.

Step	Requirement
1	I expect that you have already installed Hugo (extended) on your machine. If this is not the case, go to their website and read the quick-start section.
2	I’ll use my favorite template Doks. This template is different because it requires installing Node. If you choose another theme that’s fine, some of the following steps can be skipped.
3	Install Node.

Setup Hugo Site

Theme	Description
Doks	Navigate to the root folder and open a console. Install all dependencies with `npm install`.
Non-Doks	Create a new site with Hugo and insert your theme in the themes folder.

Start you local webserver by typing hugo server in the console. By default your site is hostet on localhost:1313.

Btw. if you like that template, check out Doks Homepage.

Create Source repo (private)

Create a new private repo on GitHub. This will be the source repo which you will use to make changes. The content is private and nothing you want to share. Open GitHub on your browser and create a new repo.

Switch over to VSCode and add your project to the repo.

Initialize GitHub repo locally with git init on the root directory.
Ensure that there is no public and resources folder in your project.

Also delete the files from /.github/workflows marked in the next picture:

Step	Command
Connect to source repo	`git remote add origin https://github.com/[your github name]/[your PRIVATE repo name].git`
Add all files	`git add .`
Commit	`git commit -m "initial commit"`
Push to GitHub	`git push origin master`

Create GH-pages repo (public)

📌

Again, it's important that there is not public or resources folder in your project hierarchy

First, create another repo. This time make it public. Then create a submodule that will be publicly available and represent the source for GitHub pages.

git submodule add https://github.com/[your github name]/[your PUBLIC repo name].git public

This should now create the public folder.

Ignored by .gitignore (optional)

If you receive a message like this:

$ git submodule add https://github.com/xuptox/public_gh_pages_repo.git public
The following paths are ignored by one of your .gitignore files:
public
hint: Use -f if you really want to add them.
hint: Turn this message off by running
hint: "git config advice.addIgnoredFile false"

Open .gitignore and remove the line for public.

Create Submodule

If you created the public repo and removed public from .gitignore.
Rerun the git submodule... command again.

You should get a message like this:

$ git submodule add https://github.com/xuptox/public_gh_pages_repo.git public
Cloning into '[path to project]/doks-master/public'...
warning: You appear to have cloned an empty repository.
fatal: You are on a branch yet to be born
Unable to checkout submodule 'public'

Step	Command
Build your website	`hugo`
Navigate to `public` folder	`cd public` or use VSCode
Add the file	`git add .`
Commit	`git commit -m "first build"`
Navigate back to root	`cd ..`
Add all files	`git add .`
Commit everything (incl. the submodule)	`git commit -m "first build incl. submodule ref"`
Push source and public (ref) to GitHub	`git push -u origin master --recurse-submodules=on-demand`

Check your project hierarchy. Right next to your public folder you should see the letter S indicating that it’s a submodule.

Your private repo on GitHub should also indicate that the public folder is referencing another repo.

Add Actions

Create Personal Token

Before we create the actual workflow, you need to create a personal access token that allows you to commit and push to the public repo.

Create a token in your Token Settings on GitHub. Hit Generate new token and select the checkbox repo.

This allows full control on the repo. Scroll down and hit Generate to create the actual token value.

You must copy that string as it will not be shown again when you leave this page.

Open another tab in your browser and add the created token to your Secrets Page on GitHub.
Click New repository secret and paste the created token to the lower textbox. Give that token a name e.g. PERSONAL_TOKEN and hit Add secret.

Create Workflow

Navigate to /.github/workflows and create a new file gh-pages.yml. Copy and paste the following content into the file and save.

name: github pages

on:
  push:
    branches:
      - master # Set a branch to deploy

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod

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

      - uses: actions/setup-node@v2
        with:
          node-version: "14"
          check-latest: true
      - run: npm install

      - name: Build
        run: hugo --gc --minify && npm run build:functions

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          external_repository: [YOUR USER]/[YOUR PUBLIC REPO NAME]
          publish_dir: ./public
          #   keep_files: true
          user_name: [YOUR USER]
          user_email: [YOUR MAIL]
          publish_branch: master

Change the values in brackets [] corresponding to your user name, GitHub repo, and mail.
I’m not sure if the user_email needs to be a real mail address.

Save the file and push changes to GitHub.

If you use VSCode you can also use the GitHub plugin. It’s another way to add, commit…

and finally, push your content to GitHub.

The rest is up to you.

You need to activate your GitHub-Page via Settings.
In case you have a custom domain, you also need to set up your DNS.
Also use encryption on your page.

Contributes

I used the following sources to create this guide:

Special Thanks goes to Alechandro!
Thanks to everyone!

Create Repo For Hugo On GitHub

What you will learn#

Requirements#

Setup Hugo Site#

Create Source repo (private)#

Create GH-pages repo (public)#

Ignored by .gitignore (optional)#

Create Submodule#

Add Actions#

Create Personal Token#

Create Workflow#

Contributes#