This repository contains the code for generating classtest.ryansafner.com. This is a minimal template for making my course websites, e.g. metricsf19.courses.ryansafner.com and microf19.courses.ryansafner.com, and is designed to be ported to make other course websites quickly.
This is heavily borrowed from the beautiful course websites of Andrew Heiss, including his ath-tufte-hugo_18-19
theme.
Instructions based on Alison Hill's excellent guide to setting up a website using blogdown. I assume you will use Netlify to deploy your website automatically from a GitHub repository, and then via your own hosting service, link your Netlify account to your hosted domain.
You will need a git client, GitHub account, and link your GitHub account to R Studio
. Follow Jenny Bryan's excellent guide.
-
Create a new repository on github
-
In your new repository, click the green Clone or Download button and copy the link
-
On your computer, navigate to a directory/folder where you will want to create a new directory/folder containing your website files. Once here, open a terminal/command prompt and type in
git clone the_link_from_step2
-
In
R Studio
, installblogdown
(install.packages("blogdown")
) if you don't already have it. -
Install Hugo via
blogdown::install_hugo()
-
Start a
New Project
inR Studio
fromExisting Directory
and then point it to the directory from Step 3. -
Edit your
*gitignore
file by adding a line with:public/
so that it will work with Netlify (here's why) -
Build your website with
blogdown::new_site()
in theR Studio
console- You may also want to change your project settings as described here
-
Copy/paste all the following files and folders from this repo into your new folder:
content/
,data/
,lib/
,pandoc/
,public/
,static/
,themes/
,config.yaml
,index.Rmd
(optional:README.md
andfavicon.ico
)- That is, DON'T copy the
.git
folder,.Rproj.user
folder,.gitignore
,.RData
,.Rhistory
,classwebtest.Rproj
, andindex.html
into the new directory - Also, DELETE
config.toml
- That is, DON'T copy the
-
Edit and build site at will, commit and push to GitHub, and you're at it!
This structure and theme seems to have a lot of additional bells and whistles beyond a typical Hugo site. Mainly, it seems to be pandoc
templates for sidenotes (a la Tufte) and citations. This part may require you to go down the rabbit hole and hack your computer just a little bit.
- Ensure you have the latest version of pandoc installed
- Install Pandoc sidenote (for converting footnotes to sidenotes).
- I use a Mac, so I use
brew install jez/formulae/pandoc-sidenote
in a terminal- By the way, for Macs, you should have homebrew installed, which requires command line tools in XCode (download XCode on the Mac App Store, and then install with
xcode-select --install
in a terminal)
- By the way, for Macs, you should have homebrew installed, which requires command line tools in XCode (download XCode on the Mac App Store, and then install with
- I use a Mac, so I use
This is the preferred method for painless deployment. Get an account at netlify.com.
- Create a new site and link it to your specific GitHub repository from Step 2 above (you may need to link Netlify to your GitHub account and grant it proper access)
- In the Build command field, type
hugo
- In the
Publish directory
field, typepublic
- Click to deploy your site
- In the Build command field, type
- Netlify automatically assigns you a
random_url.netlify.com
which it hosts. You can link it to a custom domain (e.g. I docoursename.courses.ryansafner.com
) by adding a domain- You will often have to configure the DNS records with your hosting website to make sure that it properly links to Netlify
- In my case, with justfivebuckshosting.com, adding a
CNAME
record with the custom netlify url as the value, plus a fewNS
records with the values given by Netlify, have proved sufficient
content
folder contains the following folders for making individual class-meeting-based webpages, each file should begin with##
for proper ordering- main level pages (that are on nav-bar):
syllabus
,schedule
,reference
, etc. assignment
: contains individual files for individual assignment pages (e.g. problem sets, exams)class
: contains individual files for individual class-meeting pagesreading
: contains individual files for describing individual class-meeting reading requirementspost
: if this were to ever contain a blog, blog posts would go here, etc
- main level pages (that are on nav-bar):
data
folder containslessons.yml
: a key file that populates a table of class meetings on theschedule
page. Links class meetings (rows of table) icons to individual assignment pages, class pages, and reading pages for each meeting
static
folder used for hosting files (e.g. datasets, handouts, images, etc)bib/references.bib
is where the references for citations (e.g. on syllabus, readings, etc) are stored
public
used for Netlify serving- other folders that are necessary, but should not be modified:
pandoc
stores templates needed for pagesthemes
contains the theme files, here calledath-tufte-hugo_18-19
based on Andrew Heiss'ath-tufte-hugo_18-19
theme
- Most of the course-level settings can be found in
config.yaml
, hopefully these should be obvious! - For each class meeting (edit in
data/lessons.yaml
), link to individual assignments and create pages for them incontent/
folder - Xaringan slides (which I use) require an additional setup, see below
- Adding a new column (course item, such as "Homework" or "Class Notes" or "Slides") to the table schedule page, go to
schedule.html
in (themes/ath-tufte-hugo_18-19/layouts/shortcodes/)
and add the following code (Substitute your actual name for my placeholder,THING
, below) - Note if you'd like to use a different font awesome icon (currently,fas fa-university
is used, copy/paste the html code wherever you see<i class="fas fa-university fa-lg"></i>
) - Essentially, the code below says "if there is a createdTHING
page in the/THING
folder for this class meeting, useICON
, otherwise, useICON
in the lighter colorf1f1f1
" .. the creation ofTHING
s in the/THING
folder is what Step 2 below is about.
{{- if .THING }}
<td align="center" style="width:10%;text-align:center"><a href="{{ .Site.baseurl }}/THING/{{ .THING }}/">
<i class="fas fa-university fa-lg"></i></a></td>
{{- else }}
<td align="center" style="width:10%;text-align:center"><font color="f1f1f1">
<i class="fas fa-university fa-lg"></i></font></td>
{{- end }}
- On
lessons.yaml
, add each individual element for each class as needed, e.g.THING: "01-THING"
- Place individual
01-THING.Rmd
files into aTHING
folder undercontent
to be linked to- The one exception is for Xaringan slides, which need to go under
static
to render properly, see below
- The one exception is for Xaringan slides, which need to go under
- Following Tim Mastny's Blog Post, create a
slides
folder understatic
folder - Place all Xaringan files in that folder (e.g custom css files)
- Knit the Xaringan
.Rmd
files to produce an html file (output) pulling css and other libs from this folder - Based on my Schedule page (see adding sections to schedule section), I have a link going to
/slides/
in the static folder for each class