Creating a website in less than 1 hour - part 1
Part 1 - blogdown, Hugo and Netlify
Update 2021-03-01: Hugo and the Academic (now Wowchemy) theme keep changing rapidly. Since I originally posted this, things changed. I tried to update things to reflect some of the changes. If you find things not working, let me know so I can update.
I assume that you have general computer literacy, but no experience with any of the tools that will be used. Also, no coding, web-development or related experience is expected.
What this document covers
This document is meant to provide you with the minimum required instructions to get your own website up and running quickly. As such, instructions and background information are kept at a minimum. I used a recipe-like approach by giving hopefully detailed and specific enough instructions to get things to work. I’m not covering any why here or provide much further explanations. If you decide you like to use this setup for your website, you will likely want to go beyond this document and learn a bit more about the various tools involved in the process. To that end, links to further resources are provided. Those resources also discuss a bit why you would want this setup versus something like e.g. Wordpress.
Who this is (not) for
This way of making and hosting a website might be for you if:
- You are (or would like to be) an R, RMarkdown and GitHub user. This is a method of creating a website using those tools which very efficiently fits into such a workflow.
- You want a way to host a website where all the content is fully controlled by you, and the website can be hosted without much resources (and for free).
- You are curious about R/RMarkdown/GitHub, how to use it to build a website, and you’ve got a bit of time to spare and want to give it a try.
This way of making and hosting a website might not be for you if:
- Your main workflow is MS Word, Powerpoint, etc. and you are not interested in R/Markdown/GitHub.
- You want everything accessible through a graphical interface.
If you want to see a few nice examples of websites written with blogdown/Hugo, check these out:
Many more examples of blogdown/Hugo websites are out there. See e.g. here.
Pointers to more resources and alternative tutorials (should you not like this one) can be found at the bottom of this post.
Quick tool overview
A few different software tools are working together for this website built. In most cases, they play nicely together and you don’t need to worry about details! But it is still good to know the names of the different components.
R and RStudio we won’t really use those for their normal purpose as statistics/coding software/platform, but since blogdown is part of the RMarkdown family of packages, we need to use R and RStudio to access blogdown.
blogdown is an R package that interfaces with Hugo and allows you to create websites easily using RMarkdown syntax.
Hugo is software that operates in the background. It takes all the content you create for your website (your text, your pictures, etc.), applies layout to your site based on a chosen theme, and turns everything into files that can be placed on Netlify and read by anyone’s web browser. You will likely not have to think or learn much about Hugo, at least not initially.
Netlify is the service we’ll use to host the website. It offers a free plan, which is great for a starter website (you can always upgrade once you become famous and everyone visits your website. Netlify is very easy to set up and use, and it can automatically pull information from GitHub to build your site every time you update it (see part 2 for this).
While Netlify and RStudio have paid options, for our purpose we can use their free versions. Hugo, blogdown and R are completely free.
First, you need to set up accounts and install some software for the tools we will be using.
Get a Netlify account
Go to the Netlify website and sign up for an account. Follow the sign-up steps to set up your account.
Install R and RStudio
If you don’t already have it on your computer, install R first. You can pick any mirror you like. If you already have R installed, make sure it is a fairly recent version. If yours is old, I suggest you update (install a new R version).
Once you have R installed, install the free version of RStudio Desktop. Again, make sure it’s a recent version. If you have an older version of RStudio, you should update.
Installing R and RStudio should be fairly straightforward. If you want some more details or need instructions, see this page (which is part of an online course I teach).
Starting your website
With the above registration and installation bits out of the way, you can get started with your website. To do so, follow these steps:
- Open RStudio. Install the blogdown package by typing
install.packages('blogdown')in the R console (the lower left window in RStudio). Note that all
Rcommands are case sensitive. You need to be online for this to work. You should see
blogdownand several other packages being installed. You only need to do this step once, unless you upgrade R or change computers. If for some reason you already had
blogdowninstalled, make sure it’s current and if needed, update it to the latest version. You can update this (and all) R packages by clicking on the
Packagestab in the bottom right window of RStudio, then
library(blogdown)into the R console (you need to do this every time you open/re-load R/RStudio).
Website using blogdown. On the following screen, specify a meaningful directory name (e.g. YOURNAMEWEBSITE), place it somewhere on your computer, check all boxes. In the Hugo theme box, enter
The figure below shows the screen and choices you should make. Adjust for your own setup.
Create Project. This creates a new website and installs and sets up the chosen theme, complete with a small sample site. Be patient, it might take some time. As long as you see a little red stop sign in the top left corner of the R Console window, you know things are still running. Once everything is done, you will see a lot of new files have shown up in your project/repository folder.
The command above installed a small example website. We can build the site and look at it. First, make sure
blogdown has been loaded with
library(blogdown). The build the site by typing
build_site() into the R console. Follow that with
serve_site() to see a live preview of the site. If everything works, the bottom right window, which is the RStudio viewer, shows your new website.
Click on the symbol next to the broom in the top left corner of that window to see the website in your browser. This is your new site. Now it’s time to customize and create content.
A word about themes
Pretty much all modern websites follow the concept of splitting content from layout and only merging them at some point in the process of building a website. The formatting that gives a site a specific layout is often called a theme. The theme determines the look of your website. Hugo has a lot and quickly growing number of themes (though not as many as Wordpress). The idea is that you can switch themes and thus layout without too much difficulty. In practice, there is still often a good bit of adjustment needed when you go from one theme to another. Thus, it is worth spending some time deciding on a theme before you go “all in”.
The default theme
hugo-lithium is a rather basic one. I don’t actually know too many websites that use it. A popular theme is Wowchemy (formerly called Academic). I use it for both my personal and research group sites. I’m using it for this tutorial too. The
Wowchemy theme has a lot of features and customization options. But it has downsides. First, it is fairly complex. Second, it is currently changing rapidly, and those changes often break things. I hope that when you read this, it works. If not, let me know.
There are other promising themes in the works, such as Hugo Prose and Hugo Apero, made by the same folks who are involved with the
blogdown development. I wouldn’t be surprised if in the future a lot of folks, including myself, will switch to one of those themes.
A brief explanation of your new website
The previous steps have given you a website with some example starter content. Any complex website has a certain structure consisting of folders and files. These files and folders either live only on a website server and you never see them (e.g. Wordpress), or they exist locally, as is the case for Hugo (and similar such website generators, e.g. Jekyll.)
Some of the files and folders you do not need to care much about, others you will need to interact with. To get a bit of an idea what lives where, here is a quick overview. Some of this depends on the Hugo theme you are using, but most of them have a rather similar structure. Open the directory where you placed your website, either through the
Files pane in RStudio, or by using File Explorer (or whatever that is called on a Mac\Linux 😃).
- The folder
configcontains files that control some of the overall website look and feel. We’ll visit them later. In Hugo, those files that control configuration are called either
YAMLfiles. The current trend for Hugo is to switch everything to YAML, but you’ll keep seeing a mix for a while. Many files have bits of TOML/YAML and other content in them, as you will see below.
- The folder
contentand its subfolders contain almost all the actual content for your website. We’ll edit some of that soon.
- The folder
publicis the one that contains your finished website once Hugo has processed your content and applied the layout from your chosen theme. That folder is the one which you will place online e.g. on Netlify.
- The folder
staticcontains subfolders where you can store images and other media (e.g. pdf files or video/audio, etc) that you want to be part of your site.
- The folder
themesincludes the different Hugo themes you installed. You can have several themes installed and switch between them. Note however that themes differ in their details of how they do things, so it is a good idea to check out a few themes first, then settle on one and build your website for real once you picked one.
- The other folders that might exist are ones you don’t need to worry about, at least not initially. Some of those folders can contain your own formatting and layout choices overwriting the main theme. We won’t discuss them here but once you really want to start configuring your site, those will become important.
Now that you know a little bit how your website is structured, let’s dig in and add and modify it. We’ll start with some modifications, followed by creating new content.
Playing with widgets
All (or at least most) content goes into the
content folder and its subfolders. Content is generally written in (R)Markdown. For this tutorial, you don’t need to know much Rmarkdown, but at some point you will have to learn it. Fortunately, (R)Markdown is very easy to learn. See e.g. the RMarkdown section on this page, check out this nice interactive tutorial or this cheatsheet.
The Wowchemy/Academic theme, and many other modern websites, use a layout that employs widgets, which are components of a website that are individually formatted and styled. On the demo site you just created, you see many different sections, each is a widget. Which widgets you want is controlled by files in the
/content/home/ folder. Go into that folder (from within RStudio) and open the
demo.md file. You will see a bunch of text. Some commands are between
+++ signs, this is called the TOML (or YAML if it’s 3
---) header. These are instructions for the layout. The text below is what is actually shown on the site.
As you stare at the content of the file, you might recognize that it corresponds to the 2nd block of the demo website with the dark bubble content. Let’s say you don’t want this particular widget on your home page. The easiest way is to set
active = false. (You can also delete the whole file if you are sure you don’t want it). Do that. You should notice 2 things. In the bottom-left RStudio window (the R console) you should see a bit of code showing that the website was re-built and updated in real time. If you re-load the page in your browser, the widget and its content should be gone. You can try turning off other sections of the main page using this approach.
Making things personal
Now let’s open the
about.md file. You will notice that it doesn’t really contain any content. Instead, it pulls the content from another location, namely content in the
authors folder. Go into
/content/authors/admin/ and open the
_index.md file. There you see the content that is displayed on the main page. Modify it with your personal information. Once you save your changes, you should see the website automatically being rebuilt. If you have, add a picture of yourself and replace the current
avatar.jpg file. (Your picture needs to have that name). Also, while not required, you might want to rename the folder from
admin to your name. Make sure this corresponds to the name you list in the
Cleaning up for now
Let’s turn off all other parts of the main site apart from the
about widget. The easiest way is to remove all files apart from the
about.md files. You probably don’t want to completely delete them (since you might want to use them later), thus I recommend you move them to some other folder on your computer. For instance you can make a folder called
myfiles as a subfolder of your website folder and move the files into that folder.
If all of this worked, there should be a main page containing only a brief description of yourself.
A word on error messages.
If you make some changes that break the site, you will see an error message in the R console and the site won’t re-compile until you fix the problem. You often have to be careful to write things exactly as specified, and often with the right indentation, etc. Some fiddling is at times required. If you are stuck and think you broke it too badly, you can either look in the Wowchemy theme documentation or go into the
themes/starter-academic/exampleSite folder and find the corresponding file you are editing there and see how it needs to look.
I mentioned above that TOML/YAML is a language/structure used by Hugo to control all kinds of things. Most files have some TOML/YAML part, a few files are nothing but TOML and control a lot of settings. Let’s look at the most important files. The first one is
config.yaml (sometimes also called
config.toml) located in the main website folder. Find and open it. You will see that it lists as title Academic. Change that to e.g. Website of YOURNAME. You will see this change show up on the main site. You can try what happens if you write something in the
copyright section. The rest of this file doesn’t need further editing for now.
Let’s go into the
config/_default/ folder and open the
menus.toml file. You’ll see that those correspond to the menu buttons on the main page. Most of them don’t work since we removed the widgets. For now, let’s go ahead and disable (by placing
# symbols in front) all entries apart from the
Posts block of text.
params.toml. This file lets you specify and control a lot of things. Try setting a different theme. Then read through the other parts. We won’t change them for now, but you might want to come back to them.
Create new content
Let’s create a blog post. First, let’s move the
posts.md file back into the
home folder. If successful, you should see several blog posts show up on the site. The actual files containing those posts are in the
content/post folder. (Academic is unfortunately not very good about consistently using singular or plural). You will see one file (both
.html) in the main
/post folder. That file was placed there by RStudio/blogdown. You will also see several folders, each contain a
.md file and one or more images. Those are placed there by the creator of Academic. Both ways of placing blog posts is ok but separate folders tends to be more organized. Let’s first remove the existing posts. You can either delete them, or to be safe, move everything (apart from the
_index.md file) to the folder you created earlier. You should see all posts disappear from the main page.
Now let’s create our first blog post. We can use an RStudio addin for this. Since I have found that sometimes the
serve_site() command interferes with the addin functionality, let’s stop the serving (continuous building and displaying) of the website for now by restarting
Once you have restarted
R, go to the
Addins button (approximately under the
Tools button) and choose
New Post. Add a title for your blog post. You can leave all other settings as they are. At some point you will want to think more about the way you want to set up your website, including what kind of file format you want. See the More Information section below. For now, just give it a title and use the defaults for the rest.
Once you click
done, the file should open. You will see that the things you specified in the boxes show up in the YANL area. Write some text below that area (below the
---). The text you write should be formatted as (R)Markdown. For now, you can just write some plain text. Or try some Markdown formatting using the cheat sheet listed above.
Once you finished writing your new blog post, save your changes, then start the server again by re-loading the blogdown package (
library(blogdown)), then type
serve_site() into the
Congratulations, you have built a website and wrote a blog post! Of course there is a lot you can do next. Write more posts, look at all the different elements/widgets you can turn on and modify, etc. As mentioned, the Academic theme has a lot of features. If you like what you see, continue exploring. If you think you want something simpler, check out other Hugo themes until you find one you like, then customize it. A lot of things are very similar across all Hugo themes (e.g. the TOML/YAML bits and the folder structure), but some details differ, so it’s good to pick a theme before you really start customizing it.
But for now, we’ll leave it at this. There is one more crucial step missing though.
Making your website public
So far, everything happened on your local computer. In a final step, we want to put the website online so everyone can see it. With Netlify, this is fairly simple. Log into your Netlify account. Under
Sites, you should see a white box that says “drag and drop your site folder here”. Take the folder named
public inside your website folder and drag it into that box. If things work right, after a few seconds you should see that your site is deployed. It will have a weird name and a URL (mine when I tried it just now was called
https://cranky-lamport-fff53a.netlify.com/). Click on it and you will see your new website publicly online for everyone to see!
If you want, you can change the name of your site under
Site settings. More advanced (not free but also not too expensive and not that hard) is to get your domain name, e.g.
www.yourname.com or something like that.
If you want to add GitHub to the mix and have the deployment of your website automated, move on to part 2 of this post.
This post is just to get you up and running. If you like what you see and want to keep using blogdown/Hugo, you’ll likely need to learn more. There is a lot of good information on blogdown/Hugo/Academic available. I recommend the following:
- A short introductory course is Alison Hill’s summer of blogdown. Alison also has several blog posts on her website discussing Hugo and blogdown in a lot of detail, check out those materials.
- A lot of details and further information can be found in the blogdown book.
- For the Wowchemy theme, check out the docs for the theme. While they could be improved and at times a bit confusing, they are still a good source of information.
Further information and tutorials can easily be found with some online searching. Let me know if you find any especially helpful ones and I’ll add them here.