How to make this website

Sun, Feb 21, 2021 6-minute read


Motivation for Static Websites

The primary characteristics that make static websites convenient.

  • Simplicity



Overview of Components

Static website: All HTML files are served without any dynamic changes. This can make hosting & serving simple websites cheaper and faster.

Hugo: A static website generator that makes websites from md. documents.

Blogdown: An R package that connects Hugo to packages that can render .Rmd documents



Installation

https://bookdown.org/yihui/blogdown/installation.html

install.packages("blogdown")
library(blogdown)
blogdown::install_hugo()



Themes

https://bookdown.org/yihui/blogdown/other-themes.html

https://themes.gohugo.io/

Hugo generates sites using ‘themes’ aka rendering templates. There are many themes available on Hugo, however some of them must be modified to be rendered by rmarkdown. There is plenty of documentation if you find a theme that must be modified to work.

After choosing a theme you don’t need to install it by hand, it is better if you pass the theme name to the argument in blogdown::new_site( theme = "" ) or by building a new site in an RStudio project context (shown below).



Use this theme -> kakawait/hugo-tranquilpeak-theme

Some themes require tinkering to make them to work properly with blogdown or Netlify. A common issue is caused by themes using different directory tree structure. The blogdown -> Netlify website-workflow is popular, so there is ample help online. However you may have to dig into the CSS or try out many different changes to config.toml.



New Project

https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects

https://bookdown.org/yihui/blogdown/rstudio-ide.html

You don’t have to start a new project in R Studio to build a site, however it keeps everything much more organized if you do.

File -> New Project -> New Directory then select “Website using blogdown” This is where you can name your new directory and set your Hugo theme.

The blogdown author recommends enabling the option “Preview site after building” and disabling the option “Re-knit current preview when supporting files change”. To find those options look on R Studio under Tools -> Project Options...-> Build Tools




Blogdown to build the site

Build the site from scratch, all webpages will be rendered

blogdown::hugo_build() # You only need to do this once, afterwards use serve_site()


Make new pages or edit current pages

blogdown::new_post( title = "Page Title", author = "Sean", ext = ".Rmd")


Renders webpages that have been changed

blogdown::serve_site()



The project directory tree & config.toml

https://bookdown.org/yihui/blogdown/configuration.html#toml-syntax

Website-wide configuration can be done by modifying config.toml


The file config.toml is located in the project home directory along with the directories /static (where images and figures are stored) and /public (what blogdown generates)


Here is an example of my config.toml after some personal modifications and changes to use the theme “anatole”.

baseURL = "https://seandmcatee.netlify.app/"
languageCode = "en"
DefaultContentLanguage = "en"
title = "Website of Sean McAtee"
theme = "anatole"
# recommended ignoreFiles by blogdown
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_cache$", "\\.knit\\.md$", "\\.utf8\\.md$"]
summarylength = 10
enableEmoji = true
enableRobotsTXT = true

# Enable Disqus
#disqusShortname = ""

# Google Analytics
#googleAnalytics = "UA-123-45"

# Syntax highlighting
pygmentsUseClasses = true
pygmentsCodeFences = true
pygmentsCodefencesGuessSyntax = true

[params]
title = "Sean D McAtee"
author = "Sean D McAtee"
description = ""
profilePicture = "images/profile.jpg"
keywords = ""
favicon = "favicons/"
# example ["css/custom.css"]
customCss = []
# example ["js/custom.js"]
customJs = [] 
mainSections = ["post"]
images = ["images/site-feature-image.png"]
doNotLoadAnimations = false
# Form Spree Contact Form
#contactFormAction = "https://formspree.io/f/your-form-hash-here"
# Google Site Verify
#googleSiteVerify = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"

## Math settings
[params.math]
enable = false  # Enable math support globally, Can always enable math per page.
use = "katex"  # options: "katex", "mathjax". default is "katex".

## Social links
# use 'fab' when brand icons, use 'fas' when standard solid icons.
[[params.socialIcons]]
icon = "fab fa-linkedin"
title = "Linkedin"
url = "https://www.linkedin.com/in/sean-david-mcatee/"

[[params.socialIcons]]
icon = "fab fa-github"
title = "GitHub"
url = "https://github.com/smcatee/"

[[params.socialIcons]]
icon = "fas fa-envelope"
title = "e-mail"
url = "mailto:sean.d.mcatee@gmail.com"

## Menu items

[menu]

  [[menu.main]]
  name = "Portfolio"
  identifier = "home"
  weight = 100
  url = "/"

  #[[menu.main]]
  #name = "Posts"
  #weight = 200
  #identifier = "posts"
  #url = "/post/"

  [[menu.main]]
  name = "About Me"
  weight = 300
  identifier = "about"
  url = "/about/"

  #[[menu.main]]
  #name = "Contact"
  #weight = 400
  #identifier = "contact"
  #url = "/contact/"

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

[permalinks]
    post = "/:year/:month/:day/:slug/"



GitHub to host the site

https://github.com/

https://www.netlify.com/ # can use GitHub account to sign up for Netlify


On GitHub create a new public repository for you project.

# Some reminders, make sure you know what these git commands do.
git init
git add .
git status
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/your-username/repository-name.git
git push -u origin main



Netlify to serve the site

Now that your website is hosted on GitHub, Netlify can watch your GitHub repo for new commits.


Connecting GitHub to Netlify

New Site from Git -> Continuous Deployment [GitHub] -> Pick a Repository -> ...

Your default domain name will be <randomname.netlify.app>. Netlify provides free ‘.netlify.app’ domain names. There are options to purchase a custom domain name from Netlify or to use your custom domain name.



Update config.toml

Update the baseurl, title, and other site basics.


baseurl = "https://my-website.netlify.app/"

…

title = "Website of Sean McAtee"

…

ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_cache$", "\\.knit\\.md$", "\\.utf8\\.md$"]

…

[build.environment]
    HUGO_VERSION = "0.81.0"  # use blogdown::hugo_version()

…

[params]
title = "Sean D McAtee"
author = "Sean D McAtee"
description = ""
profilePicture = "images/profile.jpg"
keywords = ""
favicon = "favicons/"
# example ["css/custom.css"]
customCss = []
# example ["js/custom.js"]
customJs = []

…

[[params.socialIcons]]
icon = "fab fa-linkedin"
title = "Linkedin"
url = "https://www.linkedin.com/in/sean-david-mcatee/"

[[params.socialIcons]]
icon = "fab fa-github"
title = "GitHub"
url = "https://github.com/smcatee/"

[[params.socialIcons]]
icon = "fas fa-envelope"
title = "e-mail"
url = "mailto:sean.d.mcatee@gmail.com"



Render changes

Now blogdown generates menu items and connects other dots behind the scenes. The command serve_site will prepare the website and serve it locally. This command does the minimal amount of updating to generate the website, unlike build_site which will generate the whole site from scratch.

blogdown::serve_site()



Don’t forget to commit & push to GitHub first!

git add .
git status
git commit -m "updated baseurl"
git push -u origin main



Check out what you’ve made!

Now wait a few seconds, check your Netlify website, fix bugs, edit CSS, make a new posts, get inspired.