hugo/content/en/getting-started/usage.md

title, description, categories, keywords, weight, aliases

title	description	categories	keywords	weight	aliases
Basic usage	Use the command-line interface (CLI) to perform basic tasks.			20	/overview/usage/ /extras/livereload/ /doc/usage/ /usage/

Test your installation

After installing Hugo, test your installation by running:

hugo version

Display available commands

To see a list of the available commands and flags:

hugo help

To get help with a subcommand, use the --help flag. For example:

hugo server --help

Build your project

To build your project, cd into your project directory and run:

hugo build

The hugo build command builds your project, publishing the files to the public directory. To publish your project to a different directory, use the --destination flag or set publishDir in your project configuration.

Note

Hugo does not clear the public directory before building your project. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the public directory after the build.

Depending on your needs, you may wish to manually clear the contents of the public directory before every build.

Draft, future, and expired content

Hugo allows you to set draft, date, publishDate, and expiryDate in the front matter of your content. By default, Hugo will not publish content when:

• The draft value is true
• The date is in the future
• The publishDate is in the future
• The expiryDate is in the past

Note

Hugo publishes descendants of draft, future, and expired node pages. To prevent publication of these descendants, use the cascade front matter field to cascade build options to the descendant pages.

You can override the default behavior when running hugo build or hugo server with command line flags:

hugo build --buildDrafts    # or -D
hugo build --buildExpired   # or -E
hugo build --buildFuture    # or -F

Although you can also set these values in your project configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.

Note

As noted above, Hugo does not clear the public directory before building your project. Depending on the current evaluation of the four conditions above, after the build your public directory may contain extraneous files from a previous build.

A common practice is to manually clear the contents of the public directory before each build to remove draft, expired, and future content.

Develop and test your site

To view your site while developing layouts or creating content, cd into your project directory and run:

hugo server

The hugo server command builds your site and serves your pages using a minimal HTTP server. When you run hugo server it will display the URL of your local site:

Web Server is available at http://localhost:1313/ 

While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using LiveReload.

Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.

LiveReload

While the server is running, Hugo injects JavaScript into the generated HTML pages. The LiveReload script creates a connection from the browser to the server via web sockets. You do not need to install any software or browser plugins, nor is any configuration required.

Automatic redirection

When editing content, if you want your browser to automatically redirect to the page you last modified, run:

hugo server --navigateToChanged

Deploy your site

Note

As noted above, Hugo does not clear the public directory before building your project. Manually clear the contents of the public directory before each build to remove draft, expired, and future content.

When you are ready to deploy your site, run:

hugo

This builds your site, publishing the files to the public directory. The directory structure will look something like this:

public/
├── categories/
│   ├── index.html
│   └── index.xml  <-- RSS feed for this section
├── posts/
│   ├── my-first-post/
│   │   └── index.html
│   ├── index.html
│   └── index.xml  <-- RSS feed for this section
├── tags/
│   ├── index.html
│   └── index.xml  <-- RSS feed for this section
├── index.html
├── index.xml      <-- RSS feed for the site
└── sitemap.xml

In a simple hosting environment, where you typically ftp, rsync, or scp your files to the root of a virtual host, the contents of the public directory are all that you need.

Most of our users deploy their sites to a CI/CD platform, where a push¹ to their remote Git repository triggers a build and deployment. Learn more in the host and deploy section.

---

1. The Git repository contains the entire project directory, typically excluding the public directory because the site is built after the push. ↩︎