How does this website work?

This website is built using Hugo, a powerful and fast static site generator, with the MinimalAlpha theme by me. I chose Hugo for its speed, simplicity, and extensibility, which allows me to experiment and further develop the site as I learn more.

What is Hugo?

Hugo is an open-source static site generator written in Go. It takes content written in Markdown, applies templates, and generates a complete, static website. Hugo is known for its blazing fast build times, flexible configuration, and robust templating system. It excels at handling large amounts of content and can build most sites in seconds.

How Hugo Works?

Hugo uses a combination of layouts, partials, shortcodes, and configuration files to build websites. Here’s a breakdown of key components:

Layouts

Layouts define the HTML structure for different types of pages in your Hugo site.

Types of Layouts

  • Baseof: The master template that wraps around other layouts
  • Single: Used for individual content pages
  • List: For pages that display multiple content items
  • Section: Templates for specific content sections

Layouts are stored in the layouts directory and can be overridden at various levels for granular control.

Partials

Partials are reusable HTML snippets that promote code reuse and maintainability.

Common Uses for Partials

  • Header and footer sections
  • Navigation menus
  • Sidebar components
  • Social media sharing buttons

Partials are stored in the layouts/partials directory and are included in layouts using the following syntax:

{{ partial "name.html" . }}

Shortcodes

Shortcodes extend Markdown’s capabilities by creating custom content snippets.

Benefits of Shortcodes

  • Embed complex HTML structures within Markdown
  • Create reusable content components
  • Implement dynamic functionality

Shortcodes are defined in the layouts/shortcodes directory and used in content files. Here’s an example of how you might use a shortcode in your content:

{{% youtube w7Ft2ymGmfc %}}

Site and Page Variables

Hugo provides variables for inserting dynamic content into templates and pages.

Types of Variables

  • Site Variables: Global information (e.g., {{ .Site.Title }})
  • Page Variables: Specific to individual pages (e.g., {{ .Title }})
  • Custom Variables: Defined in front matter or configuration files

Styling

While Hugo focuses on structure and content, styling is typically handled through CSS files.

Styling Best Practices

  • Use CSS frameworks judiciously
  • Implement responsive design principles
  • Optimize CSS for performance

CSS files are usually placed in the static/css directory of your theme or site.

Configuration

The config.toml file (or YAML/JSON equivalent) serves as the central configuration for your Hugo site.

Key Configuration Areas

  • Basic site information (title, language, etc.)
  • Content management settings
  • Theme selection and customization
  • Build options and parameters

Example config.toml:

baseURL = "https://example.org/"
languageCode = "en-us"
title = "My Hugo Site"
theme = "my-theme"

Creating a Hugo Website

Here’s a step-by-step guide to creating a Hugo website:

  1. Install Hugo on your system
  2. Create a new site: hugo new site sitename
  3. Navigate to the site directory: cd sitename
  4. Edit the configuration file: nano hugo.toml
  5. Add a theme and basic configuration
  6. Start writing content in the content folder
  7. Preview your site locally: hugo serve
  8. Visit http://localhost:1313 to see your website

Remember, mastering Hugo requires some trial and error. It may seem complex at first, but with time and practice, it becomes easier to understand and utilize its features effectively.

Hugo Build Process

When you run the hugo command, here’s what happens:

  1. Hugo reads the configuration file
  2. It processes the content files (Markdown, etc.)
  3. The appropriate layouts are selected based on content type and section
  4. Partials and shortcodes are integrated
  5. Variables are populated with actual content
  6. The final HTML is generated
  7. Static assets (CSS, JavaScript, images) are copied to the output directory

The result is a fully static website that can be deployed to any web server or hosting platform.

Deployment Options

There are several ways to deploy a Hugo site. Here are three popular options:

1. GitHub Pages

Hugo provides excellent documentation for deploying to GitHub Pages. This method involves pushing your Hugo project to a GitHub repository and using GitHub Actions to build and deploy your site automatically.

2. Cloudflare Pages

To deploy on Cloudflare Pages:

  1. Install Wrangler CLI: sudo npm -i g wrangler
  2. Authenticate: Run wrangler login
  3. Build your Hugo site: Run hugo in your site directory
  4. Deploy: Run wrangler pages publish public inside your Hugo site directory

Note: I encountered an issue where the CSS was loading correctly on the Cloudflare-provided *.pages.dev domain, but not on my custom domain. This led me to explore other deployment options.

3. Vercel (My Chosen Method)

For Vercel deployment:

  1. Install Vercel CLI: sudo npm i -g vercel
  2. Navigate to your Hugo site directory
  3. Run vercel and follow the prompts
  4. Your site will be deployed to a project.vercel.app domain

To use a custom domain with Vercel:

  1. Go to the Vercel dashboard and add your domain
  2. If you already own the domain, you’ll need to add Vercel nameservers to your domain registrar
  3. Wait a few hours for DNS propagation
  4. Your site should now be live on your custom domain