mirror of
				https://github.com/gohugoio/hugo.git
				synced 2024-05-11 05:54:58 +00:00 
			
		
		
		
	[Docs] Update and expand http://gohugo.io/overview/usage/
The `hugo help` output as shown in http://gohugo.io/overview/usage/ was not yet updated for v0.13. Thanks to @alebaffa for the heads up! Also: - Clarify that, after using `hugo server`, the bare `hugo` command need to be run before deployment. - Add a section on running `hugo` as production web server, and add links to two blog posts of two Hugo users sharing their experience. Partially fixes: #852 and #937
This commit is contained in:
		@@ -14,69 +14,154 @@ weight: 30
 | 
				
			|||||||
 | 
					
 | 
				
			||||||
Make sure either `hugo` is in your `PATH` or provide a path to it.
 | 
					Make sure either `hugo` is in your `PATH` or provide a path to it.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
    $ hugo help
 | 
					<pre><code class="hljs nohighlight">$ hugo help
 | 
				
			||||||
    A Fast and Flexible Static Site Generator
 | 
					A Fast and Flexible Static Site Generator built with
 | 
				
			||||||
    built with love by spf13 and friends in Go.
 | 
					love by spf13 and friends in Go.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
    Complete documentation is available at http://gohugo.io
 | 
					Complete documentation is available at http://gohugo.io
 | 
				
			||||||
 | 
					
 | 
				
			||||||
    Usage:
 | 
					Usage:
 | 
				
			||||||
  hugo [flags]
 | 
					  hugo [flags]
 | 
				
			||||||
  hugo [command]
 | 
					  hugo [command]
 | 
				
			||||||
 | 
					Available Commands:
 | 
				
			||||||
    Available Commands:
 | 
					 | 
				
			||||||
  server      Hugo runs its own webserver to render the files
 | 
					  server      Hugo runs its own webserver to render the files
 | 
				
			||||||
  version     Print the version number of Hugo
 | 
					  version     Print the version number of Hugo
 | 
				
			||||||
 | 
					  config      Print the site configuration
 | 
				
			||||||
  check       Check content in the source directory
 | 
					  check       Check content in the source directory
 | 
				
			||||||
  benchmark   Benchmark hugo by building a site a number of times
 | 
					  benchmark   Benchmark hugo by building a site a number of times
 | 
				
			||||||
      new [path]                Create new content for your site
 | 
					  new         Create new content for your site
 | 
				
			||||||
      help [command]            Help about any command
 | 
					  help        Help about any command
 | 
				
			||||||
 | 
					
 | 
				
			||||||
     Available Flags:
 | 
					Flags:
 | 
				
			||||||
 | 
					      --noTimes=false: Don't sync modification time of files
 | 
				
			||||||
 | 
					  -w, --watch=false: watch filesystem for changes and recreate as needed
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Global Flags:
 | 
				
			||||||
  -b, --baseUrl="": hostname (and path) to the root eg. http://spf13.com/
 | 
					  -b, --baseUrl="": hostname (and path) to the root eg. http://spf13.com/
 | 
				
			||||||
      -D, --buildDrafts=false: build content marked as draft
 | 
					  -D, --buildDrafts=false: include content marked as draft
 | 
				
			||||||
      -F, --buildFuture=false: build content with PublishDate in the future
 | 
					  -F, --buildFuture=false: include content with datePublished in the future
 | 
				
			||||||
 | 
					      --cacheDir="": filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
 | 
				
			||||||
      --config="": config file (default is path/config.yaml|json|toml)
 | 
					      --config="": config file (default is path/config.yaml|json|toml)
 | 
				
			||||||
  -d, --destination="": filesystem path to write files to
 | 
					  -d, --destination="": filesystem path to write files to
 | 
				
			||||||
      --disableRSS=false: Do not build RSS files
 | 
					      --disableRSS=false: Do not build RSS files
 | 
				
			||||||
      --disableSitemap=false: Do not build Sitemap file
 | 
					      --disableSitemap=false: Do not build Sitemap file
 | 
				
			||||||
 | 
					      --editor="": edit new content with this editor, if provided
 | 
				
			||||||
 | 
					  -h, --help=false: help for hugo
 | 
				
			||||||
 | 
					      --ignoreCache=false: Ignores the cache directory for reading but still writes to it
 | 
				
			||||||
      --log=false: Enable Logging
 | 
					      --log=false: Enable Logging
 | 
				
			||||||
      --logFile="": Log File path (if set, logging enabled automatically)
 | 
					      --logFile="": Log File path (if set, logging enabled automatically)
 | 
				
			||||||
 | 
					      --pluralizeListTitles=true: Pluralize titles in lists using inflect
 | 
				
			||||||
  -s, --source="": filesystem path to read files relative from
 | 
					  -s, --source="": filesystem path to read files relative from
 | 
				
			||||||
      --stepAnalysis=false: display memory and timing of different steps of the program
 | 
					      --stepAnalysis=false: display memory and timing of different steps of the program
 | 
				
			||||||
  -t, --theme="": theme to use (located in /themes/THEMENAME/)
 | 
					  -t, --theme="": theme to use (located in /themes/THEMENAME/)
 | 
				
			||||||
      --uglyUrls=false: if true, use /filename.html instead of /filename/
 | 
					      --uglyUrls=false: if true, use /filename.html instead of /filename/
 | 
				
			||||||
  -v, --verbose=false: verbose output
 | 
					  -v, --verbose=false: verbose output
 | 
				
			||||||
      --verboseLog=false: verbose logging
 | 
					      --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.
 | 
					Use "hugo help [command]" for more information about a command.
 | 
				
			||||||
 | 
					</code></pre>
 | 
				
			||||||
 | 
					
 | 
				
			||||||
## Common Usage Example
 | 
					## Common Usage Example
 | 
				
			||||||
 | 
					
 | 
				
			||||||
The most common use is probably to run `hugo` with your current directory being the input directory.
 | 
					The most common use is probably to run `hugo` with your current directory being the input directory:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
    $ hugo
 | 
					    $ hugo
 | 
				
			||||||
    > X pages created
 | 
					    0 draft content
 | 
				
			||||||
      in 8 ms
 | 
					    0 future content
 | 
				
			||||||
 | 
					    99 pages created
 | 
				
			||||||
 | 
					    0 paginator pages created
 | 
				
			||||||
 | 
					    16 tags created
 | 
				
			||||||
 | 
					    0 groups created
 | 
				
			||||||
 | 
					    in 120 ms
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					This generates your web site to the `public/` directory,
 | 
				
			||||||
 | 
					ready to be deployed to your web server.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					## Instant feedback as you develop your web site
 | 
				
			||||||
 | 
					
 | 
				
			||||||
If you are working on things and want to see the changes immediately, tell Hugo to watch for changes.
 | 
					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, and rebuild your site as soon as a file is saved:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
Hugo will watch the filesystem for changes, rebuild your site as soon as a file is saved.
 | 
					    $ hugo -s ~/Code/hugo/docs --watch
 | 
				
			||||||
 | 
					    0 draft content
 | 
				
			||||||
    $ hugo -s ~/mysite --watch
 | 
					    0 future content
 | 
				
			||||||
       28 pages created
 | 
					    99 pages created
 | 
				
			||||||
       in 18 ms
 | 
					    0 paginator pages created
 | 
				
			||||||
 | 
					    16 tags created
 | 
				
			||||||
 | 
					    0 groups created
 | 
				
			||||||
 | 
					    in 120 ms
 | 
				
			||||||
    Watching for changes in /Users/spf13/Code/hugo/docs/content
 | 
					    Watching for changes in /Users/spf13/Code/hugo/docs/content
 | 
				
			||||||
    Press Ctrl+C to stop
 | 
					    Press Ctrl+C to stop
 | 
				
			||||||
 | 
					
 | 
				
			||||||
Hugo can even run a server and create a site preview at the same time! Hugo
 | 
					Hugo can even run a server and create a site preview at the same time!
 | 
				
			||||||
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 implements [LiveReload](/extras/livereload/) technology to automatically
 | 
				
			||||||
 | 
					reload any open pages in all JavaScript-enabled browsers, including mobile.
 | 
				
			||||||
 | 
					This is the easiest and most common way to develop a Hugo web site:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
    $ hugo server -ws ~/mysite
 | 
					    $ hugo server -ws ~/Code/hugo/docs
 | 
				
			||||||
 | 
					    0 draft content
 | 
				
			||||||
 | 
					    0 future content
 | 
				
			||||||
 | 
					    99 pages created
 | 
				
			||||||
 | 
					    0 paginator pages created
 | 
				
			||||||
 | 
					    16 tags created
 | 
				
			||||||
 | 
					    0 groups created
 | 
				
			||||||
 | 
					    in 120 ms
 | 
				
			||||||
    Watching for changes in /Users/spf13/Code/hugo/docs/content
 | 
					    Watching for changes in /Users/spf13/Code/hugo/docs/content
 | 
				
			||||||
       Web Server is available at http://localhost:1313
 | 
					    Serving pages from /Users/spf13/Code/hugo/docs/public
 | 
				
			||||||
 | 
					    Web Server is available at http://localhost:1313/
 | 
				
			||||||
    Press Ctrl+C to stop
 | 
					    Press Ctrl+C to stop
 | 
				
			||||||
       28 pages created
 | 
					
 | 
				
			||||||
       0 tags created
 | 
					
 | 
				
			||||||
       in 18 ms
 | 
					## Deploying your web site
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					After running `hugo server` for local web development,
 | 
				
			||||||
 | 
					you need to do a final `hugo` run **without the `server` command**
 | 
				
			||||||
 | 
					and **without `--watch` or `-w`** to rebuild your site.
 | 
				
			||||||
 | 
					You may then **deploy your site** by copying the `public/` directory
 | 
				
			||||||
 | 
					(by FTP, SFTP, WebDAV, Rsync, git push, etc.) to your production web server.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Since Hugo generates a static website, your site can be hosted anywhere,
 | 
				
			||||||
 | 
					including [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][],
 | 
				
			||||||
 | 
					[Amazon S3][] and [CloudFront][], or any other cheap or even free
 | 
				
			||||||
 | 
					static web hosting services.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					[Apache][], [nginx][], [IIS][]...  Any web server software would do!
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					[Apache]: http://httpd.apache.org/ "Apache HTTP Server"
 | 
				
			||||||
 | 
					[nginx]: http://nginx.org/
 | 
				
			||||||
 | 
					[IIS]: http://www.iis.net/
 | 
				
			||||||
 | 
					[Heroku]: https://www.heroku.com/
 | 
				
			||||||
 | 
					[GoDaddy]: https://www.godaddy.com/
 | 
				
			||||||
 | 
					[DreamHost]: http://www.dreamhost.com/
 | 
				
			||||||
 | 
					[GitHub Pages]: https://pages.github.com/
 | 
				
			||||||
 | 
					[Amazon S3]: http://aws.amazon.com/s3/
 | 
				
			||||||
 | 
					[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					### Alternatively, serve your web site with Hugo!
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Yes, that's right!  Because Hugo is so blazingly fast both in web site creation
 | 
				
			||||||
 | 
					*and* in web serving (thanks to its concurrent and multi-threaded design and
 | 
				
			||||||
 | 
					its Go heritage), some users actually prefer using Hugo itself to serve their
 | 
				
			||||||
 | 
					web site *on their production server*!
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					No other web server software (Apache, nginx, IIS...) is necessary.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Here is the command:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					    hugo server --watch \
 | 
				
			||||||
 | 
					                --baseUrl=http://yoursite.org/ --port=80 \
 | 
				
			||||||
 | 
					                --appendPort=false
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					This way, you may actually deploy just the source files,
 | 
				
			||||||
 | 
					and Hugo on your server will generate the resulting web site
 | 
				
			||||||
 | 
					on-the-fly and serve them at the same time.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					You may optionally add `--disableLiveReload=true` if you do not want
 | 
				
			||||||
 | 
					the JavaScript code for LiveReload to be added to your web pages.
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					Interested? Here are some great tutorials contributed by Hugo users:
 | 
				
			||||||
 | 
					
 | 
				
			||||||
 | 
					* [hugo, syncthing](http://fredix.ovh/2014/10/hugo-syncthing/) (French) by Frédéric Logier (@fredix)
 | 
				
			||||||
 | 
					* [服务器上 hugo 的安装和配置 <small>(Installing and configuring Hugo on the server)</small>](http://hucsmn.com/post/hugo-tutorial-make-it-work/) (Chinese) by hucsmn
 | 
				
			||||||
 
 | 
				
			|||||||
		Reference in New Issue
	
	Block a user