Publish to WordPress directly from RStudio

The following piece of automation let me fall in love with R all over again: Publish a WordPress post directly from an R Markdown file! What's so great about that? Usually, I develop my analysis and visualizations in an RMarkdown file that I publish to Github (version control, code sharing—all the good reasons to use git).

Github is fantastic to share code, but it's not trivial to skim through a script and quickly understand what was done and how. Even with lots of comments, it will require dedication and time. However, A WordPress post about the analysis provides background, emphasizes only the interesting coding bits, provides visual results, and has a much higher likelihood to be found by other programmers.

Unfortunately, the above workflow separates the WordPress post from the underlying R script. Changing one part requires manually changing the other. The ability to have the raw code (posted on Github) and the WordPress post from a single source of truth (the R Markdown script) is a game-changer! Best of all, it's easy to set up, as we'll see below.

First, we set up a small R script (let's call it PublishPost.R) that will later publish the content (i.e., don't execute the script yet, that'll be the last step below).

# install the packages
if (!require('knitr')) {
  install.packages("knitr")
}
if (!require('devtools')) {
  install.packages("devtools")
}
if (!require('RWordPress')) {
  devtools::install_github(c("duncantl/XMLRPC", "duncantl/RWordPress"))
}

# load the packages
library(knitr)
library(RWordPress)

# provide credentials to your WordPress site
# i.e., replace with your WordPress user, password, and URL
options(WordPressLogin = c(YOUR_WP_USER_NAME = 'YOUR_WP_PASSWORD'),
        WordPressURL = 'YOUR_WORDPRESS_URL/xmlrpc.php')
# note the addition of /xmlrpc.php to the URL

# call the function that publishes the specified file
knit2wp('TITLE_OF_FILE_YOU_WANT_TO_PUBLISH.Rmd',
        title = 'TITLE OF YOUR WP POST',
        publish = FALSE,
        action = "newPost")

The first lines, load the three R packages that pull everything off: Duncan Temple Lang developed RWordPress. William K. Morris, Yihui Xie, and Jared Lander developed the knit2wp function in knitr.

The middle part specifies the credentials to your WordPress site. I assume you don't want to distribute your WordPress login credentials on Github, so remember to exclude the script PublishPost.R in your .gitignore.

The last part of the script call the knit2wp function from the knitr package, which pushes your blog post to your site.

Note the options in the knit2wp call (see all by typing ?knit2wp in your R console.) The setting publish = TRUE would publish your post right away, without you having even to open WordPress. I prefer to push my posts in draft mode (i.e., publish = FALSE). I then log in to WordPress and check that everything looks the way I want before making it public. I also set categories at this point, add SEO specs, etc.

In its simplest form, writing your RMarkdown is business as usual. Write your code, add images, and so on, using standard Markdown syntax.

With a little bit of extra effort, you can include WordPress-specific formatting (i.e., something that is interpreted by PHP, not knitr). For instance, to keep your WordPress-specific paragraph formatting, you add the <!-- wp:paragraph --> function call in your R Markdown. This line of code is the opening element that sets up the HTML structure of the WordPress Block editor. knitr ignores those calls (as it's enclosed in R comment tags), but WordPress will know what to do with it. This is likely easier to follow in an example. To see these tags in action, head on over to Github and have a look at the source code of the very post that you are reading.

Another WordPress-specific element is the “More” tag that defines the part of the post that is visible in the blogroll. To include a “More” tag in your post, place the following snippet at the desired spot in your RMarkdown:

<!-- wp:more -->
<!--more-->
<!-- /wp:more -->

You can include mathematical notation in your MarkDown file as you normally would. However, you need to install an additional plugin to render it correctly on your WordPress page. One option is the Simple Mathjax plugin.

If you write very long posts (and need a table of contents), or want to otherwise reference text on the same page, anchors are nifty solution. You need two tags for it to work:

This is the <a name="demo_anchor">text I want to link to</a>.

Here is the [link](#demo_anchor) to the text above.

Last but not least, execute the PublishPost.R script and marvel at the ease of this neat little publishing pipeline.

When you want to edit your post (versus publishing for the first time), you need to adjust the parameters in the knit2wp function call.

# editing a post requires 'action' and 'postid' parameters in knit2wp
knit2wp('TITLE_OF_FILE_YOU_WANT_TO_PUBLISH.Rmd',
        title = 'Publish to WordPress directly from RStudio',
        publish = FALSE,  # if published, then TRUE
        action = "editPost",
        postid = 317)

The postid is the ID of the post in WordPress. Not sure how to find the WordPress post ID? Look here.

Please comment below if you run into trouble with the setup. Happy analyzing and blogging!