Alpha Theme
Alpha Docs
Deployment

Netlify

Author oxypteros

Netlify allows deployment by importing a Git repository from GitHub, GitLab, BitBucket and Azure DevOps or with direct upload .

Deploy on Netlify

After signing up and logging into Netlify:

From the Projects dashboard, choose:

Import from Git

  1. Choose your Git Provider and connect your account.
  2. After authentication, select your Alpha repository from the list.

Set the following:

  1. Project name — This will define your site’s URL: https://[project-name].netlify.app
    1. In your root hugo.toml set
    baseURL = "https://[project-name].netlify.app"
    1. Commit and push the change to the Git Provider
  2. Build command:
    • With search:
    hugo --gc --minify && npx pagefind --site "public"
    • Without search:
    hugo --gc --minify
  • Environment variables ( Add key/value pairs)
    • Key: HUGO_VERSION
    • Value: 0.147.3
      Note: Use a HUGO_VERSION greater than 0.146.1, ideally matching your local version.

Click Deploy [project-name].
Once deployment finishes, click View Deploy Project.

Every push to your Git repository will trigger an automatic deployment.

Deploy Manually with upload

  1. Build your site locally:
    • With Search:
    hugo --gc --minify && npx pagefind --site "public"
    • Without Search:
    hugo --gc --minify
    Note: Pagefind search requires Node.js installed locally.
  2. On the Projects page under …or deploy manually click browse to upload.
  3. Change file type filter from .zip to All files, then upload your built public/ folder.
  4. At the Deploy success! click Get Started
  5. Navigate to Domain Management → Production Domains.
  6. Click Options → Edit Project Name to change the autogenerated name to something personal, then click Save.
  7. Update baseURL in hugo.toml
baseURL = "https://[project-name].netlify.app"

Attention

Netlify auto-assigns a project name after the first upload.
For your Hugo site to work, you must rebuild your site with the correct baseURL and re-upload.

For future deployments:

  1. Build your site locally.
  2. Navigate to Projects → [your project name].
  3. Click Deploys –> browse to upload and re-upload the updated public/ folder.

Netlify File Config & Headers (Optional)

Netlify TOML

Netlify settings can be configured not only from the Netlify dashboard but also from a netlify.toml file placed at the root of your project.

Alpha includes a boilerplate netlify.toml file with two base rules: build.command and build.environment.
You’ll find this file at: themes/alpha/netlify.toml

How to Use

  1. Copy the file from /themes/alpha/netlify.toml to your site’s root directory (not static/, but the actual root of your project).
  2. Customize and expand the configuration as needed for your project.

This file is a starting point. For a complete reference, see the official Netlify netlify.toml documentation.

netlify.toml

Settings defined in netlify.toml override those in the Netlify dashboard.
Alpha recommends using the file only for settings that can’t be configured in the UI.

Custom Headers File

Alpha also includes a _headers file preconfigured for a default Alpha installation, located at: /themes/alpha/static/_headers.

This file allows you to define HTTP headers for Netlify, including security-related ones.

Refer to the official documentation for syntax details, available options, and best practices..

Warning

Some headers (especially related to cross-origin policies or Content Security Policy (CSP)) can break your site or block third-party embeds if misconfigured. Always test your site thoroughly before going live.

How to Use

  1. Copy the _headers file from /themes/alpha/static to your site’s ownstatic/ directory.
  2. Review and customize the rules to match your site’s security and performance needs.
Edit this page on Github