From 9a499b56c964d08fe43a43e48fe038f489cebfb6 Mon Sep 17 00:00:00 2001 From: mdhender Date: Sat, 4 Apr 2015 03:13:06 -0500 Subject: [PATCH] Add a section comparing the 'build' and 'server' One of the first things that new users have to understand is the difference between Hugo as a web server and Hugo as a web site generator. Issue #852 asked for documentation to make that clear. This patch updates the overview page with that information. It will seem repetitive to users that understand the difference. Weigh that against the needs of those that don't. Reference #852 --- docs/content/overview/introduction.md | 41 +++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/content/overview/introduction.md b/docs/content/overview/introduction.md index 2ff199e0b..cdf845d1e 100644 --- a/docs/content/overview/introduction.md +++ b/docs/content/overview/introduction.md @@ -37,6 +37,47 @@ build times and the ability to rebuild whenever a change is made, Hugo provides a very fast feedback loop. This is essential when you are designing websites, but also very useful when creating content. +## What makes Hugo different? + +Web site generators render content into HTML files. Most are "dynamic +site generators." That means the HTTP +server (which is the program running on your website that the user's +browser talks to) runs the generator to create a new HTML file +each and every time a user wants to view a page. + +Creating the page dynamically means that the computer hosting +the HTTP server has to have enough memory and CPU to effectively run +the generator around the clock. If not, then the user has to wait +in a queue for the page to be generated. + +Nobody wants users to wait longer than needed, so the dynamic site +generators programmed their systems to cache the HTML files. When +a file is cached, a copy of it is temporarily stored on the computer. +It is much faster for the HTTP server to send that copy the next time +the page is requested than it is to generate it from scratch. + +Hugo takes cacheing a step further. All HTML files are rendered on your +computer. You can review the files before you copy them to the computer +hosting the HTTP server. Since the HTML files aren't generated dynamically, +we say that Hugo is a "static site generator." + +Not running a web site generator on your HTTP server has many benefits. +The most noticeable is performance - HTTP servers are very good at +sending files. So good that you can effectively serve the same number +of pages with a fraction of the memory and CPU needed for a dynamic site. + +Hugo has two components to help you build and test your web site. The +one that you'll probably use most often is the built-in HTTP server. +When you run `hugo server`, Hugo renders all of your content into +HTML files and then runs a HTTP server on your computer so that you +can see what the pages look like. + +The second component is used when you're ready to publish your web +site to the computer running your website. Running Hugo without any +actions will rebuild your entire web site using the `baseurl` setting +from your site's configuration file. That's required to have your page +links work properly with most hosting companies. + ## How fast is Hugo? {{% youtube CdiDYZ51a2o %}}