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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
---
title: Basic usage
linktitle: Basic usage
description: Hugo's command line interface (CLI) is fully featured but simple to use, even for those with limited experience working from the command line.
categories: [getting started]
keywords: [usage,livereload,command,flags]
menu:
docs:
parent: "getting-started"
weight: 40
weight: 40
sections_weight: 40
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
toc: true
---
## Test your installation
After [installing] Hugo, test your installation by running:
```bash
hugo version
```
You should see something like:
```text
hugo v0.105.0-0e3b42b4a9bdeb4d866210819fc6ddcf51582ffa+extended linux/amd64 BuildDate=2022-10-28T12:29:05Z VendorInfo=snap:0.105.0
```
## Display available commands
To see a list of the available commands and flags:
```bash
hugo help
```
To get help with a subcommand, use the `--help` flag. For example:
```bash
hugo server --help
```
## Build your site
To build your site, `cd` into your project directory and run:
```bash
hugo
```
The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration.
{{% note %}}
Hugo does not clear the `public` directory before building your site. 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.
{{% /note %}}
## 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
You can override the default behavior when running `hugo` or `hugo server` with command line flags:
```bash
hugo --buildDrafts # or -D
hugo --buildExpired # or -E
hugo --buildFuture # or -F
```
Although you can also set these values in your site 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 site. 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.
{{% /note %}}
## Develop and test your site
To view your site while developing layouts or creating content, `cd` into your project directory and run:
```bash
hugo server
```
The [`hugo server`] command builds your site into memory, and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
```text
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:
```bash
hugo server --navigateToChanged
```
## Deploy your site
{{% note %}}
As noted above, Hugo does not clear the public directory before building your site. Manually clear the contents of the public directory before each build to remove draft, expired, and future content.
{{% /note %}}
When are ready to deploy your site, run:
```bash
hugo
```
This builds your site, publishing the files to the public directory. The directory structure will look something like this:
```text
public/
├── categories/
│ ├── index.html
│ └── index.xml <-- RSS feed for this section
├── post/
│ ├── 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 using a CI/CD workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify].
Learn more in the [hosting and deployment] section.
[^1]: The Git repository contains the entire project directory, typically excluding the public directory because the site is built _after_ the push.
[`--destination`]: /commands/hugo/#options
[`hugo server`]: /commands/hugo_server/
[`hugo`]: /commands/hugo/
[`publishDir`]: /getting-started/configuration/#publishdir
[AWS Amplify]: https://aws.amazon.com/amplify/
[CloudCannon]: https://cloudcannon.com/
[Cloudflare Pages]: https://pages.cloudflare.com/
[commands]: /commands/
[front matter]: /content-management/front-matter/
[GitHub Pages]: https://pages.github.com/
[GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/
[hosting and deployment]: /hosting-and-deployment/
[hosting]: /hosting-and-deployment/
[installing]: /installation/
[LiveReload]: https://github.com/livereload/livereload-js
[Netlify]: https://www.netlify.com/
|
