usage.md - hugo - [fork] hugo port for 9front
HTML git clone https://git.drkhsh.at/hugo.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
usage.md (6279B)
---
1 ---
2 title: Basic usage
3 description: Use the command-line interface (CLI) to perform basic tasks.
4 categories: []
5 keywords: []
6 weight: 20
7 aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
8 ---
9
10 ## Test your installation
11
12 After [installing] Hugo, test your installation by running:
13
14 ```sh
15 hugo version
16 ```
17
18 You should see something like:
19
20 ```text
21 hugo v0.123.0-3c8a4713908e48e6523f058ca126710397aa4ed5+extended linux/amd64 BuildDate=2024-02-19T16:32:38Z VendorInfo=gohugoio
22 ```
23
24 ## Display available commands
25
26 To see a list of the available commands and flags:
27
28 ```sh
29 hugo help
30 ```
31
32 To get help with a subcommand, use the `--help` flag. For example:
33
34 ```sh
35 hugo server --help
36 ```
37
38 ## Build your site
39
40 To build your site, `cd` into your project directory and run:
41
42 ```sh
43 hugo
44 ```
45
46 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.
47
48 > [!note]
49 > 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.
50 >
51 > Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build.
52
53 ## Draft, future, and expired content
54
55 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:
56
57 - The `draft` value is `true`
58 - The `date` is in the future
59 - The `publishDate` is in the future
60 - The `expiryDate` is in the past
61
62 {{< new-in 0.123.0 />}}
63
64 > [!note]
65 > Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
66
67 You can override the default behavior when running `hugo` or `hugo server` with command line flags:
68
69 ```sh
70 hugo --buildDrafts # or -D
71 hugo --buildExpired # or -E
72 hugo --buildFuture # or -F
73 ```
74
75 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.
76
77 > [!note]
78 > 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.
79 >
80 > A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
81
82 ## Develop and test your site
83
84 To view your site while developing layouts or creating content, `cd` into your project directory and run:
85
86 ```sh
87 hugo server
88 ```
89
90 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:
91
92 ```text
93 Web Server is available at http://localhost:1313/
94 ```
95
96 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].
97
98 Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.
99
100 ### LiveReload
101
102 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.
103
104 ### Automatic redirection
105
106 When editing content, if you want your browser to automatically redirect to the page you last modified, run:
107
108 ```sh
109 hugo server --navigateToChanged
110 ```
111
112 ## Deploy your site
113
114 > [!note]
115 > 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.
116
117 When you are ready to deploy your site, run:
118
119 ```sh
120 hugo
121 ```
122
123 This builds your site, publishing the files to the `public` directory. The directory structure will look something like this:
124
125 ```text
126 public/
127 ├── categories/
128 │ ├── index.html
129 │ └── index.xml <-- RSS feed for this section
130 ├── posts/
131 │ ├── my-first-post/
132 │ │ └── index.html
133 │ ├── index.html
134 │ └── index.xml <-- RSS feed for this section
135 ├── tags/
136 │ ├── index.html
137 │ └── index.xml <-- RSS feed for this section
138 ├── index.html
139 ├── index.xml <-- RSS feed for the site
140 └── sitemap.xml
141 ```
142
143 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.
144
145 Most of our users deploy their sites using a [CI/CD](g) 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].
146
147 Learn more in the [host and deploy] section.
148
149 [^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push.
150
151 [`--destination`]: /commands/hugo/#options
152 [`cascade`]: /content-management/front-matter/#cascade
153 [`hugo server`]: /commands/hugo_server/
154 [`hugo`]: /commands/hugo/
155 [`publishDir`]: /configuration/all/#publishdir
156 [AWS Amplify]: https://aws.amazon.com/amplify/
157 [build options]: /content-management/build-options/
158 [CloudCannon]: https://cloudcannon.com/
159 [Cloudflare Pages]: https://pages.cloudflare.com/
160 [front matter]: /content-management/front-matter/
161 [GitHub Pages]: https://pages.github.com/
162 [GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/
163 [host and deploy]: /host-and-deploy/
164 [installing]: /installation/
165 [LiveReload]: https://github.com/livereload/livereload-js
166 [Netlify]: https://www.netlify.com/