As a followup to a previously written post outlining the idea of having the source material for the Creative Commons Certifications residing in GitHub in Markdown, this post documents a bit more at a technical level my current efforts to show how the content can be ported easily to WordPress.
If I might make a construction metaphor, what exists on GitHub is like the foundation and framework we almost never notice in our homes. What we have on GitHub now for the start of the Core Certification are files with headings, text, links, images, basic syntax of the proposed certification.
Brought into WordPress, we add the wallboard, texturing, flooring, paint, etc, seen here with the structure of the GitHub hosted content rendered as HTML, in a particular theme. From there we might add WordPress specific features like featured images, re-arrange the order, modify the introduction, swapping out resources.
The timer framing is just the starting point for building the houses of certification, and they are not intending to be drab repeated suburban copy houses.
The house I live in was built in the 1970s from a “kit” known as O’Malley Easy Do. I know this because my neighbor, Jack, built his first from the same kit. A truck delivered a load of trusses, beams, and wall sections. But each builder could customize the size of the rooms, the locations of windows. All started from the same pieces of infrastructure, but even with that, the finished homes are quite different inside, not only in decor but layout.
From GitHub to WordPress
My first experiments were a proof of concept. To display GitHub content from WordPress, I chose to use the Markdown module enabled in the JetPack plugin (there are other plugin options for writing in Markdown).
But to make it work as I wanted to in WordPress, I had at the top some shortcodes (using the PageList plugin that creates lists based on the WordPress Page parent/child/sibling relationship) I use to generate the navigation links. The first makes a top navigation bar linking to the other certifications; the second creates an internal set of links to other modules within a certification.
This is an example of some interior finish work, like some fancy doorway molding.
So for any updates, the Markdown copied form Github needed to be pasted below this.
Also, the Markdown code starts with a heading 1 “mark” with the title. In WordPress, this does not go in the body, but in the separate title field. When working on the interior of the house, I had to keep running the board through a table saw.
And then I found problems with images. In the source markdown, we would embed an image like:
But copied directly to WordPress, the image is broken. That is because if the way GitHub manages images- if you put the URL that looks like one for an image, in GitHub you actually get a page that contains the image
This is not the image you were looking for
The actual image URL is https://raw.githubusercontent.com/creativecommons/cc-cert-map/master/img/CopyrightBasics2.jpg likely some thing done to manage content via a content distribution network or to discourage hotlinking.
There is a way I could get get working HTML image URLs from the GitHub repo- I made the master branch also to use the Github pages features in the same branch
Setting the GitHub options to use the master branch to publish GitHub Pages.
.
But the bottom line was the markdown image code did not render in WordPress. I first fixed it the lazy (wrong) way, by uploading the images to the WordPress media library, and manually changing the links.
There is nothing to see at the link, that’s not what I need. But all of the images are not published at a direct URL. So while https://github.com/creativecommons/cc-cert-map/blob/master/img/CopyrightBasics2.jpg does not render in a browser as an image, http://creativecommons.github.io/cc-cert-map/img/CopyrightBasics2.jpg does.
And this tells me I might be able to get the links to work if I modified the content automatically and do some kind of string replace method to re-write the urls.
I knew the WordPress method needed to allow for a clean and total copy/paste from GitHub source, without any manual tinkering. The construction metaphor might break down here, but what I need is a way for WordPress to do the special interior design with the stuff in the content box of the editor coming solely from GitHub copied Markdown.
The things I needed to get working were
- Add the WordPress specific shortcodes to produce the internal site navigation
- Remove the first # Header tag from Markdown content
- Rewrite the Markdown image code to use public viewable image URLs
The Nuts and Bolts
I thought of two technical approaches for dealing with this situation. I could program a save_post action so that when a page was saved, I would trigger a function that would modify the content saved to the database. So Markdown goes in, some things are added, and it saves.
The other way is to use the_content filter so that the total copied Markdown is what is saved to the database, and when rendered to a page, the modifications are done for the way I wanted it presented.
I chose the latter, because it means for the rest for my team, all the need to know to make updates to WordPress is to copy the entire Markdown code from GitHub, and paste over the existing content of the WordPress page. And the other advantage should be is when I soon experiment with the WordPress GitHub Sync plugin, it will mean no copy/pasting at all to WordPress.
And down the road, it might be possible to build something so people could just populate a new WordPress site with the most current timber frames for a new site… it’s like a truck delivering an O’Malley Easy Do kit to their WordPress site.
To make this work, I create a Page Structure in WordPress (this facilitates the dynamic constructions of navigation links based on parent/child relationships)
Certifications is just an entrance to all the ones we will publish. Below that is an index/welcome for each certification, like the one for CC Core and under that are all of it’s modules, like The Commons and Copyright Basics.
The Modules use a top level navigation (to other certifications) and a sidebar to other modules. The Index/Welcomes use the top level navigation only.
I will need a way to designate these different types of WordPress pages (as well as to not bother messing with other non Certification Draft pages). I already have a special page-map.php theme template for the module pages (it adds a Gravity form for collecting resources), and I made another theme template page-cert.php to identify the index pages.
So when setting up these pages, I can use the Page Attributes menu in the WordPress editor to designate these two types of pages
In my WordPress child theme’s functions.php I add a hook to filter I need to modify content on output
|
1 |
add_filter( 'the_content', 'cc_cert_content_filter', 20 ); |
I add
|
1 2 3 |
function cc_cert_content_filter( $content ) { } |
which is called every time a WordPress page requests the content of a post/page for display.
The logic in this function is:
- Is this coming from a WordPress Page using the
page-cert.phptemplate? (an index to a certification) If so, modify the content needed to deal with images and links from Markdown, and add the shortcode for the top navigation. - Is this coming from a WordPress Page using the
page-map.phptemplate? (a single module within a certification) If so, modify the content needed to deal with images, remove the first line with the redunant heading, and add the shortcodes for the top and side navigation. - All posts/pages (default) just send on the content as it came out of the database
The code is somewhat specific to this site, as specific as the kinds of cabinets I install in my house’s kitchen, and wether I like the 1970s wood paneling or want to paint it or cover it with sheetrock. I’m doing some replacements to fix the image URLs, links from Markdown to .md files, and removing the first line of the gitHub content.
Another bonus was I do not have to manual;y define post ids in the Pagelist shortcodes, it gets that by finding the id of a pages parent (or even grandparent).
You can find this within the functions.php code for the theme or just the code I did for the first iteration is below
We are deep within the obscure tools of the home construction.
But… what we have is a way to put pure GitHub authored markdown into WordPress, leave it there as it came from GitHub, and yet have it rendered with what every WordPress specific things I want in my own house.
Still a Conceptual House
I’ve waded through a lot of detail and tossed a big wad of code blueprints. The question would be– how will others do this? People who know WordPress might figure out their own customizations. We might build a set of exports of empty WP sites that have all these pieces in, and a way to have to sync to the source for the latest content.
The easy way for us to do this would be to design one house with the rooms we like and paint colors too, not to mention our bizarre taste in furniture (my house came with some weird fiberglass couches in it). But would it not make more homes, for more people, if they can have the structural parts that support it come as a kit, but yet allow them to design the insides as they see fit?
Again, what I have working is a clean direct move from what looks in GitHub like https://github.com/creativecommons/cc-cert-map/blob/master/core/index.md to this. From this to this.
CC Certificates Easy Do!
Featured image credit: Composite of Beautiful Post and Beam Timber Frame Barn (Wikimedia Commons CC-BY licensed image) and Painter Paints a Room in a House (Wikimedia Commons Public Domain image)
