DEV Community

Cover image for Create and Deploy your portfolio with Hugo!

Create and Deploy your portfolio with Hugo!

Yeganathan S
An engineer who loves to design and develop things...
・Updated on ・6 min read

Hello everyone πŸ‘‹πŸ»

Have you just thought of making a portfolio or any static site then you're in the right place. In this article, I'm gonna share my experience ( also experiment ) with Hugo.

But before getting into it, let me give a brief introduction about Hugo...

What is Hugo?

Hugo is a general-purpose website framework. Technically speaking, Hugo is a static site generator. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website’s end users and an ideal writing experience for website authors.

What we are going to do?

We're gonna take a theme and customize as per our needs and deploy it on Github pages.

Why Github pages?

This is one of the easiest and simplest way of all. But still, we can also do the same in any other services like Netlify, Heroku and etc.

Prerequisites πŸš€

  • Hugo and Git should be installed. if you didn't install it yet, then check out the following links.

[1] - Installation of Hugo
[2] - Installation of Git

  • A Github account and knowledge of basic git commands.

To make it simple, I have made this blog into step by step process just like farming πŸ€

Let's start making wonders with Hugo πŸŽ‰

Preparation of soil πŸͺ΅

The best part of Hugo is, we can take a theme and pretty much work on it just like a word doc. so I have chosen a template already if u didn't yet, then go and find one for yourself here.

This is the template I have chosen for today's demo Hello-friend-ng πŸ’

Sneak peek of it 🀩



Github pages can't render Hugo files directly so we will be creating 2️⃣ repositories. Once we complete making changes in the template, Hugo helps us to generate static files. The reason for the 2️⃣ repositories is that one is used for Hugo files and the other for static files generated out of it.

Hope you have installed Hugo & git already, now it's time to fire up your terminal.

Type the following command,

$ hugo new site quickstart
Enter fullscreen mode Exit fullscreen mode

quickstart - it's just a directory name the files will be created.
After doing the same now, if you check out the quickstart directory you will be seeing some files/folders. Those are necessary files required for any hugo site and hugo generates those for us.

Now let's move into the quickstart directory and import the theme,

$ cd quickstart
$ git init
$ git submodule add <them_github_repo_link>
Enter fullscreen mode Exit fullscreen mode

Note: An empty git repository is initialized inside the quickstart directory so that we can add the theme as a submodule.

Now when you check the themes directory you will be seeing all those files of our theme.

Sowing βš™οΈ

There will be an examplesite folder inside the themes directory, copy and replace all the contents of examplesite under project directory ( or outside of themes directory )

Alt Text

When it comes to hugo, config.toml is the main file for our site.

Alt Text

Look at the config.toml file and change the necessary details in it except the baseURL.

We can find a description/comments of each variable inside the config.toml so that we can make changes without messing up with the other things.

baseURL = "localhost"
Enter fullscreen mode Exit fullscreen mode

baseURL should be always localhost before deployment.

Prototype πŸ”«

Shoot up the terminal now...

$ hugo server
Start building sites … 

                   | EN | FR  
  Pages            | 35 | 21  
  Paginator pages  |  0 |  0  
  Non-page files   |  0 |  0  
  Static files     | 12 | 12  
  Processed images |  0 |  0  
  Aliases          | 18 |  7  
  Sitemaps         |  2 |  1  
  Cleaned          |  0 |  0  

Built in 65 ms
Watching for changes in /Users/yeganathan/quickstart/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /Users/yeganathan/quickstart/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
Press Ctrl+C to stop
Enter fullscreen mode Exit fullscreen mode

Open a browser and enter the webserver address (localhost) to see the changes made. We can also make changes/ add content once we start our live local server and see the result instantly, this makes it even easier since we can see the result once we save our file with each change made.

We can also edit the core components of the theme by editing the required file for the required component inside the themes directory.

Adding manure and fertilizers 🌱

We can also add few more components other than in the theme...

For instance,

If we need an extra menu (Photography) apart from the one given in the theme, we can easily make one by editing the config.toml

    identifier = "about"
    name       = "About"
    url        = "about/"
    identifier = "posts"
    name       = "Posts"
    url        = "posts/"
    identifier = "photography"
    name       = "Photography"
    url        = "photography/"
Enter fullscreen mode Exit fullscreen mode

also, the contents of the page can be added to the content directory same as posts.

Alt Text

Basically, we can add anything that we want on our site. Just go around the files and start doing wonders ✨

Irrigation πŸ“¦

So for we made changes to our site and the files are only in our local system, in order to deploy in web it should be stored in remote right!? here comes Github.

As said already we need 2️⃣ repos for our hugo site.

Create your 2️⃣ remote repos on Github, one as [username] and the other as quickstart.

⚠️ Remember ⚠️
The quickstart is nothing but the project_name we can always use anything of our own but keep in mind that it should be uniform throughout the process.

when creating [username] repo always includes file .gitignore so that it won't shoot an error.

Inside the .gitignore file,

Enter fullscreen mode Exit fullscreen mode

Write the following commands in terminal...

$ git remote add origin<github_username>/quickstart.git
$ git add .
$ git commit -m "Initial commit for our Hugo site."
$ git submodule add<github_username>/<github_username>
$ git add .
$ git commit -m "Initial commit for our generated HTML."
$ git push -u origin master
Enter fullscreen mode Exit fullscreen mode

this only pushes to quickstart repo.

We still need to generate our HTML pages for our [github_username] repo, but before generating we need to change our config.toml file to output our HTML files to our submodule [github_usernam]

Open your config.toml

Alt Text

Change these things to as shown below...

Alt Text

Hugo already has a built-in command, that generates your files to a Public folder.

Let’s generate them by running the following command,

$ hugo
Start building sites … 

                   | EN | FR  
  Pages            | 35 | 21  
  Paginator pages  |  0 |  0  
  Non-page files   |  0 |  0  
  Static files     | 12 | 12  
  Processed images |  0 |  0  
  Aliases          | 18 |  7  
  Sitemaps         |  2 |  1  
  Cleaned          |  0 |  0  

Total in 136 ms
Enter fullscreen mode Exit fullscreen mode

And that should be it. If you look in your [github_username] folder now you should see HTML and CSS files, stuff that Github pages understand❗️

Alt Text

Before we finally deploy, we need to make sure our remotes are set up correctly.

$ cd <github_username>
$ git remote -v
> origin<github_username>/<github_username> (fetch)
> origin<github_username>/<github_username> (push)
Enter fullscreen mode Exit fullscreen mode

Now after doing the above, you should probably see the same fetch and push.

Harvesting 🌾

We are gonna push all those generated HTML and CSS files to [github_username] repo

Once again make sure your inside [github_username] directory in the terminal...

Now let’s host it!

git add .
git commit -m "Hosting my first Hugo website!"
git push origin main
Enter fullscreen mode Exit fullscreen mode

Now go and check the [github_username] repo

Alt Text

you will see Github pages in the repo, click that

Alt Text

If your deployment didn't show up wait for a couple of minutes and reload the same.

Finally, we hosted our first Hugo site πŸ₯³

Feel free to check out πŸ‘‰πŸ» my portfolio πŸ‘ˆπŸ»

Do Like πŸ‘ and follow for more interesting blogs πŸ‘¨πŸ»β€πŸ’»
Comment you're valuable feedbacks down ✌️

Discussion (4)

gautamgk profile image

Attractive, informative and interesting ❀️
Great work Bro πŸ”₯

yeganathan18 profile image
Yeganathan S Author

Thank you ;)

jalopy profile image
Ananthakrishnan K M

great <3

yeganathan18 profile image
Yeganathan S Author

Thanks da :)