Creating a Site

This page explains how to create a new site with Hugo and start the local development server.

Create a Project Link to this heading

hugo new project my-site --format yaml
cd my-site

hugo new project creates the basic directory structure. At this point, the site has no theme or content yet.

Installing a Theme Link to this heading

Choosing an Installation Method

The Git submodule approach does not require Go, but it does require solid Git experience to use correctly. If you are not comfortable with Git, hugo-community-docs strongly recommends using Hugo modules instead.

Hugo modules, by contrast, keep the commands simple. Updating or downgrading is just hugo mod get. The same tasks take multiple commands with Git submodules.

The recommended approach. It is a Go module under the hood. Using Ananke (external link) as an example:

git init
hugo mod init github.com/your-username/my-site  # or hugo mod init my-project

git init initializes the directory as a Git repository, letting you track your project's change history. hugo mod init initializes your project as a Go module.

Then add this to hugo.yaml.

hugo.yaml

module:
  imports:
    - path: github.com/gohugo-ananke/ananke/v2

Not recommended. Using Ananke (external link) as an example:

git init
git submodule add https://github.com/gohugo-ananke/ananke.git themes/ananke

git init sets up a Git repository, which is required before adding a submodule. git submodule add clones the theme into themes/ananke as a separate, linked repository.

Then add this to hugo.yaml.

theme: ["ananke"]

Start the Development Server Link to this heading

First, add a few content files:

hugo new content _index.md                  # homepage
hugo new content posts/_index.md            # post list page
hugo new content posts/article-1/index.md   # standalone post
hugo new content posts/article-2/index.md   # standalone post
hugo new content posts/article-3/index.md   # standalone post

This creates the corresponding files in the content directory. Then, start the server:

hugo server -DEF

By default, the site runs at http://localhost:1313. The browser refreshes automatically when you save a file. Press Ctrl + C to stop the server.

Pages not found?

Hugo skips draft, expired, and future-dated posts by default. If a post is missing, check these three flags first:

-D builds draft posts, controlled by the draft (external link) field in front matter
-E builds expired posts, controlled by the expiryDate (external link) field in front matter
-F builds future posts, controlled by the date field in front matter

To avoid the draft issue entirely, remove draft from archetypes/default.md, the file that sets the default content for hugo new content.

Build the Production Site Link to this heading

hugo

The build output goes to public/, which you can deploy directly to any static site hosting service.

Tip: gitignore

Auto-generated files are regenerated on every run, so tracking them serves no purpose and they shouldn't be tracked by version control. Add a .gitignore file in the project root to ignore them:

# Hugo
/public/
/resources/_gen/
/exampleSite/public/
/exampleSite/resources/
jsconfig.json
hugo_stats.json
.hugo_build.lock

# System
.DS_Store
.tmp*

# JS
node_modules