Contributors: JamesDiGioia, benbalter
Tags: github, git, version control, content, collaboration, publishing
Requires at least: 3.9
Tested up to: 4.3.1
Stable tag: 1.5.1
License: GPLv2
License URI: http://www.gnu.org/licenses/gpl-2.0.html
A WordPress plugin to sync content with a GitHub repository (or Jekyll site)
Ever wish you could collaboratively author content for your WordPress site (or expose change history publicly and accept pull requests from your readers)?
Looking to tinker with Jekyll, but wish you could use WordPress's best-of-breed web editing interface instead of Atom? (gasp!)
Well, now you can! Introducing WordPress <--> GitHub Sync!
- Allows content publishers to version their content in GitHub, exposing "who made what change when" to readers
- Allows readers to submit proposed improvements to WordPress-served content via GitHub's Pull Request model
- Allows non-technical writers to draft and edit a Jekyll site in WordPress's best-of-breed editing interface
- Allow teams to collaboratively write and edit posts using GitHub (e.g., pull requests, issues, comments)
- Allow you to sync the content of two different WordPress installations via GitHub
- Allow you to stage and preview content before "deploying" to your production server
The sync action is based on two hooks:
- A per-post sync fired in response to WordPress's
save_posthook which pushes content to GitHub - A sync of all changed files triggered by GitHub's
pushwebhook (outbound API call)
- Navigate to the 'Add New' in the plugins dashboard
- Search for 'WordPress GitHub Sync'
- Click 'Install Now'
- Activate the plugin on the Plugin dashboard
- Download
wordpress-github-sync.zipfrom the WordPress plugins repository. - Navigate to the 'Add New' in the plugins dashboard
- Navigate to the 'Upload' area
- Select
wordpress-github-sync.zipfrom your computer - Click 'Install Now'
- Activate the plugin in the Plugin dashboard
- Download
wordpress-github-sync.zip - Extract the
wordpress-github-syncdirectory to your computer - Upload the
wordpress-github-syncdirectory to the/wp-content/plugins/directory - Activate the plugin in the Plugin dashboard
Install the plugin and activate it via WordPress's plugin settings page.
cd wp-content/pluginsgit clone https://github.com/benbalter/wordpress-github-sync.gitcd wordpress-github-sync && composer install- Activate the plugin in Wordpress' Dashboard > Plugins > Installed Plugins
- Create a personal oauth token with the
public_reposcope. If you'd prefer not to use your account, you can create another GitHub account for this. - Configure your GitHub host, repository, secret (defined in the next step), and OAuth Token on the WordPress <--> GitHub sync settings page within WordPress's administrative interface. Make sure the repository has an initial commit or the export will fail.
- Create a WebHook within your repository with the provided callback URL and callback secret, using
application/jsonas the content type. To set up a webhook on GitHub, head over to the Settings page of your repository, and click on Webhooks & services. After that, click on Add webhook. - Click
Export to GitHubor if you use WP-CLI, runwp wpghs export all #from the command line, where # = the user ID you'd like to commit as.
WordPress <--> GitHub Sync exports all posts as .md files for better display on GitHub, but all content is exported and imported as its original HTML. To enable writing, importing, and exporting in Markdown, please install and enable WP-Markdown, and WordPress <--> GitHub Sync will use it to convert your posts to and from Markdown.
You can also activate the Markdown module from Jetpack or the standalone JP Markdown to save in Markdown and export that version to GitHub.
WordPress <--> GitHub Sync is also capable of importing posts directly from GitHub, without creating them in WordPress before hand. In order to have your post imported into GitHub, add this YAML Frontmatter to the top of your .md document:
---
post_title: 'Post Title'
layout: post_type_probably_post
published: true_or_false
---
Post goes here.
and fill it out with the data related to the post you're writing. Save the post and commit it directly to the repository. After the post is added to WordPress, an additional commit will be added to the repository, updating the new post with the new information from the database.
Note that WordPrss<-->GitHub Sync will only import posts from the master branch. Changes on other branches will be ignored.
If WPGHS cannot find the author for a given import, it will fallback to the default user as set on the settings page. Make sure you set this user before you begin importing posts from GitHub. Without it set, WPGHS will default to no user being set for the author as well as unknown-author revisions.
By default, WordPress <--> GitHub Sync only exports published posts and pages. If you want to export additional post types or draft posts, you'll have to hook into the filters wpghs_whitelisted_post_types or wpghs_whitelisted_post_statuses respectively.
In wp-content, create or open the mu-plugins folder and create a plugin file there called wpghs-custom-filters.php. In it, paste and modify the below code:
<?php
/**
* Plugin Name: WordPress-GitHub Sync Custom Filters
* Plugin URI: https://github.com/benbalter/wordpress-github-sync
* Description: Adds support for custom post types and statuses
* Version: 1.0.0
* Author: James DiGioia
* Author URI: https://jamesdigioia.com/
* License: GPL2
*/
add_filter('wpghs_whitelisted_post_types', function ($supported_post_types) {
return array_merge($supported_post_types, array(
// add your custom post types here
'gistpen'
));
});
add_filter('wpghs_whitelisted_post_statuses', function ($supported_post_statuses) {
return array_merge($supported_post_statuses, array(
// additional statuses available: https://codex.wordpress.org/Post_Status
'draft'
));
});
If you want to add a link to your posts on GitHub, there are 4 functions WordPress<-->GitHub Sync makes available for you to use in your themes or as part of the_content filter:
get_the_github_view_url- returns the URL on GitHub to view the current postget_the_github_view_link- returns an anchor tag (<a>) with its href set the the view urlget_the_github_edit_url- returns the URL on GitHub to edit the current postget_the_github_edit_link- returns an anchor tag (<a>) with its href set the the edit url
All four of these functions must be used in the loop. If you'd like to retrieve these URLs outside of the loop, instantiate a new WordPress_GitHub_Sync_Post object and call github_edit_url or github_view_url respectively on it:
// $id can be retrieved from a query or elsewhere
$wpghs_post = new WordPress_GitHub_Sync_Post( $id );
$url = $wpghs_post->github_view_url();
If you'd like to include an edit link without modifying your theme directly, you can add one of these functions to the_content like so:
add_filter( 'the_content', function( $content ) {
if( is_page() || is_single() ) {
$content .= get_the_github_edit_link();
}
return $content;
}, 1000 );
This is an advanced feature. Your configuration may or may not be fully supported. Use at your own risk.
More information can be found in the wiki.
There are a number of other filters available in WordPress <--> GitHub Sync for customizing various parts of the export, including the commit message and YAML front-matter. Want more detail? Check out the wiki.
Found a bug? Want to take a stab at one of the open issues? We'd love your help!
See the contributing documentation for details.