WIP!! :warning: R Package to Write Posts from R Markdown to Wordpress :warning:
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.
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
See vignette("setup", package = "goodpress")
.
The summary is: create your posts in folders as index.Rmd with
hugodown::md_document
output format; knit, wp_post()
, rinse, repeat.
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
hugodown::md_document
as an output format.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.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)
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.
You can either
You cannot create an user with this package, you have to use WordPress interface for that.
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.
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
---
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.
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.
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: