goodpress (or badpress?)

Write to WordPress, from R Markdown, with a modern stack.

The goal of goodpress is to post to WordPress from R Markdown. I need this prototype for a course. 😺

Limitation: This package relies on the standard WordPress REST API but has only been tested on self-hosted Wordpress installations. It may or may not work with the centralised wordpress.com service (if it does, please report back, for instance in an issue).

Important disclaimer: I don’t use WordPress, so I am not sure you should trust me. You are welcome to try out the package (not on important stuff, rather in a playground of some sort), to contribute, and to volunteer to take over this package/concept. If you write a newer and better R package please tell me about it so I can add a link to it.

Installation

You can install the released version of goodpress from its GitHub repository:

# install.packages("remotes")
remotes::install_github("maelle/goodpress", ref = "main")

Then you will need to tweaks things once on your website for three aspects

Authentication (this is compulsory)
Syntax highlighting (if you want to show R code in your posts)
Math (if you want to show math in your posts)

See vignette("setup", package = "goodpress").

Workflow

The summary is: create your posts in folders as index.Rmd with hugodown::md_document output format; knit, wp_post(), rinse, repeat.

Create your posts in folders, one folder per post, with index.Rmd knitted to index.md and figures under a “figs” folder.

fs::dir_tree(system.file(file.path("post-example2"), package = "goodpress"))
#> /home/maelle/R/x86_64-pc-linux-gnu-library/3.6/goodpress/post-example2
#> ├── chicago-fullnote-bibliography.csl
#> ├── figs
#> │   ├── pressure-1.png
#> │   └── unnamed-chunk-1-1.png
#> ├── index.Rmd
#> ├── index.md
#> └── refs.bib

The post index.Rmd should use hugodown::md_document as an output format.
Knit your post and then, run the function wp_post() that takes the path to the post folder as argument, create a draft post in your website, uploads all image media stored in the “figs” folder, edits the references to image media and then publishes the post.
The first time you run wp_post() for a folder, it creates a file called .wordpress.yml in the post folder, that contains, in particular, the URL and ID of the post on your WordPress website. This way, next time the function is run, the post is updated.

Example post and its source. Note that it includes citations as footnotes by using the same strategy as hugodown.

You could have one big “blog” folder/RStudio project with each post as a sub-folder, neatly named YYYY-MM-DD-slug, and at the root of the blog folder you’d have this script you’d run from the RStudio project

wordpress_url <- # your url
today_post <- "2020-06-01-cool-post"
goodpress::wp_post(today_post, wordpress_url)

Images and figures

For plots generated via R, just use R Markdown as you normally would.
For images not generated from R code, save them in the figs subfolder and use knitr::include_graphics() to include them. See example post with a cat picture and its source.

Author

You can either

not write any author in the YAML metadata, and the author will be the authenticated user.
write an existing username which is useful when you are posting or editing on someone else’s behalf.

You cannot create an user with this package, you have to use WordPress interface for that.

Publication status

The default status of the post is “publish”. If you want another status (status has to be one of: “publish”, “future”, “draft”, “pending”, “private”) , write it in the yaml (and then knit index.Rmd again) e.g.

---
title: "Title of the Post"
date: "2020-04-01T00:00:00"
slug: "post-slug"
excerpt: "Here I summarize this fantastic post"
status: "private"
output: hugodown::md_document
---

The package cannot handle private posts with password, only private posts that are visible to admins and editors only. You could create a private post, and then from the WordPress interface make it visible with password. Make it private again before trying to update the post with the R package.

Tags and categories

You can use tags and categories in the YAML metadata of index.Rmd (rendered to index.md). If a tag or a category doesn’t exist wp_post() will create it for you.

e.g.

---
title: "Title of the Post"
date: "2020-04-01T00:00:00"
slug: "post-slug"
excerpt: "Here I summarize this fantastic post"
status: "publish"
output: hugodown::md_document
categories:
  - math
  - code
tags:
  - crul
  - mathjax
  - R packages
---

Or (if there’s a single category or single tag)

---
title: "Another Rmd Blog Post"
date: "2020-04-01T00:00:00"
slug: "post-rmd"
excerpt: "Here I summarize this fantastic post"
output: hugodown::md_document
bibliography: refs.bib
suppress-bibliography: true
csl: chicago-fullnote-bibliography.csl
categories: R
tags:
  - citation
  - code
---

Math with MathJax

First, add MathJax JS script to your website, once.

In every post where you want to use math, use MathJax input (MathML, LaTeX). After formulas put a few empty lines.

See example post with math and its source.

Technical details

If you’re curious. 🙂

The “one post per folder” thing is inspired by Hugo leaf bundles.

At the moment this package uses the very handy hugodown’s R Markdown output format which allows using downlit for R syntax highlighting without my having to think too much.

On disk your post is stored as index.Rmd and index.md, but before upload to the WordPress API it is transformed to HTML using Pandoc.

Motivation

The current best tool for writing from R Markdown to WordPress, knitr::knit2wp(), relies on a package that hasn’t been updated in years and that depends on the no longer recommended RCurl and XML. In the meantime, WordPress gained a REST API that to my knowledge isn’t wrapped in any working R package.

There is also the solution to use a plug-in to sync a GitHub repo with a WordPress blog (see this website and its source) but it doesn’t handle media. If you use a GitHub repo:

You could set up something like a GitHub Action workflow that’d interact with WordPress REST API each time you push to the default branch.
Are you still sure you don’t want to use a static website generator instead? 😉 More seriously, I am interested in blogging workflows so feel free to tell me why and how you use WordPress (in an issue for instance).

baranovskypd / goodpress

readme