General
Create and Build A Static Website With Hugo
Introduction Back then creating a personal website/blog was extremely painful; layout design, site development, managing the security, SSL certificates, owning a domain, hosting platform and of course the content were all alone on you and over your head, which was almost impossible if you were not from a web development background. And later, few of the website providers evolved and have been providing web hosting services but most of the controls are still with service provider itself and involves some additional cost to it for any greater customization. But now in the modern era of emerging cloud technology you don’t need to be a web developer any more and in fact not necessarily be a true techie guy, because except the content all other overheads like layout design and site development will be taken care of by some website generators and managing the security, SSL certificates, owning a domain and hosting platform will be handled by cloud technologies. So all you need is to concentrate on your content itself. However if you are from a technical background and not necessarily be from web development then you can build your own website/blog in the matter of minutes, and if you have a little exposure on the development then you could take the customization to a different level and generate a feel good website of your choice. What is a static website? A Static website is a collection of HTML webpages with fixed content, and every time the page loads it displays the same information to every visitor. The content remains unchanged after the site generated/built and doesn’t require any coding or backend (database) support, so that the pages can load so quickly and reliable, and change in the content requires to generate the whole site again. In simple, static websites are a basic type of websites and are easy to create. Static websites are used for… Company/personal branding Personal website or blog Project documentation or product manuals Advertisement or promotional offers of a product Presentation or status pages Newsletters & survey forms Landing page Now let’s see how to build a static website/blog using Hugo static site generator and available hosting options Build a static website with Hugo Hugo https://gohugo.io/ Hugo is one of the most popular open-source static website generators. It is a standalone tool and very easy to use, and builds the website extremely fast. Its a cross platform tool and flexible enough to host the website pretty much on any hosting platform. There is a huge collection of themes from the community to make up your site beautifully. Advantages No coding or HTML knowledge required Creates web pages using simple markdown syntax It renders the pages extremely fast Standard framework and ease of customization Inbuilt Google Analytics and Comment system Its free and huge community support Install Hugo I am using Windows operating system to install the Hugo and in case if you are using other operating system please refer to this link to follow the installation instructions. Before you install Hugo, ensure you have Git installed, it is recommended by Hugo. Hugo is written in Go language with cross platform support but you don’t need to install the Go to make Hugo to run, and it is a pre-compiled standalone binary. You can download the latest release of Hugo from the github repository under releases . If you need the Sass/SCSS support then you need to download the extended version of Hugo Since Hugo is a pre-compiled standalone binary, it doesn’t require any installation, you can directly grab the binary and set the binary path in the environment PATH variable. To set the environment PATH variable… setx path "%path%;c:\directoryPath" c:\directoryPath is the place where the Hugo binary file is extracted. Install using chocolaty package provider If you don’t have chocolaty package manager is already installed then follow the instructions here to install the chocolaty package manager in windows operating system. To install Hugo… choco install hugo -confirm Or if you need the extended version… choco install hugo-extended -confirm If you install the Hugo using the chocolaty package manager, then it will take care of setting the environment PATH variable. Verify installation To verify the installation… hugo version Create a new site Go to your feasible directory to create a new Hugo site and run the command below in your favorite command line terminal. Here I am using C:\Sites folder to create a new site and running command in PowerShell terminal. hugo new site kpatnayakuni kpatnayakuni is my new site name. Output: Congratulations! Your new Hugo site is created in C:\Sites\kpatnayakuni. Just a few more steps and you're ready to go: 1. Download a theme into the same-named folder. Choose a theme from https://themes.gohugo.io/ or create your own with the "hugo new theme <THEMENAME>" command. 2. Perhaps you want to add some content. You can add single files with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>". 3. Start the built-in live server via "hugo server". Visit https://gohugo.io/ for quickstart guide and full documentation. Now I have create my new site named kpatnayakuni and it will create the site files for us… Directory: C:\Sites\kpatnayakuni Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 17-06-2020 05:47 AM archetypes d---- 17-06-2020 05:47 AM content d---- 17-06-2020 05:47 AM data d---- 17-06-2020 05:47 AM layouts d---- 17-06-2020 05:47 AM static d---- 17-06-2020 05:47 AM themes -a--- 17-06-2020 05:47 AM 82 config.toml Download a theme Now we have created our new site and let’s add a theme to it. You can find a whole bunch of themes in the Hugo themes page where you can go to the download page and see the download instructions. For now I will pick up hugo-refresh theme and add it to our new site. First, go to the site folder and then initialize the git repository PS C:\Sites> cd kpatnayakuni PS C:\Sites\kpatnayakuni> git init Add the theme to themes folder in the site PS C:\Sites\kpatnayakuni> git submodule add https://github.com/PippoRJ/hugo-refresh.git themes/hugo-refresh Using the desktop experience, you can directly download the theme and extract it to the site’s themes folder. And almost all the sites have example site inside the theme with a configuration file. You can copy the same file into your site and configure it as needed. First remove the site configuration file and then copy the example site configuration file from exampleSite folder inside the theme folder to our actual site PS C:\Sites\kpatnayakuni> rm config.* PS C:\Sites\kpatnayakuni> copy ./themes/hugo-refresh/exampleSite/config.* ./ The configuration file is self explanatory and you can modify the site configurations like Title, Description, Author and many more as per your requirement. You can also write your own configuration file from scratch or you can even further configure, please refer here for more details. Hugo can understand the configuration file in the toml, yaml or json format, and the configuration file should be under site’s root directory by default with the filename config and the extension could be any of your choice from .toml, .yaml or .json. Create a page Once you are done with adding the theme and basic site configuration, now we will add some content to the site. By default the content pages are added in the content folder under the site’s root directory. You should know the basic markdown syntax to create content of the site, and Hugo has that ability to convert the markdown files into html files. If you are new to markdown syntax then you can refer to https://www.markdownguide.org/ to get familiarize yourself, and it is very simple and easy to use, you can create or edit the markdown files in any text editor of your choice, and I am using Visual Studio Code for the same. To create a new page, run the command below in the site’s root directory… PS C:\Sites\kpatnayakuni> hugo new posts\welcome.md This creates the file welcome.md under <site’s root directory>\content\posts\welcome.md, i.e., in my case it is C:\Sites\kpatnayakuni\content\posts\welcome.md By default the page will be created with some front matter in it… --- title: "Welcome" date: 2020-06-18T05:09:42+05:30 draft: true --- The front matter is nothing but the attributes of the page, like title, date, author and etc., there are many other attributes that can change the behavior of the page, some are default from Hugo itself, and some are specific to the theme that you have selected, please refer to theme’s README file in the repository for more details, and also you can refer to the exampleSite under the theme’s folder in the site’s root directory for better understanding of organizing the content. Now, let’s add some content to welcome.md file… Open the file with your favorite text editor and add some content to it after the front matter… --- title: "Welcome" date: 2020-06-18T05:09:42+05:30 draft: true --- # This is a sample post This is my personal website and blog. Test the site in the localhost Hugo comes with an inbuilt webserver with live rebuild feature, which is really helpful during the development phase, you can instantly see the changes rendered in the website. To start the webserver… hugo server -D -D flag is used to include the draft pages as well, if you don’t want to include the draft pages then remove -D flag. You can manage the draft pages by setting the draft parameter to true/false in the front matter of the content page. Output: Building sites … | EN | RU -------------------+----+----- Pages | 5 | 3 Paginator pages | 0 | 0 Non-page files | 0 | 0 Static files | 28 | 28 Processed images | 1 | 0 Aliases | 1 | 0 Sitemaps | 0 | 0 Cleaned | 0 | 0 Built in 241 ms Watching for changes in C:\Users\kiran\AppData\Local\Temp\kpatnayakuni\{archetypes,content,data,layouts,static,themes} Watching for config changes in C:\Users\kiran\AppData\Local\Temp\kpatnayakuni\config.yaml Environment: "development" Serving pages from memory Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) Press Ctrl+C to stop By default Hugo brings up the webserver in the localhost with 1313 port number and if you see the webserver local address in the output that means your webserver is up and running in your localhost, then you can open your favorite browser and the open the site mentioned in the output (). Here’s my site with hugo-refresh theme… Home Page Posts List Post Note: I haven’t done any site customization yet, it is a default configuration from the theme, we will see more customization in the next section down below. Site configuration All the site related configuration is made available in the site’s root directory with the filename config.toml or config.yaml. You can open up the site configuration file with your favorite text editor and do configuration as needed. Now we will see few predominant settings will effect your site… My site configuration is in config.yaml, so I am using yaml syntax, if you are using the other format, then please look for the syntax baseURL: "https://kpatnayakuni.com" title: "Kiran Patnayakuni" theme: "hugo-refresh" It has inbuilt Google Analytics and comment system, only thing is that you need to create the required accounts and add those references here in the respective configuration section. For more customisation please refer to the configuration page in the hugo website. Almost all the configuration is self explanatory where you can enter the values accordingly Theme customization By default hugo themes already look great, but still you have many options to customize of your choice. First of all… Choose the theme suites to your purpose, so that the customization will be easy and mostly readily available for you. Before you do any theme customization, please visit the example site and look for the syntax in the respective markdown files, so that you can have a reference of various components used in the site and use them in you site as well. To up the example site, go to the exampleSite folder (<site-root-directory>\themes\<theme-name>\exampleSite) and run the command below… hugo server --themesDir ../.. Please refer to the theme components in the hugo website for better understanding of the site’s folder structure. You should have little knowledge on HTML & CSS to customize the site’s layout like how the home page looks like or list page or post page look like, and to change the behavior of the site you should be familiar with Java script as well. But it is not mandatory to build your site. Pick a theme which you really feel good, but it allows the customization to any extent. To create a rich content in your site you can make use of shortcodes, few are already available with the theme and few are Hugo inbuilt. What is a shortcode? Shortcodes are written in HTML to achieve the richness where markdown short falls. Pick a theme which has a good number of shortcodes, and also refer to shortcodes page in the hugo website for more builtin shortcodes. Build the site To build your ready to deploy site run the command below… hugo Use -D flag to include the draft pages as well. Hugo is the base command to build the hugo site and by default it builds the site under the public folder in the site’s root directory, that you can change it in the site configuration file. It is a complete site and is ready to deploy on any of your favorite hosting platform. Push the site to GitHub repository Once you are done with site customization, added the content and built the site, you can push your site to GitHub Repository. You can go to site’s root directory in your favorite command line terminal and then run the following commands… To initialize the local repository… C:\Sites\kpatnayakuni> git init To add the changes… C:\Sites\kpatnayakuni> git add . To commit the changes… C:\Sites\kpatnayakuni> git commit -m "Initial Commit" If you already have a GitHub account then login and create a repository with the same name as the local repository name, and in my case it is kpatnayakuni. If you don’t have a GitHub account then login into https://github.com/ and sign up with your email id and create the repository . First time if you are using the git then you need to set some global settings to work with the remote repositories… To set user name… C:\Sites\kpatnayakuni> git config --global user.name "<User Full Name>" To set email address… C:\Sites\kpatnayakuni> git config --global user.email "<User Email Address>" You need to use your name and email in the above examples. To add remote repository… C:\Sites\kpatnayakuni> git remote add origin https://github.com/<user_name>/<repository_name>.git To push the site onto GitHub C:\Sites\kpatnayakuni> git push -u origin master Publish the site Now, we are all done and we have our ready to deploy website on to any of our favorite hosting platform. Hugo builds the site which can be hosted pretty much on any hosting platform, and in fact Hugo has inbuilt feature to deploy on to popular cloud providers like Azure, AWS and GCP. You can refer to Hugo Deploy page in the hugo website, and refer to Hosting & Deployment page for other popular hosting solutions. Hosting on GitHub I personally suggest you to host your site on GitHub Pages, it is super easy and extremely fast. All it needs you should have a GitHub account and it is totally free. You can refer to the Hosting On GitHub page in the Hugo website to deploy your site in a step by step manner. I have recently moved my site to Azure Static WebApps from GitHub Pages, however always I have an option to switch back to GitHub Pages at any point of time in case of any an issue with the other hosting platform. Hosting on Azure Static WebApps (Preview) I have no reason to suggest you to host your static website on any other platform other GitHub Pages. In the interest of length of this post and exploring the Azure Static WebApps I will try to explain little about this preview service in my next blog post Publish a static website on Azure Static WebApps (Preview) in continuation to this post.
Welcome to My Weblog
Hello there, I am glad that you are here! I am really excited to start this blog and is all about PowerShell along with other technical stuff. The posts I blog here are truly from my personal experience and for my future reference. So I strongly recommend before you try anything from this blog directly on your production environment, please do it on your test environment first. You’re always welcome to leave your comments, suggestions, and question about my blog posts on my contact page. Thank you & Keep visiting my blog! Kiran Patnayakuni.
