class: center, middle, inverse, title-slide # Creating Websites with R Markdown and blogdown ## c(‘workflow’, ‘tricks’, ‘thoughts’) ### <a href="https://yihui.org">Yihui Xie</a> ### 2018/02/02 @ rstudio::conf 2018, San Diego --- class: center # No GIFs today --  ??? Those who are familiar with my presentation style may be expecting GIFs now, but I decided not to use GIFs this time. To emphasize this point and thoroughly disappoint you, I'll use a GIF to help you remember it. I'm done with the GIF business now. --- class: inverse, center, bottom background-image: url(https://github.com/yihui/xaringan/releases/download/v0.0.2/karl-moustache.jpg) background-size: contain ## One Karl Broman is worth a thousand GIFs I used my **xaringan** package to create the slides, which has an option `yolo: true` dedicated to the Mustache Karl (TM). Read [this post](https://yihui.org/en/2017/08/why-xaringan-remark-js/) later for the background story. ??? But I didn't say I wouldn't use any pictures. Apologies for this kind of "inside joke". --- # Two books that influenced me most in 2017 .pull-left[ [](https://en.wikipedia.org/wiki/Amusing_Ourselves_to_Death) ] .pull-right[ [](https://www.poorcharliesalmanack.com) ] ??? We should try to sit down and write something without the distraction of social media. I don't have strong self-discipline, so I installed a Chrome extension "StayFocusd" to limit my social media time to 10 minutes per day. I made about 140 notes while reading "Poor Charlie's Almanack". This book is full of wisdom (in particular, about psychology). We may never be as wise as Charlie Munger, but I believe we will be closer to him if we write down our thoughts, even if they are naive in the beginning. The next book I'm interested in is Ray Dalio's "Principles". I have only read the preface, where he emphasized the importance of writing down your principles. --- class: center background-image: url(https://unsplash.com/photos/yjTxnh7bsdw/download?force=true) background-size: cover # blogdown ### https://github.com/rstudio/blogdown  --- background-image: url(https://unsplash.com/photos/i1x2BO7CSBI/download?force=true) background-size: cover # Organize your R Markdown documents If you have used R Markdown before (<http://rmarkdown.rstudio.com>), you probably work with single documents most of the time: Knit a single document, and get a single output file. You may end up with messy Rmd files everywhere and it is hard to navigate through them. Currently two ways to organize your Rmd files: [blogdown](https://github.com/rstudio/blogdown) (casual) and [bookdown](https://github.com/rstudio/bookdown) (serious). --- # Getting started - With [the latest version of RStudio](https://www.rstudio.com/products/rstudio/download/), create a website project via `File → New Project`. - No RStudio? Fine. ```r blogdown::new_site('path/to/an/empty/directory') ``` - Behind the scenes: download Hugo (a static website generator), download a default theme, add some example pages, build the site, and preview it. ??? **The curse of being knowledgeable**: The more you know about websites, the longer it may take for you to get started. Because (1) you may have an existing website to migrate, and migrating to **blogdown** typically means moving from a more complicated system to a much simpler system (Markdown-based).; (2) you may spend a huge amount of time on tweaking your theme (CSS, Hugo templates, etc). --- # Work with the RStudio IDE (demo) - Create a new website project - RStudio addins - "Serve Site" (live preview and reload-on-change) - "New Post" - "Update Metadata" - A typical workflow - Open your website project, click the "Serve Site" addin (only once) - 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. --- # The 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, ...) --- # Themes - A new site uses the hugo-lithium theme by default - Try other themes, e.g., - [yihui/hugo-xmin](https://github.com/yihui/hugo-xmin) ([Section 2.5](https://bookdown.org/yihui/blogdown/templates.html) in the **blogdown** book) - [gcushen/hugo-academic](https://github.com/gcushen/hugo-academic) - 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 bored by your favorite theme someday, no matter how good it looks for now --- # Publishing a website - 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 ([why HTTPS](https://https.cio.gov/everything/)) - Flexible (301/302) redirect rules ([why is this important](https://yihui.org/en/2017/11/301-redirect/)) - Two methods: 1. Direct upload 1. Continuous deployment through Github --- class: inverse, center background-image: url(gif/disguised-cat.jpg) background-size: contain # Some less well-known features --- # blogdown also supports Jekyll and Hexo Although the support is limited compared to Hugo... In particular, Pandoc and HTML widgets are not supported. --- # Render to arbitrary output formats By default, posts and pages are created under `content/`, and the only possible output format for these source documents is HTML. But you may want other formats, e.g., PDF, Word, slides, and so on. The answer is use the `static/` folder. ```md content/ | |-- ... R/ | |-- build.R # blogdown::build_dir('static') static/ | |-- report.Rmd # output: pdf_document |-- slides.Rmd # output: ioslides_presentation public/ | |-- report.pdf |-- slides.html ``` --- # Render to arbitrary output formats The output files will not be automatically displayed on your website, and they are orthogonal of your Hugo website. You have to link to them in source files under `content/`. For example, ```md content/ | |-- 2018-02-02-a-blog-post.md ``` The content of the post: ```yaml --- title: "Announcing an important discovery" date: "2018-02-02" --- ``` ```md Today we made an important discovery. For the full report, please see [this PDF document](/report.pdf). ``` More info in [Section 2.7](https://bookdown.org/yihui/blogdown/static-files.html) of the **blogdown** book. --- # The *.Rmarkdown source document format Typically you use the extension `*.Rmd` for R Markdown documents, but for **blogdown**, there is another extension `*.Rmarkdown`. Main differences: - `*.Rmd` → knitr + Pandoc → `*.html` - Pandoc's Markdown is much more powerful - `*.html` may look ugly in version control (a lot of HTML tags) - `*.Rmarkdown` → knitr → `*.markdown` - Eventually `*.markdown` → Hugo → `*.html` - Hugo's Markdown features are limited, but `*.markdown` looks cleaner in version control If you don't care about "cleanness" of output files under `content/` in version control, just use `*.Rmd`. A use case of `*.Rmarkdown`: review Github pull requests. --- # options(blogdown.generator.server = TRUE) Hugo is fast. You are likely to be satisfied by the speed of the live preview via `Serve Site` (or `blogdown::serve_site()`). But live preview can be (a lot) faster. It may just take 10 milliseconds to re-render the site, if you install the **processx** package, and set an option in R: ```r options(blogdown.generator.server = TRUE) ``` By default, **blogdown** renders the full site to disk on changes and reload it in your browser, which may take one or two seconds. If you set this option, **blogdown** will take advantage of Hugo's own server (via the command `hugo server`), which is much faster. --- # hugo server --navigateToChanged Even more awesome if you _also_ set the option `blogdown.hugo.server`: ```r options( blogdown.generator.server = TRUE, blogdown.hugo.server = c('-D', '-F', '--navigateToChanged') ) ``` This means whenever you edit and save a source file, Hugo will automatically navigate to the page corresponding to this file, no matter which page you are currently on. Note: if you see a 404 error in RStudio Viewer, just refresh the viewer. -- These are the options [I set for my personal website](https://github.com/rbind/yihui/blob/master/.Rprofile).^* .footnote[ [\*] You paid $600 to come to this talk, and I think these two options are worth $580. ] ??? Many people are obsessive with hitting Ctrl + S or Command + S every few seconds. Every time you save a file, these options will save you about 2 seconds to see the preview. --- class: inverse, bottom background-image: url(https://github.com/yihui/xaringan/releases/download/v0.0.2/karl-moustache.jpg) background-size: contain # Smilence --- # options(blogdown.title_case = TRUE) ## [Tiny wins](http://joelcalifa.com/blog/tiny-wins/) When this option is set, your post title will be automatically converted to title case when you use the "New Post" addin or `blogdown::new_post()`.^* Credit: `tools::toTitleCase()` Note: this requires `devtools::install_github('rstudio/blogdown')` (I added this feature on Tuesday while working on my slides). .footnote[ [\*] This option is worth the rest $20. Good for your little fingers (no need to press Shift). ] ??? R is a language for statistical computing and graphics, and English grammar. --- class: inverse, bottom background-image: url(https://github.com/yihui/xaringan/releases/download/v0.0.2/karl-moustache.jpg) background-size: contain # Holy cow ??? I'm not using a GIF. I'm just pressing M on my keyboard. --- # Let me write a blog post here at the podium I don't have a lot of time, but I can type pretty fast!!^* I'll also answer Brandon's question in this post. <blockquote class="twitter-tweet" data-conversation="none" data-lang="en"><p lang="en" dir="ltr">Does yolo:true work in blogdown?</p>&mdash; Brandon Hurr (@bhive01) <a href="https://twitter.com/bhive01/status/958543255955693574?ref_src=twsrc%5Etfw">January 31, 2018</a></blockquote> .footnote[ [\*] Sorry, I cheated (with HHKB). For the truth, see [the blog post](https://yihui.org/en/2018/02/typing-fast/) I published from the podium. ] --- class: inverse, center background-image: url(https://cdn.shopify.com/s/files/1/0070/7032/files/darth_wat_grande.jpg) background-size: contain # Some non-technical stuff --- # Why blogdown? - R Markdown <img src="https://www.rstudio.com/wp-content/uploads/2015/12/RStudio_Hex_rmarkdown.png" width="10%" align="right" /> 1. (relatively) simple syntax for writing documents 1. the simpler, the more portable (not only HTML output, but also PDF, Word, EPUB, etc, thanks to Pandoc) 1. not only convenient (maintenance), but also reproducible 1. 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" /> 1. free, open-source, and easy to install (a single binary) 1. lightning fast (generates one page in one millisecond) 1. 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, 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, and I really hate dealing with security issues ??? 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. --- # Why should you have a website? - I web, therefore I am ~~a spiderman~~. ^* -- - Save the time of repeating things to different people (e.g., making self-introduction at conferences). -- - 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 / talk and forget; write and remember! - I wrote a large amount of garbage over the ten years, 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. .footnote[ [\*] From the preface of the **blogdown** book. ] ??? - 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! - I was really naive and arrogant in some old posts. Should I have access to a time machine, I might go back and kill my younger self. --- class: center # Everything is in the documentation [](https://bookdown.org/yihui/blogdown/) Also see the R package documentation of **blogdown**, e.g., `?blogdown::new_post`. ??? Please read at least the Chapter 1. I have seen several users ask questions about blogdown on Twitter. It seems they didn't bother reading the free book at all, and would rather make blind and random attempts. This makes me feel heartbroken. --- class: center, inverse  ## Debugging CSS, van Gogh (1890) ??? I don't want to mislead you. It is not always the bright side. There is a dark side when playing with websites. --- # Thanks! - Slides: [bit.ly/2018-blogdown](https://bit.ly/2018-blogdown) - Questions: [StackOverflow](https://yihui.org/en/2017/08/so-gh-email/) (with tags `r` and `blogdown`), or RStudio Community (https://community.rstudio.com). - Now let me check if my post is live on my personal website https://yihui.org.