github.com/lyeb/hugo@v0.47.1/docs/content/en/getting-started/usage.md (about) 1 --- 2 title: Basic Usage 3 linktitle: Basic Usage 4 description: Hugo's CLI is fully featured but simple to use, even for those who have very limited experience working from the command line. 5 date: 2017-02-01 6 publishdate: 2017-02-01 7 lastmod: 2017-02-01 8 categories: [getting started] 9 keywords: [usage,livereload,command line,flags] 10 menu: 11 docs: 12 parent: "getting-started" 13 weight: 40 14 weight: 40 15 sections_weight: 40 16 draft: false 17 aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/] 18 toc: true 19 --- 20 21 The following is a description of the most common commands you will use while developing your Hugo project. See the [Command Line Reference][commands] for a comprehensive view of Hugo's CLI. 22 23 ## Test Installation 24 25 Once you have [installed Hugo][install], make sure it is in your `PATH`. You can test that Hugo has been installed correctly via the `help` command: 26 27 ``` 28 hugo help 29 ``` 30 31 The output you see in your console should be similar to the following: 32 33 ``` 34 hugo is the main command, used to build your Hugo site. 35 36 Hugo is a Fast and Flexible Static Site Generator 37 built with love by spf13 and friends in Go. 38 39 Complete documentation is available at http://gohugo.io/. 40 41 Usage: 42 hugo [flags] 43 hugo [command] 44 45 Available Commands: 46 benchmark Benchmark Hugo by building a site a number of times. 47 check Contains some verification checks 48 config Print the site configuration 49 convert Convert your content to different formats 50 env Print Hugo version and environment info 51 gen A collection of several useful generators. 52 help Help about any command 53 import Import your site from others. 54 list Listing out various types of content 55 new Create new content for your site 56 server A high performance webserver 57 version Print the version number of Hugo 58 59 Flags: 60 -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ 61 -D, --buildDrafts include content marked as draft 62 -E, --buildExpired include expired content 63 -F, --buildFuture include content with publishdate in the future 64 --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ 65 --canonifyURLs (deprecated) if true, all relative URLs will be canonicalized using baseURL 66 --cleanDestinationDir remove files from destination not found in static directories 67 --config string config file (default is path/config.yaml|json|toml) 68 -c, --contentDir string filesystem path to content directory 69 --debug debug output 70 -d, --destination string filesystem path to write files to 71 --disableKinds stringSlice disable different kind of pages (home, RSS etc.) 72 --enableGitInfo add Git revision, date and author info to the pages 73 --forceSyncStatic copy all files when static is changed. 74 --gc enable to run some cleanup tasks (remove unused cache files) after the build 75 -h, --help help for hugo 76 --i18n-warnings print missing translations 77 --ignoreCache ignores the cache directory 78 -l, --layoutDir string filesystem path to layout directory 79 --log enable Logging 80 --logFile string log File path (if set, logging enabled automatically) 81 --noChmod don't sync permission mode of files 82 --noTimes don't sync modification time of files 83 --pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true) 84 --preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") 85 --quiet build in quiet mode 86 --renderToMemory render to memory (only useful for benchmark testing) 87 -s, --source string filesystem path to read files relative from 88 --stepAnalysis display memory and timing of different steps of the program 89 --templateMetrics display metrics about template executions 90 --templateMetricsHints calculate some improvement hints when combined with --templateMetrics 91 -t, --theme string theme to use (located in /themes/THEMENAME/) 92 --themesDir string filesystem path to themes directory 93 --uglyURLs (deprecated) if true, use /filename.html instead of /filename/ 94 -v, --verbose verbose output 95 --verboseLog verbose logging 96 -w, --watch watch filesystem for changes and recreate as needed 97 98 Use "hugo [command] --help" for more information about a command. 99 ``` 100 101 ## The `hugo` Command 102 103 The most common usage is probably to run `hugo` with your current directory being the input directory. 104 105 This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field. 106 107 The command `hugo` renders your site into `public/` dir and is ready to be deployed to your web server: 108 109 ``` 110 hugo 111 0 draft content 112 0 future content 113 99 pages created 114 0 paginator pages created 115 16 tags created 116 0 groups created 117 in 90 ms 118 ``` 119 120 ## Draft, Future, and Expired Content 121 122 Hugo allows you to set `draft`, `publishdate`, and even `expirydate` in your content's [front matter][]. By default, Hugo will not publish: 123 124 1. Content with a future `publishdate` value 125 2. Content with `draft: true` status 126 3. Content with a past `expirydate` value 127 128 All three of these can be overridden during both local development *and* deployment by adding the following flags to `hugo` and `hugo server`, respectively, or by changing the boolean values assigned to the fields of the same name (without `--`) in your [configuration][config]: 129 130 1. `--buildFuture` 131 2. `--buildDrafts` 132 3. `--buildExpired` 133 134 ## LiveReload 135 136 Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server with the `hugo server` command and watch for changes: 137 138 ``` 139 hugo server 140 0 draft content 141 0 future content 142 99 pages created 143 0 paginator pages created 144 16 tags created 145 0 groups created 146 in 120 ms 147 Watching for changes in /Users/yourname/sites/yourhugosite/{data,content,layouts,static} 148 Serving pages from /Users/yourname/sites/yourhugosite/public 149 Web Server is available at http://localhost:1313/ 150 Press Ctrl+C to stop 151 ``` 152 153 This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following areas of your [project organization][dirs]: 154 155 * `/static/*` 156 * `/content/*` 157 * `/data/*` 158 * `/i18n/*` 159 * `/layouts/*` 160 * `/themes/<CURRENT-THEME>/*` 161 * `config` 162 163 Whenever you make changes, Hugo will simultaneously rebuild the site and continue to serve content. As soon as the build is finished, LiveReload tells the browser to silently reload the page. 164 165 Most Hugo builds are so fast that you may not notice the change unless looking directly at the site in your browser. This means that keeping the site open on a second monitor (or another half of your current monitor) allows you to see the most up-to-date version of your website without the need to leave your text editor. 166 167 {{% note "Closing `</body>` Tag"%}} 168 Hugo injects the LiveReload `<script>` before the closing `</body>` in your templates and will therefore not work if this tag is not present.. 169 {{% /note %}} 170 171 ### Disable LiveReload 172 173 LiveReload works by injecting JavaScript into the pages Hugo generates. The script creates a connection from the browser's web socket client to the Hugo web socket server. 174 175 LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. The following methods make it easy to disable LiveReload: 176 177 ``` 178 hugo server --watch=false 179 ``` 180 181 Or... 182 183 ``` 184 hugo server --disableLiveReload 185 ``` 186 187 The latter flag can be omitted by adding the following key-value to your `config.toml` or `config.yml` file, respectively: 188 189 ``` 190 disableLiveReload = true 191 ``` 192 193 ``` 194 disableLiveReload: true 195 ``` 196 197 ## Deploy Your Website 198 199 After running `hugo server` for local web development, you need to do a final `hugo` run *without the `server` part of the command* to rebuild your site. You may then deploy your site by copying the `public/` directory to your production web server. 200 201 Since Hugo generates a static website, your site can be hosted *anywhere* using any web server. See [Hosting and Deployment][hosting] for methods for hosting and automating deployments contributed by the Hugo community. 202 203 {{% warning "Generated Files are **NOT** Removed on Site Build" %}} 204 Running `hugo` *does not* remove generated files before building. This means that you should delete your `public/` directory (or the publish directory you specified via flag or configuration file) before running the `hugo` command. If you do not remove these files, you run the risk of the wrong files (e.g., drafts or future posts) being left in the generated site. 205 {{% /warning %}} 206 207 ### Dev vs Deploy Destinations 208 209 Hugo does not remove generated files before building. An easy workaround is to use different directories for development and production. 210 211 To start a server that builds draft content (helpful for editing), you can specify a different destination; e.g., a `dev/` directory: 212 213 ``` 214 hugo server -wDs ~/Code/hugo/docs -d dev 215 ``` 216 217 When the content is ready for publishing, use the default `public/` dir: 218 219 ``` 220 hugo -s ~/Code/hugo/docs 221 ``` 222 223 This prevents draft content from accidentally becoming available. 224 225 [commands]: /commands/ 226 [config]: /getting-started/configuration/ 227 [dirs]: /getting-started/directory-structure/ 228 [front matter]: /content-management/front-matter/ 229 [hosting]: /hosting-and-deployment/ 230 [install]: /getting-started/installing/