gfm-wordpress
v1.6.0
Published
Convert GitHub flavored Markdown to Wordpress-ready HTML
Downloads
6
Maintainers
Readme
gfm-wordpress
Process GitHub flavored Markdown so it can be pasted directly into WordPress.
I (Jason Smith) use this tool for writing blog posts in a project on GitHub, but then publish them on the IBM Developerworks blog. If you are not blogging for the Cloud Data Services developer advocacy group, I am not sure you will find this very useful. But maybe.
Features
GFM-WordPress does a few things:
- Convert GitHub-flavored Markdown to HTML
- Correct syntax highlighting (embed the required CSS) in the HTML
- Fix a few CSS bugs
- Build a Table of Contents
- Automatically correct links to a
media/
subdirectory, so that they work from WordPress - If an image has retina resolution (
"[email protected]"
), reduce its size so it does not look ridiculous - Support for basic "figures": images that float in the text flow, with captions
Authoring a Document
Make a Markdown document in any Git project. You can preview it in GitHub normally. Follow two rules:
- In code samples, do not exceed 72 characters per line, or it will auto-wrap and look ugly. You can set a guide in the Xcode preferences. But remember not to take a screenshot with the guide enabled.
- Commit images in
media/
relative to your.md
file. Reference it like this:![Alt text goes here](media/image-filename.png)
- If you take a screenshot from a retina device (iPhone, MacBook pro, etc.), give the filename a
@2x
suffix, e.g.[email protected]
- Commit downloads in
media/
just like images. Link to them normally, e.g.[example-download]: media/example-project.tar.gz
If you follow these rules, everything will work when you view the document in GitHub, and it will work when you paste into WordPress.
Usage
Install with NPM:
npm install --global gfm-wordpress
To use the tool, you have to figure out the "media" location for your post. This is the directory WordPress will store your images, downloads, etc.
There are two ways to figure out the media location: by using the URL of an image already uploaded, or by "guessing."
- The sure-fire way: Get an image URL from your post draft:
- Log in to WordPress
- Create a draft post. Click "Save Draft" at least once, just to be sure.
- Click "Add Media"
- Click the "Upload Files" tab and click the "Select Files" button
- Select a file and upload it in.
- When the upload is done, click the image so it is checked
- In the right sidebar, the URL will be visible. Select the entire URL and copy it to your clipboard.
- The "guessing" way: Just do step 1 a lot until you know the system by heart. The media location seems to change only once per month. I think it is
47/2016/MM
where MM is the current month. I have no idea whatsoever what the "47" means. Maybe we are the 47th blog installed on this WordPress server?
Once you know your media location, run the tool:
gfm-wordpress README.md --media=47/2016/01
But you can also paste the full URL of an image; gfm-wordpress
will extract the media location from that URL.
The HTML will arrive on stdout. Copy all of the HTML and paste it into the blog editor. You should completely overwrite the previous post content. The idea is that all authoring is in Markdown. WordPress only hosts the final HTML.
Finishing
You must upload all media manually. Just follow the procedure from the Usage section above. As you preview the post, the images should render, because the gfm-wordpress output HTML is already referencing them correctly.
If you do not see the images, one problem I suspect is that they need to be pushed to a CDN of some sort. Try clicking "Insert into post". (You will notice it takes longer than you'd think.) Once it inserts the HTML into your post, just delete that HTML.
If you are on the CDS team, check the blog post of this very file (it is private, so you must be logged in or it will 404).
License
Apache 2.0