---
title: "WordPress Website Setup for goodpress"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{setup}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

To be able to use goodpress to publish posts on your WordPress website, you need to perform a few setup steps. You only need to do these *once*, so that's only potentially painful at setup.

You might not need to tweak syntax highlighting and math stuff if you, well, never show code or never show math equations in your posts.

## Authentication

From the point-of-view of WordPress this package is a "remote application" that will need an application password to interact with your WordPress site through the [REST API](https://developer.wordpress.org/rest-api/). 

Here's what I did to be able to use this package on my [test website](https://rmd-wordpress.eu/):

* Created a new user with editor rights, not admin, and [from the admin panel](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/#Getting-Credentials) I created an application password for "rmarkdown" for that user. _While you do not strictly need to create a new user to create an application password, doing this for an user with restricted access is safer._
_Note:_ This setup has been tested up to WordPress 6.2 (self-hosted, i.e. wordpress.org). It may be possible to also use it on the centralised WordPress.com if you [follow these instructions](https://wordpress.com/support/third-party-applications/#sites-with-plugins-installed) to generate an application password.

* In [`.Renviron`](https://rstats.wtf/r-startup.html#renviron), save username as `WP_USER` and application password as `WP_PWD`. Re-start R. _Keep `.Renviron` safe, it contains secrets!_ Here's an example of .Renviron below, the empty line at the end of the file is needed.

```yaml
WP_PWD="your application password including space e.g. blabla blabla blabla blabla NOT your WordPress main password"
WP_USER="yourusername"

```
* If your website is using non-pretty permalinks (i.e. you have links à la `mywebsite.com/?p=42`, [you'll need to change that setting](https://developer.wordpress.org/rest-api/key-concepts/#routes-endpoints)). Pretty permalinks are better for SEO anyway. If that's a problem for you, please open an issue.

## Syntax highlighting

### For R

To get syntax highlighting for R blocks, at the moment you need to add custom CSS (once, like the plugin setup stuff).

* Find `system.file(file.path("css", "code.css"), package = "goodpress")` and copy it to your clipboard.
* From your WordPress admin dasbhoard, go to Appearance > Customize > Additional CSS. Paste the CSS there and click on publish.

You could edit colors that are in the CSS file.

Later I hope to make this process easier, maybe by adding inline styles.

### Other languages

I haven't explored that yet.

## Math

To be able to use math with MathJax, you'll need to customize your theme. 

From WordPress interface go to Appearance > Theme Editor. 
Add the lines below (that come from [MathJax docs](https://www.mathjax.org/#gettingstarted)) to the `<head>` div of `header.php`, then save.

```html
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
```

Then refer to [the usage vignette](https://maelle.github.io/goodpress/articles/goodpress.html#math-with-mathjax).
