Wordpress still, to an extent, rules the blogging world. Its longevity is testament to…something about it ;) However, it’s not my favourite platform in which to write a blog by a long way. It doesn’t support Markdown to the extent that I want. Yes, I’ve tried the plugins; no, they didn’t do what I needed.
I like to write all my content in a structured format - ideally Asciidoc, but I’ll settle for Markdown too. Here’s how I stayed [almost] sane whilst composing a blog in Markdown, reviewing it in Google Docs, and then publishing it in Wordpress in a non-lossy way.
- Write your blog in Markdown. Perhaps this approach will work with Asciidoc too, since pandoc also works with it - I’ve just not tried it.
Google Docs is still the best way that I’ve found to collaboratively review a blog. It’s accessible to technical and less-technical users alike.
We’ll get your Markdown into GDocs via a
pandocto convert the Markdown to
pandoc Securing\ lakeFS\ with\ Role-Based\ Access\ Control\ \(RBAC\).md \ -o ~/Downloads/blog.docx
.docxfile to Google Docs
Save GDoc as native Google Doc, share with comment access
Review / Copyedit
Make edits, accept proposed changes, etc directly in GDocs.
If you’re using Asciidoc, see this related blog that I wrote on Converting from AsciiDoc to Google Docs and MS Word.
At this point the Google Doc is ready to publish. However, Google Docs doesn’t have a concept of code blocks (and other formatting such as figure captions) that your Markdown has. We don’t want lose these in a straightforward copy and paste into Wordpress’ WYSIWYG editor directly
Import the changed GDoc with edits back into Markdown
Export the copy edited & reviewed GDoc back to Markdown using a Chrome plugin
Do a diff and import changes back to original Markdown document (so that code blocks & language are not lost)
Publish the Markdown to Wordpress
Convert the markdown to HTML.
cd "/Users/rmoff/my_blogs/" pandoc "Here's Something Diff-erent - lakeFS adds support for diff of Delta tables.md" \ -o ~/Downloads/blog.html \ --wrap=none \ --no-highlight \ --extract-media=/Users/rmoff/Downloads/
--no-highlightis important to stop the HTML being generated with syntax highlighting - we want to keep the pure code block intact and let WP doing its highlighting instead.
extract-mediapath does not support
~and a relative path is from the working directory in which the command is executed.
In Wordpress, create a new post.
From the top-right dropdown menu select Code editor (⇧⌥⌘M) to view the raw HTML. Copy and paste the HTML that pandoc generated into Wordpress.
Upload all the images needed to the WordPress Media Library. Look at the resulting URL prefix (e.g.
https://lakefs.io/wp-content/uploads/2023/03/) and search and replace all the image paths in the source HTML as needed.
- You will need to amend
%20in the URL for
-for files with spaces in
- You will need to amend
At this point the code should render OK, but without syntax highlighting
To add in the syntax highlighting:
Search and replace in the raw HTML to replace:
<pre class="bash"><code lang="bash" class="language-bash">. You can do this in your favourite text editor, or use this little bash snippet:
sed -i '.bak' \ 's/<pre class="\(.*\)"><code>/<pre class="\1"><code lang="\1" class="language-\1">/' \ ~/Downloads/blog.html
Copy and paste the HTML into the blog’s code editor afresh
Use this one weird trick… switch back to the visual editor, put the cursor in the editor box, and click the Convert to blocks option that appears
If you click in one of the code blocks you’ll see that it’s picked up the language, and when you preview the blog it should highlight its syntax correctly