class: center, middle, inverse, title-slide # DIY Your Personal Academic Website with blogdown ## I web, therefore I am ### <a href="https://yihui.org">Yihui Xie</a> ### 2017/09/27 @ University of Nebraska-Lincoln --- # Software setup Slides at: [bit.ly/unl-blogdown](http://bit.ly/unl-blogdown) (Don't type the code below. Copy from slides instead.) 1. Install R if you haven't: https://cran.rstudio.com; 1. Install the **blogdown** package in R: ```r if (!require('devtools')) install.packages('devtools') devtools::install_github('rstudio/blogdown') ``` If the above code does not work, try this instead: ```r install.packages('blogdown') ``` 1. Install Hugo: `blogdown::install_hugo()`; 1. (Optional but recommended) Install the [RStudio preview version](https://www.rstudio.com/products/rstudio/download/preview/); 1. (Optional) Install GIT: https://git-scm.com/downloads. --- # If you don't have experience with building websites, great! Follow a few simple steps, and you can have a website up and running in a few minutes. -- .center[] --- # However, if you do... It may take you several days before you can actually use **blogdown**, because you may look at too many things on a page and want to customize them. -- .center[] ??? Because (1) you may have an existing website to migrate; (2) you may spend a huge amount of time on tweaking your theme (CSS, Hugo templates, etc). --- class: center .pull-left[  ] .pull-right[  ] ### A quick test on whether you have any experience with building websites --- # What is blogdown, and why? - An R package based on [R Markdown](https://rmarkdown.rstudio.com) and [Hugo](https://gohugo.io) - R Markdown <img src="https://www.rstudio.com/wp-content/uploads/2015/12/RStudio_Hex_rmarkdown.png" width="10%" align="right" /> - (relatively) simple syntax for writing documents - the simpler, the more portable (not only HTML output, but also PDF, Word, EPUB, etc, thanks to Pandoc) - not only convenient (maintenance), but also reproducible - most features of R Markdown _and_ [**bookdown**](https://bookdown.org) (technical writing)!! - Hugo <img src="https://gohugo.io/img/hugo.png" width="10%" align="right" /> - free, open-source, and easy to install (a single binary) - lightning fast (generates one page in one millisecond) - general-purpose (not only for blogs) ??? Pandoc's Markdown: paragraphs, section headings, (un)numbered lists, blockquotes, math expressions, tables, images, footnotes, bibliography/citations, ... See Chapter 2 of the **bookdown** book for additional Markdown features, such as figure/table captions, cross-references, numbered equations, theorems, ... --- # Why not WordPress, Tumblr, Medium.com, Blogger.com, etc? - No R Markdown support (even math support is often nonexistent or awkward) - Huge benefits of static websites compared to dynamic websites - all static files, no PHP or databases, no login/password, work everywhere (even offline) - typically fast to visit (no computation needed on the server side), and easy to speed up via CDN - Personal experience (I've been blogging since 2005) - I've uesd several PHP applications before, and I didn't feel I truly "own" a website until I switched to static sites - e.g. WordPress is open-source but still a big black-box to me ??? If all you want to write about is what you had for breakfast today, or how cute your kittens are, there is no need to use blogdown. If there is anything related to R, statistical computing, and/or graphics, blogdown will be much more convenient. --- # Get started - If you have RStudio [>= v1.1.28](https://www.rstudio.com/products/rstudio/download/preview/) (currently a preview version), you can create a website project via `File -> New Project`. - You can choose a Hugo theme (https://themes.gohugo.io). -- - You don't have to use RStudio: `setwd()` to an empty directory first, then run: ```r # automatically install Hugo, create a site, download a theme, # add sample posts, and start a local web server blogdown::new_site() ``` --- # A brief intro to a Hugo website - directory structure - `content/` - `about.md` - `post/` - `themes/`: there may be multiple themes - `static/`: everything is copied to `public/` - `public/`: the generated website that can be uploaded to any web server (Netlify, Github pages, Amazon S3, ...) - a Markdown file or an R Markdown file - YAML metadata (title, author, date, tags, ...) - body --- # Demo - The default new site - the hugo-lithium theme - Use other themes, e.g. - [jbub/ghostwriter](https://github.com/jbub/ghostwriter) - [gcushen/hugo-academic](https://github.com/gcushen/hugo-academic) - [kakawait/hugo-tranquilpeak-theme](https://github.com/kakawait/hugo-tranquilpeak-theme) - My advice on themes (you won't listen anyway): - you will naturually have strong desire for fancier themes, but I recommend you to try simpler themes in the beginning - spend more time on creating the content - you will be tired of your theme someday, no matter how good it looks for now --- # RStudio IDE support - Create a new website project - RStudio addins - "Serve Site" (set `options(servr.daemon = TRUE)` first) - "New Post" - "Update Metadata" - A typical workflow - Open your website project, click the "Serve Site" addin - Revise old pages/posts, or click the "New Post" addin - Write and save (take a look at the automatic preview) - Push everything to Github, or upload the `public/` directory to Netlify directly ??? If you do not see the addins, you need to update your RStudio IDE. --- # Publishing / Deployment - Many possibilities, but I'll mention only two today - Netlify is my favorite (https://app.netlify.com) - Hugo support (also other static site generators) - Free CDN - Free `*.netlify.com` subdomain - Bind your own custom domain for free, and also enable HTTPS for free - Flexible redirect rules - Two methods: 1. Direct upload 1. Continuous deployment through Github --- # Rbind - https://github.com/rbind - Welcome to Rbind if - you want to set up your website but do not know enough about web technologies such as how domain names work - or want a free subdomain `*.rbind.io` (I recommend you to register your own apex domain if you can afford it; it is fairly cheap) - or want to share your website source with other people --- # Two examples at UNL - Prof Andrew Tyre: https://drewtyre.rbind.io - Zhian N. Kamvar: https://zkamvar.github.io -- .center[] --- # Why should you have a website? - I web, therefore I am ~~a spiderman~~. ^* .footnote[ [\*] From the preface of the **blogdown** book. ] - Share what you have learned with other people, _and_ your future self! -- .center[] --- # Why should you have a website? - My first Chinese blog post was on Jan 7, 2005: https://yihui.org/cn/, and English post was on Aug 12, 2007: https://yihui.org/en/ The most important lesson I learned? - Listen / read / tweet and forget; write and remember! - I wrote a large amount of garbage and bullshit over the ten years (nearly a thousand posts), but I tend to think more deeply when I write something than when I talk or read. - Among all the garbage I produced, there might be a gem or two. - Not convinced? How about the book "[Amusing Ourselves to Death](https://en.wikipedia.org/wiki/Amusing_Ourselves_to_Death)"? ??? - Let other people know more about you. - I often flip through my own posts to find some tricks I learned but forgot. - My first English post was about tidying R code: https://yihui.org/en/2007/08/tidy-up-your-r-code/ The idea was turned into the **formatR** package, and I'm still maintaining it 10 years later! --- # Take-home message - You can find everything from the Github repo: https://github.com/rstudio/blogdown - including the documentation (as a book based on **bookdown**) at https://bookdown.org/yihui/blogdown --- # Enjoy blogdown and your website! .center[] --- class: center # Thanks! -- ## ...and I hope you can follow me to create your (new) website --  Slides created via the R package [**xaringan**](https://github.com/yihui/xaringan).