<p><div><div><div><div data-show-faces="false" data-height="21" data-width="100" data-layout="button_count" data-send="true" data-href="https://www.r-bloggers.com/announcing-blogdown-create-websites-with-r-markdown/"></div></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="https://blog.rstudio.com/2017/09/11/announcing-blogdown/"> RStudio Blog</a></strong>, and kindly contributed to <a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers)</a> </div>
<p>Today I’m excited to announce a new R package, <strong>blogdown</strong>, to help you create general-purpose (static) websites with R Markdown. The first version of <strong>blogdown</strong> is available on CRAN now, and you can install it with:</p>
<pre><code>install.packages(&quot;blogdown&quot;)
</code></pre>
<p>The source package is hosted on Github in the repository <a rel="nofollow" href="https://github.com/rstudio/blogdown" target="_blank">rstudio/blogdown</a>. Since <strong>blogdown</strong> is a new package, you may install and test the development version using <code>devtools::install_github(&quot;rstudio/blogdown&quot;)</code> if you run into problems with the CRAN version.</p>
<h2>Introduction</h2>
<p>In a nutshell, <strong>blogdown</strong> is an effort to integrate R Markdown with static website generators, so that you can generate web pages dynamically. For example, you can use R code chunks (or <a rel="nofollow" href="http://rmarkdown.rstudio.com/authoring_knitr_engines.html" target="_blank">other languages</a> that <strong>knitr</strong> supports) to generate tables and graphics automatically on any web page. Before <strong>blogdown</strong>, you can easily do this using:</p>
<ul>
<li>the <strong>rmarkdown</strong> package to create single output files from R Markdown documents;</li>
<li>and the <a rel="nofollow" href="https://github.com/rstudio/bookdown" target="_blank"><strong>bookdown</strong></a> package to compile multiple R Markdown documents to a book;</li>
</ul>
<p>But the structure of a website can be far more complicated than a collection of independent HTML pages or a book. With <strong>blogdown</strong>, the directory structure of your R Markdown files can be arbitrary. You can easily create a project website, or a blog. Each page can have its own metadata (such as categories and tags), and you can generate pages of lists of content (such as a list of blog posts or examples).</p>
<p>Besides the advantage in website structures, another highlight of <strong>blogdown</strong> is that it inherited <strong>bookdown</strong>’s Markdown extensions (based on Pandoc’s Markdown), which means you can easily write technical content on your website, including everything that Pandoc supports (e.g., headings, lists, footnotes, tables, figures, citations, LaTeX math, and quotes, etc) and <strong>bookdown</strong>’s extensions (e.g., figure and table captions, cross-references, theorems, proofs, numbered equations, and HTML widgets, etc).</p>
<p>There are several popular static site generators, and the main one we support in <strong>blogdown</strong> is <a rel="nofollow" href="https://gohugo.io/" target="_blank">Hugo</a>. Hugo is easy to install (no dependencies), lightning fast (one millisecond per page), and very flexible. We have also provided (limited) support for <a rel="nofollow" href="https://jekyllrb.com/" target="_blank">Jekyll</a> and <a rel="nofollow" href="https://hexo.io/" target="_blank">Hexo</a> (see documentation). The Markdown support in these generators is often poor in terms of functionalities (you cannot easily beat Pandoc’s Markdown), and sometimes it is painful that they use different flavors of Markdown. With <strong>blogdown</strong>, you can use richer Markdown syntax if you want.</p>
<h2>Get Started</h2>
<p>It is extremely easy to get started with a new website. After you have installed the <strong>blogdown</strong> package, it only takes one step to create a new website—just call the function <code>new_site()</code> under an empty directory (or an empty RStudio project):</p>
<pre><code>blogdown::new_site()
</code></pre>
<p>It will download and install Hugo if it has not been installed, download a default Hugo theme, add some sample posts, build the site, and launch it in your web browser (or RStudio Viewer) so that you can immediately preview the website. Note you only need to use this function once for every new site. For an existing website, you may call <code>blogdown::serve_site()</code> or the RStudio addin “Serve Site” to preview the site; it will watch changes in your source files continuously and rebuild your site automatically.</p>
<p>To write new posts, you may use the RStudio addin “New Post”:</p>
<p><img alt="New Post" src="https://i0.wp.com/bookdown.org/yihui/blogdown/images/new-post.png?w=456&ssl=1" data-recalc-dims="1"></p>
<p>If you are not satisfied with the default theme, you can try to create another new site with <a rel="nofollow" href="https://bookdown.org/yihui/blogdown/other-themes.html" target="_blank">a different theme</a> till you find a theme that you like.</p>
<h2>Documentation</h2>
<p>The comprehensive documentation of this package is a book written in <strong>bookdown</strong>, which is freely available at <a rel="nofollow" href="https://bookdown.org/yihui/blogdown/" target="_blank">https://bookdown.org/yihui/blogdown/</a> and to be published by Chapman &amp; Hall later this year. The book may seem to be short (about 150 pages), but it contains many external resources, such as examples that we have spent a lot of time on creating. It may take you quite a while to fully digest this book, but perhaps it is not necessary. For example, you do not have to read Chapter 2 to understand how Hugo works if you can find a theme that you like and don’t want to customize too much (hint: this is unlikely—you will surely be bored by the appearance of your website someday). Anyway, you are expected to read at least Chapter 1 of this book.</p>
<h2>Migration</h2>
<p>If you don’t have a website right now, consider yourself to be lucky. It is much easier to start a new website than converting an existing website. The latter is not impossible, and we have shown in <a rel="nofollow" href="https://bookdown.org/yihui/blogdown/migration.html" target="_blank">Chapter 4</a> how to convert WordPress and Jekyll websites to Hugo. To give you an idea about how long it takes to convert a website:</p>
<ul>
<li>
<p>I spent a whole week on converting <a rel="nofollow" href="https://yihui.name/" target="_blank">my personal website</a> from Jekyll to Hugo. The complication was that I had a Chinese blog, an English blog, two project websites (<a rel="nofollow" href="https://yihui.name/knitr/" target="_blank"><strong>knitr</strong></a> and <a rel="nofollow" href="https://yihui.name/animation/" target="_blank"><strong>animation</strong></a>), and several single-page project websites (such as <a rel="nofollow" href="https://yihui.name/formatR/" target="_blank"><strong>formatR</strong></a>). Finally I managed to put all of them in <a rel="nofollow" href="https://github.com/rbind/yihui" target="_blank">one repository</a>.</p>
</li>
<li>
<p><a rel="nofollow" href="https://robjhyndman.com/" target="_blank">Rob Hyndman</a> spent several days on converting his WordPress website to <strong>blogdown</strong> (<a rel="nofollow" href="https://support.rbind.io/2017/05/15/converting-robjhyndman-to-blogdown/" target="_blank">read more here</a>), when the <strong>blogdown</strong> documentation was far from being complete (Chapter 4 did not exist).</p>
</li>
<li>
<p>It took me four hours to convert <a rel="nofollow" href="https://simplystatistics.org/" target="_blank">Simply Statistics blog</a> from Jekyll to <strong>blogdown</strong>. It had about 1000 posts at that time.</p>
</li>
<li>
<p>I have converted three WordPress sites by myself: <a rel="nofollow" href="https://rviews.rstudio.com/" target="_blank">the RViews blog</a> took me a few days, <a rel="nofollow" href="https://blog.rstudio.com/" target="_blank">the RStudio blog</a> took me one day, and <a rel="nofollow" href="http://kbroman.org/" target="_blank">Karl Broman</a>’s blog took me one hour.</p>
</li>
</ul>
<p>I have provided the scripts that I used in Chapter 4, and hopefully you can reuse them to convert your own websites to save you some time.</p>
<h2>Conclusion</h2>
<p>I believe <strong>blogdown</strong> can introduce a highly streamlined experience to create and maintain a website. At least I feel addicted to blogging again after three years. I have been a firm believer in writing, but I hated the fact that I had to log in an online system to write something (e.g., WordPress), or manually type out all the YAML metadata in a new post (which is why I created the RStudio addin “New Post”). Now I just need to open my RStudio project, use the “Serve Site” addin, then create a new post using the addin “New Post” or revise existing posts, and I can live preview the site immediately in RStudio Viewer when I save the post. Deployment of the website is as simple as pushing to Github, and <a rel="nofollow" href="https://www.netlify.com/" target="_blank">Netlify</a> will do the rest of work for me.</p>
<p><img alt="cats flow" src="https://i2.wp.com/slides.yihui.name/gif/cat-flow.gif?w=456&ssl=1" data-recalc-dims="1"></p>
<p>There are many advantages of static websites as mentioned in <a rel="nofollow" href="https://bookdown.org/yihui/blogdown/static-sites.html" target="_blank">Chapter 2</a> of the book. You whole website is just contained in a folder that you can preview locally (even offline!) or publish to any web server. Your posts are plain-text files that you can create or edit at any time, which means finally you have got something more meaningful to do <a rel="nofollow" href="https://twitter.com/imtaras/status/906392194012999680" target="_blank">on your next flight</a> than having to stare at Sudoku puzzles to kill time (you may teach your neighbors R Markdown and <strong>blogdown</strong> if they feel jealousy looking at your screen).</p>
<h2>Acknowledgements</h2>
<p>Although <strong>blogdown</strong> is still relatively new, I have received a lot of useful feedback during the development of the package and the book. There have been about 200 <a rel="nofollow" href="https://github.com/rstudio/blogdown/issues" target="_blank">Github issues</a> (including <a rel="nofollow" href="https://github.com/rstudio/blogdown/pulls" target="_blank">pull requests</a>) and a few dozen questions on <a rel="nofollow" href="http://stackoverflow.com/questions/tagged/blogdown" target="_blank">StackOverflow</a>. Some Github issues were really inspiring (e.g., <a rel="nofollow" href="https://github.com/rstudio/blogdown/issues/40" target="_blank">#40</a> and <a rel="nofollow" href="https://github.com/rstudio/blogdown/issues/97" target="_blank">#97</a>), and I was very glad that they filed the feature requests. I also want to thank <a rel="nofollow" href="https://github.com/rstudio/blogdown/graphs/contributors" target="_blank">those who</a> submitted Github pull requests to improve the book. To be honest, this book was quite painful to write, because there are too many technologies potentially related to a website (e.g., JavaScript, domain names, DNS, and continuous deployment). However, I have gained a lot of motivation and inspiration from several early brave users who created their websites and wrote their own <strong>blogdown</strong> tutorials (even before the official documentation existed). That is also <a rel="nofollow" href="https://bookdown.org/yihui/blogdown/author.html" target="_blank">how I found</a> the co-authors of this book, <a rel="nofollow" href="https://twitter.com/ProQuesAsker" target="_blank">Amber</a> and <a rel="nofollow" href="https://apreshill.rbind.io/" target="_blank">Alison</a>.</p>
<p>I’m particularly grateful to the feedback from beginners (so please don’t be shy to ask “dumb” questions). It is very helpful to see what can be confusing to beginners, so that we can try better explanations or implementations, which can usually benefit users of all levels.</p>
<p>If you are looking for inspirations from other people’s <strong>blogdown</strong>-based websites, you may thumb through the Github organization <a rel="nofollow" href="https://github.com/rbind" target="_blank">https://github.com/rbind</a>. You are also welcome to move your website over there to share with or inspire more people.</p>
<p>As usual, please feel free to ask questions on <a rel="nofollow" href="https://stackoverflow.com/questions/tagged/blogdown" target="_blank">StackOverflow</a> (with at least tags <code>r</code> and <code>blogdown</code>), and file bug reports and feature requests <a rel="nofollow" href="https://github.com/rstudio/blogdown" target="_blank">on Github</a>. I recommend you to spend some time on reading the <strong>blogdown</strong> book, but I understand it may not be easy to digest, so it is fine to ask questions before you finish reading the book. I’ll be happy to point you to the relevant sections if your questions have been answered in the book. I hope you can enjoy this package, and have fun with your website!</p>
	<p>
<div>
<div>To <strong>leave a comment</strong> for the author, please follow the link and comment on their blog: <strong><a href="https://blog.rstudio.com/2017/09/11/announcing-blogdown/"> RStudio Blog</a></strong>.</div>
<hr>
<a rel="nofollow" href="https://www.r-bloggers.com/">R-bloggers.com</a> offers <strong><a rel="nofollow" href="https://feedburner.google.com/fb/a/mailverify?uri=RBloggers">daily e-mail updates</a></strong> about <a rel="nofollow" href="https://www.r-project.org/" title="The R Project for Statistical Computing">R</a> news and <a rel="nofollow" href="https://www.r-bloggers.com/search/tutorial" title="R tutorials">tutorials</a> on topics such as: <a rel="nofollow" href="https://www.r-bloggers.com/search/data%20science" title="Data science">Data science</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/Big%20Data" title="Big Data">Big Data, <a rel="nofollow" href="https://www.r-users.com/" title="R jobs">R jobs</a>, visualization (<a rel="nofollow" href="https://www.r-bloggers.com/search/ggplot2" title="ggplot and ggplot2 tutorials">ggplot2</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/boxplot" title="Boxplots using lattice and ggplot2 tutorials">Boxplots</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/map" title="Maps and gis">maps</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/animation" title="Animation in R">animation</a>), programming (<a rel="nofollow" href="https://www.r-bloggers.com/search/RStudio" title="RStudio IDE for R">RStudio</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/sweave" title="Sweave and literate programming">Sweave</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/LaTeX" title="LaTeX in R">LaTeX</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/SQL" title="SQL and databases">SQL</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/eclipse" title="Eclipse IDE for R">Eclipse</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/git" title="git and github, Version Control System">git</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/hadoop" title="Large data in R using Hadoop">hadoop</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/Web+Scraping" title="Web Scraping of google, facebook, yahoo, twitter and more using R">Web Scraping</a>) statistics (<a rel="nofollow" href="https://www.r-bloggers.com/search/regression" title="Regressions and ANOVA analysis tutorials">regression</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/PCA" title="principal component analysis tutorial">PCA</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/time+series" title="Time series">time series</a>, <a rel="nofollow" href="https://www.r-bloggers.com/search/trading" title="finance trading">trading</a>) and more...
<img width="1" alt="" src="http://feeds.feedburner.com/~r/RBloggers/~4/a73Cxm4tNvU" height="1"></a></div>