[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
gohugoio · Mar 12, 2015 · 1f9b4ef · 1f9b4ef
1 parent 0ead109
commit 1f9b4ef
Showing 1 changed file with 140 additions and 55 deletions.
diff --git a/docs/content/overview/usage.md b/docs/content/overview/usage.md
@@ -14,69 +14,154 @@ 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.
+<pre><code class="hljs nohighlight">$ 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
+  config      Print the site configuration
+  check       Check content in the source directory
+  benchmark   Benchmark hugo by building a site a number of times
+  new         Create new content for your site
+  help        Help about any command
+
+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/
+  -D, --buildDrafts=false: include content marked as draft
+  -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)
+  -d, --destination="": filesystem path to write files to
+      --disableRSS=false: Do not build RSS files
+      --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
+      --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
+      --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
+
+Use "hugo help [command]" for more information about a command.
+</code></pre>
 
 ## 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
-    > X pages created
-      in 8 ms
+    0 draft content
+    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.
+Hugo will watch the filesystem for changes, and rebuild your site as soon as a file is saved:
+
+    $ hugo -s ~/Code/hugo/docs --watch
+    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
+    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 JavaScript-enabled browsers, including mobile.
+This is the easiest and most common way to develop a Hugo web site:
+
+    $ 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
+    Serving pages from /Users/spf13/Code/hugo/docs/public
+    Web Server is available at http://localhost:1313/
+    Press Ctrl+C to stop
+
+
+## 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
 
-Hugo will watch the filesystem for changes, rebuild your site as soon as a file is saved.
+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.
 
-    $ 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
+You may optionally add `--disableLiveReload=true` if you do not want
+the JavaScript code for LiveReload to be added to your web pages.
 
-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.)
+Interested? Here are some great tutorials contributed by Hugo users:
 
-    $ 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
+* [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