Blogs are a great communications tool. This post documents a method for generating WordPress posts through RStudio. It uses the RWordPress package by Duncan Temple Lang. This tutorial is basically a highly scaled-down version of Peter Bumgartner’s excellent tutorial. At the time of posting, both that and this tutorial are distributed using a CC-BY-NC-SA license (see below).
Gutenberg does support Markdown via a block. To me, WordPress has lost its way. It is no longer a blogging tool. It is trying to compete with Wix and Medium. Li-An (@li-an) 2 years, 4 months ago. Averroes does not work in my tests. Roig82 (@roig82) 2 years, 4 months ago. Markdown is a lightweight and intuitive markup language that provides a faster way to style your posts, pages and comments. Although it takes a little time getting used to, you’ll never have to reach for your mouse while using Markdown. In this article, we’ll go over what Markdown is all about and how you can start using it with WordPress. Markdown is a fairly prominent feature of Jetpack. For those unaware, Jetpack is an entire toolset for WordPress users, with features that support social media publishing, carousels, advanced. TheMarkdown Blocklets you compose posts and comments with links, lists, and other styles using regular characters and punctuation marks. Markdown is used by writers and bloggers who want a quick and easy way to write rich text, without having to take their hands off the keyboard, and without learning a lot of complicated codes and shortcuts.
Set Up Your Session
Installing the RWordPress and XMLRPC Packages
The RWordPress package is being distributed through GitHub. It can be installed using the install_github() operation in the devtools package. You also need to install Lang’s XMLRPC package as well.
Load Necessary Packages
We need the following packages, in addition to RWordPress and XMLRPC (see above step):
- knitr, a suite of operations for generating reports
Create / Load a Script with Your Credentials
To post to WordPress, your login and password must be included in the script. Posting or circulating a Markdown file with your WordPress login credentials creates a huge web security risk. On the other hand, we teach you to be open about your coding, so that others can review, replicate, and build on it. How to negoatiate the two?
Bumgartner’s solution is to add the following variables to your .Rprofile file using this code
Do not delete the quotation marks in this template. For the ‘yourWordPressURL’, be sure to add a “https://” before and and “/xmlrpc.php” after your site address. So, for the site “joeblog.com”, you would enter “https://joeblog.com/xmlrpc.php”
Once you have generated and stored the file, you can add it to any Markdown file that you intend to post. I called my file “WPCrds.R”:
Set Images to Post to imgur.com
To save time and resources, post your images to the open online site Imgur.com. To do so, add these knitr options to your script:
Generate a Polished html Report
Create a Markdown file that renders your report in html. Render it locally to something sufficiently polished, and then move on to the next step.
In order to add a picture to this example, let me add a photo:
Post Your Information
In another chunk, set your post title as the variable postTitle, and define fileName as the name of the Markdown file that you are using to generate the post:
Post using the knit2wp command, whose options include:
- the Markdown file name (option: input)
- the post title (option: title)
- whether the post should be published upon rendering (option: publish, set true to directly publish – not advisable)
- for a new post, the action variable should be set to “newPost” (option: action)
- to set the post’s category. Use the slugs designated on your site. (option: categories)
- to set the post’s tags. Use the slugs designated on your site. (option: tags)
Clean It Up on WordPress
From here, you will have a draft post on your WordPress site. I find WordPress to have a far more user-friendly interface to complete the last steps of a post.
Remember: Risk the temptation to do everything in R if it costs a lot of time. Yes, you would be cool if you could do it. The problem is no one but data nerds will appreciate it, and there’s not a lot of data nerds out there.
Summary
To summarize, start with this set up to your script. Remember that the source() line points to a file with your credientials:
Then write the script until it is polished, and then you can post by running this code. I recommend that you set eval = F, so that it doesn’t run when you render the Markdown file into html. Then, once the file runs, execute this code on its own, not as part of a larger operation.
Then, polish the piece in WordPress.
Description
Official documentation: https://github.com/gis-ops/wordpress-markdown-git
This WordPress Plugin lets you easily publish, collaborate on and version control your [Markdown, Jupyter notebook] documents directly from your favorite remote Git platform, even if it’s self-hosted.
The advantages are:
- Write documents in your favorite editor and just push to your remote repository to update your blog instantly
- Use the power of version control: publish different versions of the document in different posts, i.e. from another branch or commit than latest
master - Easy to update by your readers via pull requests, minimizing the chance of stale tutorials
The following document types are currently supported:
- Markdown
- Jupyter notebooks (only for public repositories)
The following platforms are currently supported:
- Github
- Bitbucket
- Gitlab
Usage
Note, this plugin uses Github’s wonderful /markdown API to render to HTML. This comes with 2 caveats:
- Unless authenticated, the rate limit is set at 60 requests per minute. Since v1.1.0 the plugin is capable of statically caching content. In case that’s not dynamic enough for you, your only option currently is to not use any cache in which case every document will be pulled from your provider every time someone opens it on your site. Then it’s strongly recommended to create a Github access token and register it with the plugin. Then the rate limit will be set to 5000 requests per hour. See Global attributes section for details on how to do that.
- The Markdown content cannot exceed 400 KB, so roughly 400 000 characters incl whitespace. If not a monographic dissertation, this should not be an applicable limit though.
Shortcodes
The plugin features a variety of shortcodes.
Publish documents
The document-specific shortcodes follow a pattern of [git-<platform>-<action>], where
<platform>can be one ofgithub: if you use Github as your VCS platformbitbucket: if you use Bitbucket as your VCS platformgitlab: if you use Gitlab as your VCS platform
<action>can be one ofmarkdown: Render your Markdown files hosted on your VCS platform in Github’s rendering stylejupyter: Render your Jupyter notebook hosted on your VCS platfrom (only for public repositories)checkout: Renders a small badge-like box with a link to the document and the date of the last commithistory: Renders a<h2>section with the last commit dates, messages and authors
Manipulate rendering style
Additionally, there’s an enclosing shortcode [git-add-css] which adds a <div to wrap its contents. That way you can manipulate the style freely with additional CSS classes. Follow these steps:
- Add a CSS file to your theme’s root folder, which contains some classes, e.g.
class1,class2,class3 - Enqueue the CSS file by adding
wp_enqueue_style('my-style', get_template_directory_uri().'/my-style.css');to the theme’sfunctions.php Add the enclosing
git-add-cssshortcode to your post with the custom CSS classes in theclassesattribute, e.g.:[git-add-css classes='class1 class2 class3']
[git-gitlab-checkout url=...]
[git-gitlab-markdown url=...]
[git-gitlab-history url=...]
[/git-add-css]
Attributes
Each shortcode takes a few attributes, indicating if it’s required for public or private repositories:
Attribute
Action
Public repo
Private repo
Type
Description
url
all except git-add-css
:ballot_box_with_check:
:ballot_box_with_check:
string
The browser URL of the document, e.g. https://github.com/gis-ops/wordpress-markdown-git/blob/master/README.md
user
all except git-add-css
:negative_squared_cross_mark:
:ballot_box_with_check:
string
The user name (not email) of an authorized user
token
all except git-add-css
:negative_squared_cross_mark:
:ballot_box_with_check:
string
The access token/app password for the authorized user
cache_ttl
all except git-add-css
:negative_squared_cross_mark:
:negative_squared_cross_mark:
integer
The time in seconds that the plugin will cache, only for cache_strategy=static.
cache_strategy
all except git-add-css
:negative_squared_cross_mark:
:negative_squared_cross_mark:
integer
Only static caching is implemented so far. dynamic caching is on the way!
limithistory
:negative_squared_cross_mark:
:negative_squared_cross_mark:
integer
Limits the history of commits to this number. Default 5.
classesgit-add-css
:ballot_box_with_check:
:ballot_box_with_check:
string
The additional CSS classes to render the content with
Global attributes
Since most attributes will be the same across the entire system, this plugin offers the possibility to set all attributes globally except for url:
In the menu Plugins ► Plugin Editor, choose “Documents from Git” and enter your preferences in the includes/config.json.
Note, setting the attributes manually in the shortcode has always precedence over any settings in includes/config.json.
Caching
Often we need to prioritize speed when loading content and, in addition, it is very costly to fetch, load and format the content every time we need to read the content of the post.
This plugin soon offers 2 methods for caching, static and dynamic which can be set via the cache_strategy property.
Static caching (cache_strategy=static)
This is the default strategy, as it doesn’t require any user action.
The property cache_ttl sets how many seconds the content cache will keep alive.
Currently there’s no way to flush the cache manually. However, changing cache_ttl or the history limit will create a new cache.
Dynamic caching (cache_strategy=dynamic)
This is not implemented yet. See #20 for details.
Token authorization
You need to authorize via user and token if you intend to publish from a private repository. You don’t need to authorize if the repository is open.
However, keep in mind that some platforms have stricter API limits for anonymous requests which are greatly extended if you provide your credentials. So even for public repos it could make sense. And unless you use this plugin’s caching capabilities, it’s strongly recommended to register a Github access token regardless of the VCS hosting platform, see the beginning of the chapter.
How to generate the token depends on your platform:
- Github: Generate a Personal Access Token following these instructions
- Bitbucket: Generate a App Password following these instructions
- Gitlab: Generate a Personal Access Token following these instructions
This plugin needs only Read access to your repositories. Keep that in mind when creating an access token.
Examples
We publish our own tutorials with this plugin: https://gis-ops.com/tutorials/.
Publish Markdown from Github
Publish Markdown from Github with 1 hour cache
Publish Jupyter notebook from Github
Publish from a private repository
Display last commit and document URL from Bitbucket
Display commit history from Gitlab
Use additional CSS classes to style
The following example will put a dashed box around the whole post:
[git-add-css classes=”md-dashedbox”]
[git-github-checkout url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]
[git-github-markdown url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]
[git-github-history url=”https://github.com/gis-ops/tutorials/blob/master/qgis/QGIS_SimplePlugin.md”]
[/git-add-css]
`
With the following CSS file contents enqueued to your theme:
div.md_dashedbox {
position: relative;
font-size: 0.75em;
border: 3px dashed;
padding: 10px;
margin-bottom:15px
}
div.md_dashedbox div.markdown-github {
color:white;
line-height: 20px;
padding: 0px 5px;
position: absolute;
background-color: #345;
top: -3px;
left: -3px;
text-transform:none;
font-size:1em;
font-family: “Helvetica Neue”,Helvetica,Arial,sans-serif;
}
`
Installation
- Install WP Pusher (https://wppusher.com) via ZIP and activate
- Install from Github via WP Pusher from gis-ops/wordpress-markdown-git
- Activate and add shortcode to your posts.
Or directly from WordPress plugin repository.
Or install the latest code as ZIP from https://github.com/gis-ops/wordpress-markdown-git/archive/master.zip
FAQ
Does the plugin support caching?
Yes, since v1.1.0 the plugin supports static caching of all relevant information. See the “Caching” section for details.
Are relative links supported?
No, relative image links (e.g. ) cannot be processed by this plugin. Please see the notes in the documentation for ways to work around this limitation.
Can I host the source file in a private repository?
Wordpress Markdown Plugin
Yes, you can, if you provide the plugin’s config.json with the necessary credentials for your platform (see documentation for details). However, be aware that all image URLs you are referencing are openly accessible or provide the necessary authentication means. Also see #13 and the documentation for further details.
Wordpress Markdown Support
Reviews
Markdown Support