Creating a Blog

Create a blog to publish a collection of Radix articles

Table of Contents


Radix websites include integrated support for blogging. To create a blog you author a collection of posts (located in the _posts subdirectory of your website) and then dedicate a page (usually the website homepage) to a listing of all of your posts.

Getting started

Creating a blog

If you are using RStudio, the easiest way to get started is to use the Radix Blog option in the RStudio New Project dialog:

A new RStudio Project for the blog will be created and opened. The blog will include the following files:

Option Description
_site.yml Website configuration file.
index.Rmd Blog home page.
about.Rmd Blog about page.
_posts/welcome/welcome.Rmd Welcome post for the blog.

Note that the welcome post is just there to provide some skeletal content for the blog – feel free to delete it and add your own initial post to the blog as described in creating a post.

If you are not using RStudio you can also call the Radix create_blog() function:


library(radix)
create_blog(dir = "my-blog", title = "My Blog")

The basic scaffolding for a blog and an initial welcome post will be created within the my-blog sub-directory.

Configuration

After you’ve created the blog scaffolding, there are a couple of additional configuration items you’ll want to add to your _site.yml so that it’s easier to share content on the blog via RSS and social networks like Twitter:

For example:

_site.yml


name: "reproducible-finance-with-r"
title: "Reproducible Finance with R"
description: |
  Exploring reproducible finance with the R statistical 
  computing environment.
base_url: https://beta.rstudioconnect.com/content/3776/
navbar:
  logo: images/rstudio.png
  right:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html
    - text: "Contributors"
      href: contributors.html
    - icon: fa fa-rss
      href: index.xml
output: radix::radix_article

Note that we’ve also added a feed icon to the right side of the menu bar which makes it easy to discover and browse the RSS feed for the blog.

Creating a post

The easiest way to start authoring a new post is to call the create_post() function from within your blog’s directory. For example:


library(radix)
create_post("The Sharpe Ratio")

This will create a sub-directory for your post within the _posts directory, add a stub Radix article, and open the article for editing.

If you want your post to start out as a draft (i.e. not be included within the listing of all posts) then you can add draft = TRUE. For example:


create_post("The Sharpe Ratio", draft = TRUE)

You work on blog posts independent of the enclosing website (use Knit to render and preview the post just like any R Markdown document). This is in fact the only way to update post content — posts are considered standalone documents that are not re-rendered when the site is built. This is because posts are often expensive to render and have R package dependencies that may be difficult to satisfy as time goes on.

In the next section will describe how to create a listing page for all of your posts.

Listing pages

Once you have authored one or more posts you’ll want to create a listing page. You can do this by adding a listing metadata entry to the page you to include the listing on. This is often the main page for the website (index.Rmd). For example:

index.Rmd


---
title: "Reproducible Finance with R"
site: radix::radix_website
listing: posts
---

In our example blog (which will be described in more detail below) this results in the following listing:

Categories

If your posts include categories metadata, then the page will also include category links to the right of the article listing. For example, here is some post metadata that includes categories:


---
title: "The Sharpe Ratio"
# (additional metadata e.g. description and date, excluded for brevity)
categories:
  - portfolios
  - dygraphs

As a result of including categories, the listing page now looks like this:

RSS feeds

When you create a listing page an RSS feed is created automatically for the page (using the name of the listing page with a .xml file extension). You can link to the RSS feed within your site’s navigation bar as follows (some navbar entries excluded for brevity):

_site.yml


name: "reproducible-finance-with-r"
title: "Reproducible Finance with R"
description: |
  Exploring reproducible finance with the R statistical 
  computing environment.
base_url: https://beta.rstudioconnect.com/content/3776/
navbar:
  right:
    - icon: fa fa-rss
      href: index.xml
output: radix::radix_article

Note that the description and base_url fields are both required to generate an RSS feed.

By default the most recent 20 articles will be included in the RSS feed. You can change this by specifying feed_items_max within the collection configuration in _site.yml (navbar and output format fields omitted for brevity):

_site.yml


name: "reproducible-finance-with-r"
title: "Reproducible Finance with R"
description: |
  Exploring reproducible finance with the R statistical 
  computing environment.
base_url: https://beta.rstudioconnect.com/content/3776/
collections:
  posts:
    feed_items_max: 50

Specify feed_items_max: false to have no limit on the number of items included in the feed.

Post drafts

If you want to work on a post for a period of time without having it be added to the listing page, add draft: true to the post’s metadata. For example:


---
title: "The Sharpe Ratio"
description: |
  In this post we present a classic finance use case using the
  PerformanceAnalytics, quantmod, and dygraphs packages. 
  We'll demonstrate importing stock data, building a portfolio,
  and then calculating the Sharpe Ratio. 
draft: true
---

When you are ready to publish the post, either remove the draft option or set it to false, then build the website.

Beyond support for drafts, Radix has a number of additional features to accommodate a variety of post authoring and contribution workflows, including importing posts published elsewhere on the web (e.g. on RPubs, in a Git repository, or on another blog). The article on blog post workflow describes these options in more detail.

Next steps

Comments and sharing

Readers will likely want to comment on and share articles they read on your blog. You can enable support for Disqus comments and sharing links for Twitter, LinkedIn, and other services by adding options to the collection:posts section of _site.yml.

For example, the following options provide the Disqus shortname for a site and specify that we want sharing buttons for Twitter and LinkedIn.

_site.yml


name: "reproducible-finance-with-r"
title: "Reproducible Finance with R"
description: |
  Exploring reproducible finance with the R statistical 
  computing environment.
base_url: https://beta.rstudioconnect.com/content/3776/
collections:
  posts:
    disqus: reproducible-finance-with-r
    share: [twitter, linkedin]

The following footer is then automatically included at the end of each post:

Note that the base_url field is required in order to use Disqus and sharing links.

Valid values for the share option are twitter, linkedin, facebook, google-plus, and pintrest.

Organizing posts

You can use whatever scheme you like to organize the _posts directory. You can have all posts at the top level or you can create subdirectories to create groupings of posts.

One popular scheme for organizing blog posts is to use a date prefix for the post directory names. For example:


_posts/
  2017-11-09-visualizing-asset-returns/
  2017-09-13-asset-volatility/
  2017-03-07-quandl-and-forecasting/
  2016-11-08-sharpe-ratio/

The benefits of this scheme are that post names are given additional uniqueness (to guard against colliding names over the long term) and are also automatically listed in order when browsing the _posts directory.

Note that if you use a date-prefixed post directory you are not required to specify an explicit date field within your post’s metadata.

Preview images

Note that the listing for our example above includes a preview image for each post. Preview thumbnail images are generated automatically based on the first plot encountered within your post. You can specify that a specific plot should be used as the preview image using the preview chunk option. For example:


```{r, layout="l-body-outset", preview=TRUE}
library(ggplot2)
ggplot(diamonds, aes(carat, price)) + geom_smooth() +
  facet_grid(~ cut)
```

If you want to use another image entirely as a post preview you add a preview field to the post’s metadata. For example, here we add a preview field to the example metadata from above (some fields excluded for brevity):


---
title: "The Sharpe Ratio"
description: |
  In this post we present a classic finance use case using the
  PerformanceAnalytics, quantmod, and dygraphs packages. 
  We'll demonstrate importing stock data, building a portfolio,
  and then calculating the Sharpe Ratio. 
preview: images/sharpe-ratio.png
---

Preview images are also used for generating Open Graph and Twitter Card metadata. However, since those systems require that preview images be specified as absolute URLs, you also need to add a base_url field to your _site.yml file as describe above in Getting Started.

Citations

If your _site.yml file provides a base_url field, then an article citation appendix and related metadata will be included automatically within all published posts. For example:

If you want to disable this behavior you can use the collections:posts:citations field within _site.yml. For example:

_site.yml


name: "reproducible-finance-with-r"
title: "Reproducible Finance with R"
description: |
  Exploring reproducible finance with the R statistical 
  computing environment.
base_url: https://beta.rstudioconnect.com/content/3776/
collections:
  posts:
    disqus: reproducible-finance-with-r
    share: [twitter, linkedin]
    citations: false

Subscriptions

You can add HTML that enable readers to subscribe to your blog by including the collections:posts:subscribe option within _site.yml. The subscribe option in turn points to an HTML file that provides the ability to subscribe to your blog. For example:

_site.yml


name: "reproducible-finance-with-r"
title: "Reproducible Finance with R"
description: |
  Exploring reproducible finance with the R statistical 
  computing environment.
base_url: https://beta.rstudioconnect.com/content/3776/
collections:
  posts:
    disqus: reproducible-finance-with-r
    share: [twitter, linkedin]
    subscribe: _subscribe.html

_subscribe.html


<form method='post' action='https://blogtrottr.com'>
  <p>Enjoy this blog? Get notified of new posts via email:</p>
  <input type='text' name='btr_email' />
  <input type='hidden' name='btr_url'
         value='https://beta.rstudioconnect.com/content/3776/index.xml'/>
  <input type='hidden' name='schedule_type' value='0' />
  <input type='submit' value='Subscribe' />
</form>

This example uses the Blogtrottr service to provide an email subscription. You could also use another service or simply include a link to your RSS feed.

The contents of _subscribe.html will be included in both the sidebar of the main listing page as well as in the footer of articles. Note that relative URLs won’t work in subscription HTML since the content appears at different levels of the site (thus we include the full URL to the RSS feed in the example above).

Supporting files

When a blog post is published, resource files located alongside the post in its directory are also published. The following files are not published by default:

  1. Files beginning with "." (hidden files).

  2. Files beginning with "_"

  3. Files known to contain R source code (e.g. ".R", ".s", ".Rmd"), R data (e.g. ".RData", ".rds"), or configuration data (e.g. "rsconnect" ,"packrat")).

You can override this behavior using a resources metadata entry for your post, which can specify explicit files to include or exclude. For example (some fields excluded for brevity):


---
title: "The Sharpe Ratio"
description: |
  In this post we present a classic finance use case using the
  PerformanceAnalytics, quantmod, and dygraphs packages. 
  We'll demonstrate importing stock data, building a portfolio,
  and then calculating the Sharpe Ratio. 
resources:
  exclude:
    *.csv    
---

Publishing a blog

After you’ve authored one or more posts you will want to build the entire site before publishing it.

If your Radix website is contained within an RStudio project you can use the Build Website command available in the Build pane to generate the site:

To build a website from the command line, use the rmarkdown::render_site() function:


library(rmarkdown)
render_site()

There are a variety of options available for making your site available to others, see the article on website publishing for details.

Examples

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/radixpub/radix-r, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".