How does Hugo work? What is the mechanism to produce a static web site?
Existing descriptions
I was searching for such a “high level description” how Hugo works in
What fits most is
An attempt at describing how Hugo works
Hugo takes the all the Markdown files it finds in the content directory and its subdirectories. Hugo converts them to static HTML files. The folder structure in the content directory is taken for the navigation.
The direct set of subdirectories of the content folder are considered to define sections.
Clarification needed
I am looking for such a high-level description of the site generation “algorithm” which explains what Hugo does…
Lol! Now seriously, I don’t know where you found out about the Hugo algorithm, but I’m sorry to tell you that there is no algorithm or AI involved.
Hugo is an Open Source static site generator written in Go that expects a certain file structure, configuration settings, templates and user content that is then published in the form of a website after running the command hugo in a console.
It basically just means: a description of the steps involved from proceeding from the input (which is mainly what is in the content folder, the chosen theme and the configuration file to the output, which is the public folder.
You write
Hugo is an Open Source static site generator written in Go that
expects a certain file structure,
configuration settings,
templates and
user content
that is then published in the form of a website after running the command hugo in a console.
This is in a simple form the “algorithm” (=description) what Hugo does. I’d like to see a bit more details …
As I am asking what does “Hugo” does
It could be something like this (2nd attempt, not sure if Hugo actually does this, this is why I am asking …)
Hugo reads the settings from the configuration file.
Hugo goes through all the files in the content directory and its subdirectories and recreates the same directory structure in the output folder called public.
If it encounters a single file in a subfolder in the content directory it looks for a template called single.html to use if there are several files it looks for a tempate called list.html.
Templates can be found in the layouts folder or in folder of the currently uses theme. A template may require other templates.
How could a 3rd attempt at a description lool like?
There is the templates lookup order in the Docs. There is default precedence regarding the way posts are ordered. The closest thing to an algorithm is perhaps the Related Content feature.
Beyond that @bep could elighten you further regarding how Hugo internally builds a site (if he has the time -that is-).
It’s a good exercise to try to describe something in a simple way, in a couple of sentences. I’ve described Hugo to people in the past like so:
Hugo is a Static Site Generator, which makes it simple to create and use html “templates” that merge your css, javascript, images and content written in Markdown format, into a publishable website. Hugo is developed with emphasis on speed and performance; in fact, it will probably take longer to upload the site to your server, than it does for Hugo to generate it. It’s easily installable on all major platforms - Mac, Windows, Linux - as a single, simple file.
Anyway, that’s how I described it to some business users.
Once you have successfully explained what a static site generator is, I don’t see how to single out a description for Hugo without just comparing/benchmarking it with to other static gen (lots of pros, few cons). But let us know what you end up with!
Sure, most web developers know what a static site generator is.
Comparison with other static generators is fine as well.
But you cannot say that web developers easily get it. Otherwise we would not have all these quite basic questions in this forum.
The title of this post is ‘How does Hugo work’? And then I asked for the “algorithm”.
This means
What does Hugo do?
Which are the steps involved - Such as
reading the config file,
going through the contents directory and its subdirectories
Construct the site object which contains all the parameters (and more??) to be accessed through the context (a dot) in the templates.
Searching for templates and applying them with the Markdown input supplied from the contents directory
Applying the default taxonomy (unless otherwise stated) to the tags and categories given in the Markdown files and creating static web pages for each tag and category.
Create a folder structure in the public folder folder which follows the structure of the contents folder and write the generated html files and the files copied from the static folder.
Something worth explaining: Hugo uses the golang template system. (Golang developer perspective here: template package - html/template - Go Packages ; template package - text/template - Go Packages Templates are executed by applying them to a data structure. Annotations in the template refer to elements of the data structure to control execution and derive values to be displayed. Execution of the template walks the structure and sets the cursor, represented
by a period ‘.’ and called “dot”, to the value at the current location in the structure as execution proceeds.
). How does this look like from the web developer perspective?
A description from web developer perspective is not the same as a description for a business user.
The descriptions in the documentation and in this thread so far have been quite vague.
One has to find out by trail and error by …
trying out different themes and identifiying which type of web site they support
changing them here and there and test if it still works
finding out what is a hard coded convention and what may be changed
The explanations could start from a very basic explanation such as
And then proceed to more detailed descriptions what Hugo does.
For example when I started it was not clear to me that the layouts directory may be empty as the theme has a layout directory and the layouts are taken from there. It is not necessary to copy the layouts from the theme layouts directory to the layouts directory as there is a lookup process for layouts which depends on naming conventions.
Of course good example themes are helpful as well (see other recent thread on this).
When I studied Hugo, I created for myself this mindmap. The gray arrows show Hugo’s work. Perhaps it will help someone to understand something, or inspire to draw something like this more professionally.
It helped me understand how to add plain markdown pages to a site that’s mostly hugo-reveal presenations, and that was a bloody miracle
Clear doc is a wonderful thing. Seems like the official doc needs something like Jake’s doc added to it.
@hjh I know I am late to the party, but I just wanted to post to let you know I really appreciate your quest. Algorithmic descriptions are a wonderful way of cutting through the complexity of large projects. That hard part is getting explanations that are succinct, yet relevant enough.
The Jake Wiesler page is one of the best I’ve come across. But there’s still a lot more to be covered.
