How to build up this website?

Intro

The first (meaningful) post for this new website! After searching for many blog managers, I finally found out a cool and nice way to generate a good-looking website. The whole website is built under a R package blogdown, which is based on another pretty handy package rmarkdown that helps you markdown pdf or html file in Rstudio. blogdown employs a site generator called Hugo. With that, there are numerous themes developed by other Hugo users.

Some other features would be detailedly described in tutorials, here I wanna spent more time on the problems that I encountered during making the website.

Tutorials

Though now everything seems straightforward, it took me many hours to figure out how to make this website… Anyway, check these sources out!

  1. bookdown: Authoring Books and Technical Documents with R Markdown

A book from authors. I found the most useful section is the first few paragraphs introducing the package and ‘1.7 A recommended workflow’. The details are somehow not clear to me, because I had no experience building a website and Github. For people like me just starting to use github, I recommend the tutorials followed.

  1. Another tutorial (more pictures and workflow) from the author

I like the flowchart that this tutorial uses to decribe the workflow. More pictures, more intuitive.

  1. Tutorial for blogdown in Chinese (中文教學)

Found this one later after I have almost finished the whole website. It’s helpful if you read Chinese.

  1. Tutorial for using github with Rstudio

This one shows how to connect github with Rstudio. Also check out this one if you like more illustrationss. After downloading git, the simplest way to do this is as followed: create a github respository, copy the link, go back to Rstudio and create a R package under vision control, paste the link, and be happy. If you read Chinese, this website really helped me understand how git works.

Caveats I have jumped in

Belows are some caveats I have spent a lot of time troubleshooting.

1. Theme! Choose a well documented theme.

I chose hugo-academic for my website. One very first reason is the detailed description about each tunable feature. Another reason is intuitive: this website is designed for person in academics.

In the beginning, I browsed through all the themes and cannot make the choice. The first theme that I picked has elegant design and comfortable layout but shows very limited information about how to tune some of the features. So when the other coding/building problems came in, I did’t know where the problem was from. Be wise to choose a beautiful and well described theme.

2. Make sure you understand how git and github work, and how Rstudio interacts with them.

For people who have intensively used github, this might be trivial. But it was NOT trivial to me at all to understand how it works. It took me a while (maybe 0.5-1 hour reading about the introduction articles) to understand what git and github are, and how to push code from Rstudio to github.

Here are my understanding of these terms.

  • Rstudio: the interface for you to write r, rmd, and other codes.

  • git: a version control system for a team to track changes in code. Yes, a team. Now this is your personal website so that the only team member is you. Noted that it is possible to share the source code with other team members and co-manage the source code on github.

  • github: an online and open-source version of git. You need an github account to use blogdown.

  • Hugo: a site generator, like a witchcraft beautifying your website. I guess the reason that blogdown authors recommends Hugo is that there are many user-contributed themes available. Authors also provide the way to migrate from other site generators, such as Jekyll and WordPress.

  • netlify: deploys static website from your source code on github, and provides free domains (where your website will have a prefix “.name”). If you have registered a domain outside netlify for yourself, you could also customize your domain to what you like.

3. Some commands and steps only need to be done once.

For example, to initiate the website, you only need to go through the workflow below once:

  1. Connect Rstudio with github by createing a new project under vision control (you can see this option when creating a new R project: “Vision control”)

  2. Create a new website by the function blogdown::new_site(sample='TRUE', theme='hugo_academic'). It will create a skeleton under your project folder locally. You can change to a theme you like. The argument sample create a sample in /theme folder, which you can refer to in the future if you remove a feature and want it back again.

  3. Push code to github.

  4. Connect the /public folder in your github respository (not the local folder in your laptop) to netlify by simply dragging the folder to netlify. Set up deploy settings, check hugo version (see next caveat), and click deploy.

  5. Your website becomes alive!

Now this is the most important part. I say important because it took me hours to do silly things again and again without fully comprehension. To update the website, there are something you do or do not need to do.

Do to update

After initiating, in order to update the website, you edit the static website in Rstudio in your laptop. You will see the git window in Rstudio shows new “modified” items. blogdown will automatically update local /public (“local” means in your laptop) every time your save the .rm or .rmd file. When you update blogs locally, the only thing you need to do is to push the updated code (the whole folder of your website, although only github /public is used to deploy) to github, and wait for netlify to automatically deploy. It might take a few minutes for netlifly to deploy your website, but don’t worry – things getting simplier after the first try.

Don’t do it after website initiated

  • Don’t build the new site again by new_site().

  • Better not change the theme after editing on it. Stick to the theme you choose.

  • Don’t need to depoly manually after github connected to netlify.

  • Don’t manully deploy the website again on netlify.

4. Check Hugo version, and make sure it’s right in netlify

If you find netlify doesn’t deploy your website successfully (and comes in with error 255), it might be due to the Hugo version. Some themes are built under later Hugo version. Make sure you check the Hugo version that blogdown uses by the function blogdown::hugo_version(). Now the version is:

blogdown::hugo_version()
## [1] '0.37.1'

Go to netlify deploy setting / Build environment variables / Type in the key HUGO_VERSION and value 0.37.1.

5. There is updating problem with Chinese characters.

I have a stong incentive to write random stuffs in Chinese. There is problem updating the website locally in Rstudio Viewer when some Chinese characters showing in the website. I still don’t know why.

Related

comments powered by Disqus