hugo/docs/content/overview/usage.md

---
aliases:
- /doc/usage/
date: 2013-07-01
menu:
  main:
    parent: getting started
next: /overview/configuration
notoc: true
prev: /overview/installing
title: Using Hugo
weight: 30
---

Make sure either `hugo` is in your `PATH` or provide a path to it.

    $ hugo help
    A Fast and Flexible Static Site Generator
    built with love by spf13 and friends in Go.

    Complete documentation is available at http://gohugo.io

    Usage:
      hugo [flags]
      hugo [command]

    Available Commands:
      server                    Hugo runs its own webserver to render the files
      version                   Print the version number of Hugo
      check                     Check content in the source directory
      benchmark                 Benchmark hugo by building a site a number of times
      new [path]                Create new content for your site
      help [command]            Help about any command

     Available Flags:
      -b, --baseUrl="": hostname (and path) to the root eg. http://spf13.com/
      -D, --buildDrafts=false: build content marked as draft
      -F, --buildFuture=false: build content with PublishDate in the future
          --config="": config file (default is path/config.yaml|json|toml)
      -d, --destination="": filesystem path to write files to
          --disableRSS=false: Do not build RSS files
          --disableSitemap=false: Do not build Sitemap file
          --log=false: Enable Logging
          --logFile="": Log File path (if set, logging enabled automatically)
      -s, --source="": filesystem path to read files relative from
          --stepAnalysis=false: display memory and timing of different steps of the program
      -t, --theme="": theme to use (located in /themes/THEMENAME/)
          --uglyUrls=false: if true, use /filename.html instead of /filename/
      -v, --verbose=false: verbose output
          --verboseLog=false: verbose logging
      -w, --watch=false: watch filesystem for changes and recreate as needed

    Use "hugo help [command]" for more information about that command.

## Common Usage Example

The most common use is probably to run `hugo` with your current directory being the input directory.

    $ hugo
    > X pages created
      in 8 ms

If you are working on things and want to see the changes immediately, tell Hugo to watch for changes.

Hugo will watch the filesystem for changes, rebuild your site as soon as a file is saved.

    $ hugo -s ~/mysite --watch
       28 pages created
       in 18 ms
       Watching for changes in /Users/spf13/Code/hugo/docs/content
       Press Ctrl+C to stop

Hugo can even run a server and create a site preview at the same time! Hugo
implements [LiveReload](/extras/livereload/) technology to automatically reload any open pages in all browsers (including mobile). (Note that you'll need to run without -w before you deploy your site.)

    $ hugo server -ws ~/mysite
       Watching for changes in /Users/spf13/Code/hugo/docs/content
       Web Server is available at http://localhost:1313
       Press Ctrl+C to stop
       28 pages created
       0 tags created
       in 18 ms
sanity: move from json to yaml 2013-07-06 23:36:30 +00:00			`---`
Converting front matter to YAML 2014-05-29 22:42:05 +00:00			`aliases:`
			`- /doc/usage/`
			`date: 2013-07-01`
Implementing new menu system in the docs site 2014-04-23 07:00:11 +00:00			`menu:`
			`main:`
Converting front matter to YAML 2014-05-29 22:42:05 +00:00			`parent: getting started`
			`next: /overview/configuration`
			`notoc: true`
			`prev: /overview/installing`
			`title: Using Hugo`
			`weight: 30`
YAML support similar to jekyll (start and end with '---') 2013-07-08 21:57:01 +00:00			`---`
adding hugo 2013-07-04 15:32:55 +00:00
Some more random copyediting of Hugo docs - Change "livereload" and "live reload" to "LiveReload"; - Add a `$ ` prompt before example command lines (not exhaustive, work in progress); - Remove unnecessary whitespace from partials; - Revise the blackfriday options table in overview/configuration.md to make it narrower. - Manually set the language for highlight.js where appropriate - Rename "404" to "Custom 404 page", and remove incorrect reference to "homepage" - Credit the author of tutorials/github_pages_blog.md (Similar notes are necessary for other contributed pages where "I" am not spf13 to avoid reader confusion.) - Add CSS for `kbd` and `table` etc. to css/style.css; - etc. 2015-01-09 18:51:15 +00:00			Make sure either `hugo` is in your `PATH` or provide a path to it.
Updating / Rewriting / Adding all of the documentation in preparation for the next release 2014-05-27 22:32:57 +00:00
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00			`$ hugo help`
			`A Fast and Flexible Static Site Generator`
			`built with love by spf13 and friends in Go.`

Switch to new hompage 2014-09-27 07:35:42 +00:00			`Complete documentation is available at http://gohugo.io`
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00
			`Usage:`
			`hugo [flags]`
			`hugo [command]`

			`Available Commands:`
Minor proofreading corrections to Hugo docs - Add backticks and commas where necessary - Remove some trailing whitespace - Add front matter example in TOML - Fix typo in one of the tags in Showcase - Add 多说 (Duoshuo) as an alternative to Disqus - Use internal links (i.e. without gohugo.io) where possible - Use a colon to set off an example - Change "it's" to "its" where appropriate - Use typographical (i.e. curly) apostrophe on the front page where appropriate - Capitalize "Github" as "GitHub" 2014-10-07 23:52:58 +00:00			`server Hugo runs its own webserver to render the files`
			`version Print the version number of Hugo`
			`check Check content in the source directory`
			`benchmark Benchmark hugo by building a site a number of times`
			`new [path] Create new content for your site`
			`help [command] Help about any command`
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00
			`Available Flags:`
Updating / Rewriting / Adding all of the documentation in preparation for the next release 2014-05-27 22:32:57 +00:00			`-b, --baseUrl="": hostname (and path) to the root eg. http://spf13.com/`
Add future details to documentation 2014-05-29 05:00:06 +00:00			`-D, --buildDrafts=false: build content marked as draft`
			`-F, --buildFuture=false: build content with PublishDate in the future`
Adding proper command line option parsing 2013-07-19 07:38:24 +00:00			`--config="": config file (default is path/config.yaml\|json\|toml)`
Updating a bunch of the docs 2013-08-03 07:30:34 +00:00			`-d, --destination="": filesystem path to write files to`
Updating / Rewriting / Adding all of the documentation in preparation for the next release 2014-05-27 22:32:57 +00:00			`--disableRSS=false: Do not build RSS files`
			`--disableSitemap=false: Do not build Sitemap file`
Adding support for logging & verbose logging. Consolidation of error handling. Integration of jWalterWeatherman library. Fixed #137 2014-03-31 17:23:34 +00:00			`--log=false: Enable Logging`
Updating / Rewriting / Adding all of the documentation in preparation for the next release 2014-05-27 22:32:57 +00:00			`--logFile="": Log File path (if set, logging enabled automatically)`
Adding proper command line option parsing 2013-07-19 07:38:24 +00:00			`-s, --source="": filesystem path to read files relative from`
Updating / Rewriting / Adding all of the documentation in preparation for the next release 2014-05-27 22:32:57 +00:00			`--stepAnalysis=false: display memory and timing of different steps of the program`
			`-t, --theme="": theme to use (located in /themes/THEMENAME/)`
			`--uglyUrls=false: if true, use /filename.html instead of /filename/`
Adding proper command line option parsing 2013-07-19 07:38:24 +00:00			`-v, --verbose=false: verbose output`
Updating / Rewriting / Adding all of the documentation in preparation for the next release 2014-05-27 22:32:57 +00:00			`--verboseLog=false: verbose logging`
Adding proper command line option parsing 2013-07-19 07:38:24 +00:00			`-w, --watch=false: watch filesystem for changes and recreate as needed`
adding hugo 2013-07-04 15:32:55 +00:00
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00			`Use "hugo help [command]" for more information about that command.`

More proofreading and minor revisions to Hugo docs Among the various changes, most instances of {{ template "partials/FILE.html" . }} were changed to {{ partial "FILE.html" . }} Also, in main.go, change "2013" to "2013-14". 2014-09-03 04:12:26 +00:00			`## Common Usage Example`
adding hugo 2013-07-04 15:32:55 +00:00
add note that running with watch doesn't produce a site suitable for deployment 2015-02-17 23:08:54 +00:00			The most common use is probably to run `hugo` with your current directory being the input directory.
adding hugo 2013-07-04 15:32:55 +00:00
			`$ hugo`
			`> X pages created`
Updating a bunch of the docs 2013-08-03 07:30:34 +00:00			`in 8 ms`
adding hugo 2013-07-04 15:32:55 +00:00
add note that running with watch doesn't produce a site suitable for deployment 2015-02-17 23:08:54 +00:00			`If you are working on things and want to see the changes immediately, tell Hugo to watch for changes.`
Updating / Rewriting / Adding all of the documentation in preparation for the next release 2014-05-27 22:32:57 +00:00
add note that running with watch doesn't produce a site suitable for deployment 2015-02-17 23:08:54 +00:00			`Hugo will watch the filesystem for changes, rebuild your site as soon as a file is saved.`
adding hugo 2013-07-04 15:32:55 +00:00
Fix example in docs that wouldn't work in practice The pflag package used in hugo has to use the "=" sign for double dash options such as --source. Thus the original example `--source ~/mysite` is already incorrect. Adding the = sign though woul not fix things in this case, since `--source=~/mysite` does not get resolved to /home/username/mysite, but looks for the ./~/mysite directory within the current directory. To resolve this, either the directory name has to be changed in the docs not to use the "~" sign, or have to change to use the single dash version of the command line flag. The latter seems to be more in line with the rest of the example. Leaving `--watch` as a double dash option to minimize the change, though it could be either way, since the follow up example uses the single dash version of both. 2013-08-05 13:45:01 +00:00			`$ hugo -s ~/mysite --watch`
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00			`28 pages created`
Switching docs highlighting to highlight.js .. Docs build super fast again! 2014-05-15 13:58:55 +00:00			`in 18 ms`
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00			`Watching for changes in /Users/spf13/Code/hugo/docs/content`
Change "ctrl+c" to "Ctrl+C" 2015-01-29 21:19:12 +00:00			`Press Ctrl+C to stop`
adding hugo 2013-07-04 15:32:55 +00:00
add note that running with watch doesn't produce a site suitable for deployment 2015-02-17 23:08:54 +00:00			`Hugo can even run a server and create a site preview at the same time! Hugo`
			`implements [LiveReload](/extras/livereload/) technology to automatically reload any open pages in all browsers (including mobile). (Note that you'll need to run without -w before you deploy your site.)`
adding hugo 2013-07-04 15:32:55 +00:00
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00			`$ hugo server -ws ~/mysite`
			`Watching for changes in /Users/spf13/Code/hugo/docs/content`
adding hugo 2013-07-04 15:32:55 +00:00			`Web Server is available at http://localhost:1313`
Change "ctrl+c" to "Ctrl+C" 2015-01-29 21:19:12 +00:00			`Press Ctrl+C to stop`
Updating usage documentation to new interface 2013-10-01 02:39:06 +00:00			`28 pages created`
			`0 tags created`
add note that running with watch doesn't produce a site suitable for deployment 2015-02-17 23:08:54 +00:00			`in 18 ms`