When I started on my YouTube journey, I was excited to produce content about my home lab configuration and share some of the things I’ve learned along the way. However, I wasn’t fully prepared for how many people messaged me about written documentation to go along with the repositories. In hindsight, this is a no-brainer and was also highlighted in the Go Developer Survey 2024 H1 Results, the primary way people learn is through a written document.

So, let’s talk about how I spun-up this website and how you can do the same.

Why Hugo?

I chose Hugo because it’s a static site generator meaning that there is no database or server-side code to run. This makes it very fast and easy to deploy. I also chose this because I have experience managing Hugo documentation sites at work usually using the Docsy theme or the Hugo Book theme. However, those seemed a bit too bland for my personal site. I wanted something that was flashier and had more color (not the norm for me) to it and I ended up choosing the Stack theme.

However, I didn’t end up using the theme as is or at least with their starter repo. Instead, I ended up using the quick-start documentation from Hugo to allow me to customize the theme to my liking.

Initial Configuration

For the initial configuration, I followed the quick-start guide from the Hugo documentation. This allowed me to get a basic site up and running with the stack theme. Using the theme as a submodule allowed me the capability to override the theme’s default layouts and styles with my own. For example, removing the “Built with Hugo” footer and replacing it with my own footer.

If you got this running, you should be able to see the site running locally by running hugo server and navigating to localhost:1313 in your browser.

Customizing the Theme

So, let’s talk about what I did to make everything work as well as it does.

• Copy over the configuration files located in the theme’s starter repo directory to the root of my site. This allows me to take advantage of the parameters that the theme has set up.
  • When you copy these over you will need to also remove the config.toml file that is in the root of the directory. Make sure to modify any of the configurations that you want to change and add theme = 'hugo-theme-stack' to the config.toml file. For me, this included:
  • social media links in the menu.toml file
  • title in the config.toml file
  • sidebar subtitle in the params.toml file
• Find the layout file for the footer and remove the “Built with Hugo” text. This is in the theme’s directory under layouts/partials/footer/footer.html. I copied this file to my site’s directory under layouts/partials/footer/footer.html and removed the text.
  • This allows you to customize the layouts of the theme to your liking without having to modify the theme itself. This can be done with any of the theme’s layouts.
• Finally, for my sanity, I also changed the folder structure of the content directory so that the posts were organized by year, month, and day. This is a personal preference and not necessary for the theme to work.

If you have been following along, this is what your directory structure should look like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

├── archetypes
│   └── default.md
├── assets
│    └── ...
├── config
│   └── _default
│       ├── _languages.toml
│       ├── config.toml
│       ├── markup.toml
│       ├── menu.toml
│       ├── params.toml
│       ├── permalinks.toml
│       └── related.toml
├── content
│   ├── _index.md
│   ├── categories
│   │   └── hugo
│   │       └── _index.md
│   ├── page
│   │   ├── archives
│   │   │   └── index.md
│   │   ├── links
│   │   │   └── index.md
│   │   └── search
│   │       └── index.md
│   └── post
│       ├── 2024
│       │   └── 05
│       │       └── 07
│       │           ├── cover.svg
│       │           ├── index.md
│       │           └── learning_content_exp.svg
├── layouts
│   └── partials
│       └── footer
│           └── footer.html
├── static
│   ├── favicon.png
├── themes
│   └── hugo-theme-stack
│       ├── ...

Comments

Now that your site is up and running and you have customized the theme to your liking, you can add comments to your site. By default, the stack theme uses disqus for comments. You can use this or modify it to use another service by modifying the params.toml file in the root of your site.

1
2
3

[comments]
enabled = true
provider = "disqus"

I switched over to using giscus which is heavily inspired by utterances, but instead uses GitHub discussions instead of issues. I found this to be a bit more user friendly and easier to manage. To do this, I added the following to my params.toml file:

1
2
3

[comments]
enabled = true
provider = "giscus"

and then after completing the setup on the giscus website, I added the filled out the [comments.giscus] section of my params.toml file.

This now allows me to have comments on my site without having to rely on someone showing ads or tracking my users. Also, since disqus sells your data to advertisers, I didn’t want to support that. opt out of disqus data sharing

Sitemap

I also adjusted the default sitemap, the main reason for doing this was to adjust the priority and change frequency of the posts. This is done by creating a new file called sitemap.toml next to your other configuration toml files.

1
2

ChangeFreq = "daily"
Priority = "1"

While you can get way more complex in your setup by generating a custom sitemap.xml file, I found this to be sufficient for my needs at least now. A good write up on how to do this can be found here which is from the Hugo forums. This also talks about the robots.txt file but we will be using http headers on our deployment to handle this.

Deployment

While there are many choices for your hosting provider, GitHub pages, Netlify, and Vercel are just some to name a few. I ended up choosing Cloudflare pages. This might change in the future to a self-hosted container running nginx or lighthttpd, but for now, I’m happy with the performance and the ease of use that Cloudflare pages provides.

Cloudflare pages are completely free and provide a global CDN for your site. This means that your site will be served from the closest datacenter to the user. To deploy to Cloudflare pages, you will need to follow the hugo framework guide from Cloudflare. This will walk you through setting up your site on Cloudflare pages and connecting it to your GitHub repository. Once you have set this up, you can push your changes to your GitHub repository and Cloudflare pages will automatically build and deploy your site.

However, there are a few things that the framework guide doesn’t cover that I had to figure out and tweak to get my site to work the way I wanted it to.

Headers file

By default, Cloudflare will serve your pages with a noindex header. This is to prevent search engines from indexing your site. So, to correct this we will need to create a _headers file in a new directory called Cloudflare in the root of your git repository:

1
2
3
4
5
6
7
8
9

/
  X-Robots-Tag: index, follow

/static/*
  Access-Control-Allow-Origin: *
  X-Robots-Tag: nosnippet

https://myproject.pages.dev/*
  X-Robots-Tag: noindex

Make sure to replace https://myproject.pages.dev/* with your project’s dev URL, if not bots will be able to index your dev site. This can be found in the Cloudflare pages dashboard, underneath the project name and repository name.

Because I have no secure content on my site, I also added the Access-Control-Allow-Origin: * header to allow for cross origin requests.

The reason I put this in a Cloudflare directory is because I have my public directory in my .gitignore file and I don’t want to worry about accidentally committing the locally built files to my repository and instead rely on Cloudflare to build and deploy my site.

This means we will need to modify the build parameters in the Cloudflare pages dashboard, select your site, go to the settings tab. Under the build and deploy section, click on edit configurations in the build configurations section.

1
2

Build Command: hugo -b $CF_PAGES_URL -d ./cloudflare
Build Output Directory: cloudflare

So now when I build locally to view html changes it will go to my git ignored public directory and when I push to GitHub it will build in the Cloudflare directory.

While here, I also removed the preview deployments as I don’t need a development build every time I push to my repository. This is done by setting Configure Preview Deployments to None. This reduces the number of builds you run by half and since your limited to 500 builds a month, this can be important.

Custom Domain

Finally, the last mandatory configuration in my opinion was to set up a custom domain.

• Log in to the Cloudflare dashboard.
• Select your account in Account Home > Workers & Pages.
• Select your Pages project > Custom domains.
• Select Set up a domain.
• Provide the domain that you would like to serve your Cloudflare Pages site on and select Continue.

Since I went the CNAME Route, this was super easy to set up. However, more configurations can be found here.

Cloudflare Web Analytics

Optionally, I also added a web analytics service to my site. Cloudflare Web Analytics provides free, privacy-first analytics for your website without changing your DNS or using Cloudflare’s proxy. This helps you understand the performance of your web pages as experienced by your site visitors.

Cloudflare Pages offers a one-click setup for Web Analytics:

• Log in to Cloudflare dashboard.
• From Account Home, select Workers & Pages.
• In Overview, select your Pages project.
• Go to Manage > Web Analytics > and select Enable Web Analytics. Cloudflare will automatically add the JavaScript snippet to your Pages site on the next deployment.

Conclusion

While this is just a high-level overview and will constantly evolve as I learn more about how I want my site to look and feel, the basics are here, continuous deployment, comments, and analytics and of course a custom domain.

Overall, I am very happy with how the site turned out and how easy it was to get the site up and running on Cloudflare pages.

I hope this article has helped you get your site up and running. If you have any questions or need help, feel free to reach out to me in the comments. I am always happy to help!