class: center, middle, inverse, title-slide # Making Websites with R Markdown and blogdown ### <a href="https://yihui.org">Yihui Xie, RStudio</a> ### 2017/05/24 @ An RStudio Webinar --- # 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**. .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). --- # A quick test on whether you have any website experience .pull-left[  ] .pull-right[  ] --- # blogdown: yet another tool?! .center[] ??? If you judge blogdown from the appearance of the websites that it creates, you may think, "What's the point of another tool for building websites? We have got plenty! WordPress, Tumblr, Medium.com, etc. We can create pretty much everything we want there: the navigation menu, sidebar, content, footer, and so on." --- # 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); helper function `blogdown::install_hugo()` - lightning fast (main reason why I switched from Jekyll to Hugo) - 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, Medium.com, Tumblr, 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. --- # How about Jekyll and other static site generators? - Jekyll is too slow for me and I don't enjoy the (Ruby gems) dependency hell, but we will support it anyway in the future - We have heard good words about [Hexo](https://hexo.io), too, and will try to support it, too - Unless you have strong reasons to go with other generators (I'd love to know them), we recommend you to stay with Hugo -- - Sometimes I feel I'm just like an R Markdown virus --- # Get started - If you use RStudio, create a new empty project; if not, `setwd()` to an empty directory first. ```r devtools::install_github('rstudio/blogdown') # automatically install Hugo, create a site, download a theme, # add sample posts, and start a local web server blogdown::new_site() ``` - If you have RStudio [>= v1.1.28](https://dailies.rstudio.com) (currently daily versions), you can create a website project via `File -> New Project`. --- # 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 --- background-image: url(https://images.unsplash.com/photo-1424460421773-58b49adfc68a?dpr=2&auto=format&fit=crop&w=1500&h=1000&q=80&cs=tinysrgb&crop=) background-size: cover class: inverse # blogdown internals - blogdown &approx; Hugo + R Markdown - Hugo can only process Markdown; R Markdown is prebuilt to `.html` and passed to Hugo - a few helper functions - `new_site()` creates a new website - `install_hugo()` / `install_theme()` - `serve_site()` rebuilds and live reloads a website on changes (RStudio addin "Serve Site") - `new_post()` creates a new post under `content/post/` and automatically fills out some YAML metadata (title, author, date, ...) - output format: `blogdown::html_page` - built on top of `bookdown::html_document2`, so most [**bookdown**](https://bookdown.org) features are also available in **blogdown** --- # RStudio IDE support - Addins - "Serve Site" (may need `options(servr.daemon = TRUE)`) - "New Post" - "Update Metadata" - New website project (only available in daily build) - 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 ??? If you do not see the addins, you need to update your RStudio IDE. --- # What if I have already got a website? - Jekyll - if you can find a Hugo theme (https://themes.gohugo.io) that you are satisfied with, the migration will be easy, since both Jekyll and Hugo use Markdown, but you may need to clean up the YAML metadata of your posts - "Simply Statistics" took me five hours in total: https://simplystatistics.org/ - otherwise the effort may not be trivial, because you have to rewrite your Jekyll theme using the Huge templating language - WordPress - Export all your posts to XML, and use the Python tool Exitwp: https://github.com/thomasf/exitwp - Exitwp converts WordPress to Jekyll, which will bring you much closer to Hugo ??? It took me a week to migrate several of my Jekyll websites and merge them into one Hugo-based website. --- # Publishing / Deployment - Many possibilities, but I'll mention only one today - No, I don't recommend Github Pages - Netlify is the new and much more flexible Github Pages ^* - Hugo support (among other static site generators) - Free CDN - Bind your own custom domain for free, and also enable HTTPS for free - Flexible redirect rules - Continuous deployment - Unique preview URL for each Github pull request .footnote[ [*] Disclaimer: they didn't pay me to say this. ] --- # 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 - The spirit: we help you set up your website, and hope you could help someone else in the future after you learn more about all the technologies (no obligation) - We are still waiting for more volunteers to join Rbind, so please **do not tweet anything about it** at this moment, otherwise we may run out of human resources --- # 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! - 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 - not on CRAN yet but should be mature enough now ^* - incomplete documentation (as a book based on **bookdown**) at https://bookdown.org/yihui/blogdown .footnote[ [*] The major things that are holding me back are (1) I'm not totally satisfied with the support for HTML widgets, and (2) the documentation is still incomplete --- there is just way too much to write. ] --- # Enjoy blogdown and your website! .center[] --- # Questions? I think I can only manage to answer a few of them here. If your question is not answered, please consider asking on StackOverflow with the tags `r` and `blogdown`: https://stackoverflow.com/tags/blogdown Yes, I read every single question with one of these tags on StackOverflow: `knitr`, `bookdown`, `blogdown`, `dt`, and so on, although obviously I cannot answer every single one. .center[]