- Git. Follow the download/install instructions according to your platform.
- Hugo. You need to have Hugo installed in your local system.
- GitHub account. In order to host your blog or personal site you need to have to Sign-up to GitHub if you do not have an account already.
- (Optional) A secondary GitHub account. This is is particular useful to increase security regarding your main GitHub account. See more below.
This setup will use two repositories one for the sources used by Hugo and another one for blog/site.
- Head over to GitHub and create a new repository named
usernameis your username (or organization name) on GitHub.
- Create a second repository for the sources/skeleton of the site:
blog. The name is completely arbitrary but this tutorial will assume the use of
Use Hugo to create a site
If you are not familiar with Hugo, follow the quick-start. Here is a summary of it:
Initialize a site using Hugo. This will create a skeleton for the your site:
hugo new site blog
Init a git project and install a theme (as a git submodule):
cd blog # Init git repository git init # Download the theme as a git submodule git submodule add \ https://github.com/budparr/gohugo-theme-ananke.git themes/ananke # Edit your config.toml configuration file # and add the Ananke theme. echo 'theme = "ananke"' >> config.toml # Do not track /public directory in git echo '/public' >> .gitignore
Create a new post and add some content:
hugo new posts/my-first-post.md
Edit the new post
--- title: "My First Post" date: 2019-03-26T08:47:11+01:00 draft: false --- This is my first post
Open up config.toml in a text editor:
baseURL = "https://example.org/" languageCode = "en-us" title = "My New Hugo Site" theme = "ananke"
Preview the site:
Commit your changes and setup your repository:
# In case you created the repository in GitHub already git remote add origin email@example.com:username/blog.git # Add all the skeleton of the site git add . # First commit git commit -m "Initial commit"
Create GitHub bot account
In order to give Travis CI the power to publish the generated site in
username.github.io a GitHub Personal Access Token is needed (or the credentials of the repository owner). The token needs have the
repo scope, therefore it will grant access to all the repositories that the user have permissions, including those from the organization it belongs. It is then a too much powerful access only for publishing a personal site.
If a separate account is used instead, access could be given only to
username.github.io repository. That is more secure.
A trick is to use Gmail email aliases, so an account as
firstname.lastname@example.org be created.
Once the account is created, create a personal access token with repo permissions:
Copy the value of the token to use it later for the Travis CI configuration.
Also add the bot user as a collaborator in
Configure Travis CI
Sign-in in travis-ci.com with your main GitHub account and authorize access to the
In the settings for the repository in Travis CI, configure an environment variable with the name
GITHUB_TOKEN and set the value of the personal access token from the GitHub bot account.
Create travis build
.travis.ymlfile in the root of the
blogrepository with the following configuration (for more information check Travis CI GitHub Pages Deployment):
dist: bionic # Ubuntu distribution language: go # programming language go: - master # This will use the latest version of the language # Install hugo extended using snaps addons: snaps: - name: hugo channel: extended/stable # will be passed to --channel flag script: - hugo # This commands builds your website on travis deploy: provider: pages # GitHub Pages Deployment skip_cleanup: true # prevents delete all the files created during the build that you are trying to upload local_dir: public # Default static site output dir for Hugo repo: username/username.github.io # This is the slug of the repo you want to deploy your site to target_branch: master # Branch to push local_dir contents to, defaults to gh-pages github_token: $GITHUB_TOKEN # Set in the settings page of your repository, as a secure variable keep_history: true # Optional, create incremental commit instead of doing push force, defaults to false email: email@example.com on: branch: master # this is the branch were changes are pushed
git add .travis.yml git commit -m "Adding travis ci automation"
This will trigger a build on Travis CI which in turn will run Hugo to generate the static site. The generated files will be committed and pushed to
username.github.iorepository. Then, finally the site will be available under https://username.github.io.
Now, the workflow for working on the personal site is as simple as working in the
blog repository, committing and pushing content to it, then the content will be transformed and published automatically in GitHub Pages.