A WordPress plugin to sync content with a GitHub repository (or Jekyll site)
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!
The sync action is based on two hooks:
save_post
hook which pushes content to GitHubpush
webhook (outbound API call)wordpress-github-sync.zip
from the WordPress plugins repository.wordpress-github-sync.zip
from your computerwordpress-github-sync.zip
wordpress-github-sync
directory to your computerwordpress-github-sync
directory to the /wp-content/plugins/
directoryInstall the plugin and activate it via WordPress’s plugin settings page.
cd wp-content/plugins
git clone https://github.com/benbalter/wordpress-github-sync.git
cd wordpress-github-sync && composer install
public_repo
scope. If you’d prefer not to use your account, you can create another GitHub account for this.application/json
as 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.Export to GitHub
or if you use WP-CLI, run wp wpghs export all ===
from the command line, where === = the user ID you’d like to commit as.wordpress-github-sync.zip
from the WordPress plugins repository.wordpress-github-sync.zip
from your computerwordpress-github-sync.zip
wordpress-github-sync
directory to your computerwordpress-github-sync
directory to the /wp-content/plugins/
directoryInstall the plugin and activate it via WordPress’s plugin settings page.
cd wp-content/plugins
git clone https://github.com/benbalter/wordpress-github-sync.git
cd wordpress-github-sync && composer install
public_repo
scope. If you’d prefer not to use your account, you can create another GitHub account for this.application/json
as 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.Export to GitHub
or if you use WP-CLI, run wp 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 WordPress GitHub Sync will only import posts from the master
branch. Changes on other branches will be ignored.
If WordPress GitHub Sync 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, WordPress GitHub Sync 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. However, it provides a number of hooks in order to customize its functionality. Check out the wiki for complete documentation for these actions and filters.
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 WordPressGitHub 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 urlAll 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 );
Shortcodes (v >= XXXX)
If you wish to add either the bare URL or a link referencing the URL to an individual post, without editing themes, you can add a shortcode anywhere in your post;
[wpghs]
The following optional attributes can also be included in the shortcode
* target=
+ 'view'
(default) the url used will be the view URL (/blob/
).
+ 'edit'
the url used will be the edit URL (/edit/
).
* type=
+ 'link'
(default) an anchor tag (<a>
) with href set to the requested URL will be inserted.
+ 'url'
the the bare requested URL will be inserted.
* text=
+ ''
(default) link text (where type='link'
, ignored otherwise) will be set to ‘View this post on GitHub’.
+ 'text'
link text (where type='link'
, ignored otherwise) will be set to ‘text’ (the supplied text).
For example,
[wpghs target='view' type='link' text='Here is my post on GitHub'] will produce a HTML anchor tag with href set to the 'view' URL of the post on GitHub, and the link text set to 'Here is my post on GitHub', i.e. <a href="https://github.com/USERNAME/REPO/blob/master/_posts/YOURPOST.md">Here is my post on GitHub</a>
Any or all of the attributes can be left out; defaults will take their place.
There are a number of other customizations available in WordPress GitHub Sync, 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.
This change log follows the Keep a Changelog standards.
wpghs_post_meta
filter & wpghs_pre_import_meta
to handle the meta yourself. See the documentation for more information.sanitize_title
to sanitize_file_name
. post_date
if post isn’t published. post_date
means the time the post was published. If it’s not published, it shouldn’t have a post_date
.wpghs_pre_fetch_all_supported
: Filter the query args before all supported posts are queried.wpghs_is_post_supported
: Determines whether the post is supported by importing/exporting.prime
: Forces WPGHS to fetch the latest commit and save it in the cache.wpghs_sync_branch
: Branch the WordPress install should sync itself with.wpghs_commit_msg_tag
: Tag appended to the end of the commit message. Split from message with -
. Used to determine if commit has been synced already.wpghs_line_endings
to set preferred line endings.wpghs_pre_import_args
wpghs_pre_import_meta
$wpghs
variable. WordPress_GitHub_Sync::$instance
instead.