Like this? Share with your travel buddies!

I’ve recently started blogging and writing posts and wanted to share a workflow that I’ve found efficient. Some background is that I’ve been working in software development for more than a decade. So I’ve gotten comfortable with certain workflows like working with my text editor of choice (Visual Studio Code and Emacs right now) and working with a version control system like Git. When getting into blogging with WordPress, the natural authoring environment is the WordPress block editor. That environment has been surprisingly good but I still wanted the efficiency of working on text in VS Code.

I’m using a combination AsciiDoc (think Markdown with more features) and Git to do all of my preliminary work and then transfer to WordPress for the final polish, adding images, and checking with Grammarly. I chose AsciiDoc over Markdown because I find it more fully-featured out of the box and it is standardized compared to the zillions of Markdown flavors. AsciiDoc is also the environment I’m using for a side book project!

Here’s what I’m doing in case it is useful for you. This is the process I used on our recent Turks and Caicos travel guide. I hope you’ll tell me about similar strategies you use for an AsciiDoc blog or a Markdown blog! The entire process I’m describing here would work equally well for Markdown blogging.

Why am I working this way?

Writing content in my text editor of choice (VS Code) is highly efficient for me compared to other environments. Coupling that with the ability to use Git to version my work has been a real win! Moreover, I like that working on text files allows me to confidently work offline without worry that a browser-based editor will have an issue without internet access.

What is AsciiDoc?

AsciiDoc is a textual markup system in the same vein as Markdown. It is much more fully featured and provides the ability to author professional content. You can use internal cross-references, book chapters and parts, tables of contents, separate documents into multiple files, and more. You can then publish the document in HTML, PDF, eBook, and other formats. GitHub also renders your AsciiDoc files right in the browser like Markdown. An AsciiDoc editor like VS Code can render an HTML preview just like for Markdown.

How do I use AsciiDoc for my posts?

I have a template that I start from for all of my posts that looks like this (click the “view raw” link in the bottom right to see the markup)

Here’s my blog writing process

1. Do my keyword research and record findings in the AsciiDoc table at the top capturing keywords, difficulties, volume, date updated, and whether or not I’ve included the keyword in the post.
2. Write an outline in this document
3. Keep track of all of my actions to get ready to publish
4. Write the post at the end of the document
5. Go through all of my actions
6. Paste the raw AsciiDoc into the Grammarly editor, correct things, paste back into VS Code
7. Push to GitHub and render to HTML. I either use the AsciiDoc VS Code extension’s HTML preview or render to HTML asciidoctor post.adoc -o post.html. Copying from the HTML pastes brilliantly into the WordPress editor!
8. Paste the content into the WordPress editor and finish work on the post in WordPress by adding images, checking with Grammarly, making Yoast happy, etc.

Preventing duplicate work

If you have a look through the template above, you’ll see commentary saying which AsciiDoc constructs map to which in HTML and therefore in the WP editor. Overall, I think you get a fully-featured set with links, headings, lists, and basic formatting all pasting from the rendered HTML.

Tips and notes

• I find that having a spell-checker extension for my editor is great. I’ve been using Code Spell Checker in VS Code and like it overall.
• I haven’t found a strategy to deal with photos yet in AsciiDoc that translates easily to the blog. So I add placeholders in AsciiDoc and insert photos once I’m working in WP.
• Once I transfer to WP, I’m stuck there for Grammarly, photos, etc. I’ve not yet found a way to keep the AsciiDoc content up to date. Any ideas on improving this workflow would be appreciated!
• I started by copy-pasting from the GitHub preview of my .adoc files since those are HTML. However, that seems to force :sectanchors: on which winds up producing links next to headings that I don’t want in my final post. So I switched to the VS Code preview or manual rendering.
• I didn’t look for an AsciiDoc or Markdown blog platform because I want to keep the tech stack simple right now. If you like something that works well with WordPress, let me know below.
• I need to investigate if there’s an integrated way to render AsciiDoc or Markdown in WordPress to allow for more single sourcing.

Wrapping up

That’s the blogging process I’m currently using. It will surely evolve and I’ll periodically update this post. This strikes a balance that I like compared to fully working in the WordPress editor. Does this workflow sound interesting? Do you have any similar workflows I could learn from? Let me know below!

Like this? Pin it!

Like this? Share with your travel buddies!