Hugo-For-Beginners.Pdf
Total Page:16
File Type:pdf, Size:1020Kb
Hugo for Beginners A complete beginners’ guide on developing a blog site with Hugo static site generator Author: M. Hasan License: Creative Commons license CC BY-SA 4.0 DOI: doi.org/10.5281/zenodo.3887269 Online Version: pilinux.me/hugo/hugo-for-beginners Code Examples: github.com/piLinuxME/collections/hugo/hugo-for-beginners Abstract Written in one of the fastest-growing languagesi Golang, Hugo excels in building static sites from local markdown files and dynamic API-drivenii content at a blistering speediii. There are numerous free themesiv available online for rapid prototyping and development of a Hugo based blog site. This tutorial concentrates on developing a Hugo based site from scratch without importing any already developed theme. Contents Abstract ................................................................................................................................................... 1 Introduction ............................................................................................................................................ 2 Environment Setup ................................................................................................................................. 2 Windows 10 (64-bit) OS ...................................................................................................................... 2 Ubuntu 18.04.4 LTS (64-bit) OS........................................................................................................... 3 New Site Creation ................................................................................................................................... 4 Theme Development .............................................................................................................................. 4 Template for Regular Pages ................................................................................................................ 7 Template for Listing Pages ................................................................................................................ 15 Template for Homepage ................................................................................................................... 16 Template for 404 Error Page ............................................................................................................. 17 Summary ............................................................................................................................................... 18 References ............................................................................................................................................ 18 Introduction Unlike dynamic websites, static sites have fewer or no dependencies on databases, application servers and thus provides enhanced security, faster loading speed, and improved performance for end-users. Manually maintaining and updating each page of a static site is cumbersome. Hence, static site generators were born where the developer writes the functionality of the site, the content editor publishes or updates articles, and finally, the website generator renders the contents into HTML files and saves thousands of development and maintenance hours. Out of the 283 opensource static site generators enlisted on staticgen.comv, here website development using Hugo generator is discussed thoroughly. Environment Setup For different architectures and operating systems (OS), the compiled versions of Hugo along with the source codes are available for free on Githubvi under version 2.0 of the Apache Licensevii. Hugo version 0.72.0, Windows 10 (64-bit), and Ubuntu 18.04.4 LTS (64-bit) are considered for this tutorial. Windows 10 (64-bit) OS Hugo binary file for Windows OS can be extracted from github.com/gohugoio/hugo/releases/download/v0.72.0/hugo_0.72.0_Windows-64bit.zip and can be executed from the command-line interpreter. For demonstration, here hugo.exe file is saved in D:\Hugo_workspace directory. On a Windows machine, hugo.exe must be located in the same directory from where Hugo’s command-line interface (CLI) needs to be accessed unless the "PATH" environment variable is set. # change directory D:\>cd Hugo_workspace # check Hugo version D:\Hugo_workspace>hugo version # output: # Hugo Static Site Generator v0.72.0-8A7EF3CF windows/amd64 BuildDate: 2020-05-31T12:08:42Z Listing 1: Run Hugo on a Windows 10 64-bit machine 2 Ubuntu 18.04.4 LTS (64-bit) OS Hugo binaries have no dependency. After placing the binary file in /usr/local/bin directory, Hugo’s CLI can be accessed from any location. # home directory cd # fetch binary file wget https://github.com/gohugoio/hugo/releases/download/v0.72.0/hugo_0.72.0_Linux-64bit.tar.gz # extract tar -xvf hugo_0.72.0_Linux-64bit.tar.gz # change directory cd /usr/local/bin/ # copy hugo binary file sudo cp ~/hugo . # return back to the home directory cd # check Hugo version hugo version # output: # Hugo Static Site Generator v0.72.0-8A7EF3CF linux/amd64 BuildDate: 2020-05-31T12:07:45Z Listing 2: Run Hugo on a Linux 64-bit machine 3 New Site Creation With a one-line command hugo new site tutorial , Hugo creates a new website scaffolded at tutorial project directory. The newly-created site’s directory structure is: Table 1: Directory structure of a newly scaffolded Hugo site |── archetypes |── default.md |── content |── data |── layouts |── static |── themes |── config.toml Theme Development This tutorial follows more of a pragmatic approach rather than diving into theories. With the development of a Hugo theme, directory structure and different features of Hugo will be explored. At the root of the project, in this case at tutorial/ path, executing hugo new theme custom creates a new theme named "custom" at tutorial/themes/custom location. The directory structure of custom is: Table 2: Directory structure of a newly generated theme |── archetypes |── default.md |── layouts |── _default |── baseof.html |── list.html |── single.html |── partials |── footer.html |── head.html |── header.html |── 404.html |── index.html |── static 4 |── css |── js |── LICENSE |── theme.toml Hugo uses Golang’s data-driven html/templateviii package for generating HTML output safe against code injection and text/templateix package to generate textual output. custom/layouts contains skeletons for four types of pages: Homepage Listing pages (index pages etc.) Regular pages (about-us page, blog posts or articles, etc.) Custom 404 error page Listing 3 contains HTML codes of a single webpage built with the Bootstrap CSS and JS libraries. In the upcoming lessons, a Hugo theme is created from this webpage. <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width,initial-scale=1" /> <meta http-equiv="x-ua-compatible" content="IE=edge" /> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous" /> <style> .px-6 { padding-top: 4.5rem !important; padding-bottom: 4.5rem !important; } a { color: #000; } .navbar-nav-text { color: #000 !important; } h1, h2, h3, h4, h5, h6 { font-weight: 400; } </style> 5 <title>Hugo for beginners</title> </head> <body> <div class="navbar navbar-expand-lg fixed-top navbar-light bg-white"> <div class="container"> <a href="/" class="navbar-brand">Hugo for beginners</a> <button class="navbar-toggler" type="button" data-toggle="collapse" data- target="#navbarResponsive" aria-controls="navbarResponsive" aria-expanded="false" aria-label="Toggle navigation"> <span class="navbar-toggler-icon"></span> </button> <div class="collapse navbar-collapse" id="navbarResponsive"> <ul class="navbar-nav"> <li class="nav-item dropdown"> <a class="nav-link navbar-nav-text" data-toggle="dropdown" href="#" id="blog"> Blog </a> <div class="dropdown-menu" aria-labelledby="web-development"> <a class="dropdown-item navbar-nav-text" href="/web-development/"> Web Development </a> </div> </li> </ul> </div> </div> </div> <div class="container px-6"> <div class="row"> <div class="col-md-12"> Hello world! </div> </div> <br /><br /><br /> </div> <footer> <div class="container"> <div class="card"> <div class="card-body py-2"> <p class="card-text text-center"> <a href="./">Hugo for beginners</a> - Content available under a Creative Commons license <a href="https://creativecommons.org/licenses/by-sa/4.0" target="_blank" rel="noreferrer">CC BY-SA 4.0</a> unless otherwise specified. 6 </p> </div> </div> <br /> </div> </footer> <script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384- DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script> <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/umd/popper.min.js" integrity="sha384- Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script> <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script> </body> </html> Listing 3: HTML template of a single webpage Template for Regular Pages In the PDF version of this article, Listing 3 contains four different blocks denoted by four different colors – light gray, sky blue, light orange, and light gold in ascending order. On the web version, lines 4 – 28 refers to 'head' block, lines 32 – 53 refers to the 'header' block, lines 55 – 64 belongs