Skip to content

org2blog/org2blog

Repository files navigation

Org2Blog

/images/logo-color-multi.png

Why We Do This

People don’t buy what you do. They buy why you do it. ―Simon Sinek

Org2Blog is a tool for making your voice heard by the world. WHY? Because we think that freedom of expression is an intrinsic human right. Its practice is fundamental both to the growth of the individual and society. Your words are important:

We Do This So Your Words Will Be Heard

About

Org2Blog is the most advanced WordPress blog editor and manager available today.

It provides the ease and use of a desktop application granting the power and convenience that you would expect of any high-quality application.

Is it worth the price? Yes it saves you the most precious commodity: time. What does that price get you? A LOT―

Check out all the features:

Table Of Contents

Requirements And Compatibility

Org2Blog uses the Org-mode built-in to Emacs to blog on WordPress.

Org2Blog strives to run against the current versions of all of them.

Current Requirements: Org2Blog 1.1.16, Emacs 28.1, which includes Org mode 9.5.2, and WordPress 6.0.

Although it’s not required to use Org2Blog you will get the best user experience by using the WordPress Classic Editor.

Installation

Install Emacs

Start by installing Emacs Version 28.1.

Emacs is where Org2Blog lives. To use Org2Blog first you need to install Emacs. Here is where to get it:

  • macOS
  • Windows
  • Linux
    • Your system probably comes with it otherwise use your package manager

If you are new to Emacs and want to drink from the fire-hose of knowledge then start here. If you want only a sip though just ask a friend. That is the most fun way to get started.

Using A Package

The easiest way to install Org2Blog is using a package.

You can use either a stable or cutting-edge version of Org2Blog by configuring your packaging system.

The stable version contains well-used releases unlikely to contain bugs. However it receives new features and bug fixes more slowly.

If you want the stable version, then use MELPA Stable:

(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/") t)

The cutting-edge version contains new changes immediately as they’re made. It contains new features and bug fixes faster than the stable version. Although it’s very unlikely it may contain breaking changes.

If you want the cutting edge version using MELPA

(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/") t)

For advanced users, you can configure Package to use any combination of stable and cutting-edge versions of a package and its dependencies. Read more about how to configure it and utilize that power in both your init file and the Package user interface.

Use-Package

Use-Package brings ease and order to your init file. It manages your packages predictably and simply. it’s the easiest way to use Org2Blog because it will download Org2Blog for you along with all of its dependencies. Before using it you must configure your system as explained in Using A Package

Here is how to load Org2Blog:

(use-package org2blog
             :ensure t)

Take some time to read more about Use-Package. You can use as little or as much as you find helpful. It accommodates just about any Init style you can throw at it.

Install The Package Yourself

You can also do what Use-Package does yourself. Find the package you want in Using A Package and download it. it’s a plain old TAR file so you can uncompress and examine it to see how it works.

Install it by calling package-install-file and choosing the file you just downloaded. Load it by adding (require 'org2blog) to your init file.

Build The Package Yourself

MELPA creates Org2Blog’s package using this recipe.

Here is how to build it:

  • Clone the MELPA repo
  • Read about how to build a recipe
  • Make sure that you are using the correct Emacs version (see requirements above) either in your path or editing the recipe
  • Open the Org2Recipe and build it

Setting Up The Source Code By Hand

See DEVELOPMENT.

Usage

Note: For a better learning experience try reading this document inside of Emacs and Org mode after installing Org2Blog by calling org2blog-readme.

Make Your First Post In Less 5 Minutes

Blogging is fun. Org2Blog makes blogging with WordPress even more fun because it makes it simple. Simplicity is one of Org2Blog’s greatest strengths. That means you spend more time blogging and less time fiddling around with stuff. Having fun is why you are doing this, right? Exactly. Before digging into all of the powerful things you can do with Org2Blog, make your first blog post. To do that, it’s copy-and-paste time. Don’t worry; you’ll dig into all the other cool features soon! You can easily make your first post in less than 5 minutes from now because the configuration file and UI make it so simple.

  • Installation is already complete, so Org2Blog is ready for you to use.
  • Create the profile for your blog so you can get started. In this example, “myblog” is the name of your profile for your blog: it stores everything you want Org2Blog to use and know about it. To get started, it only requires the 2 bits of the information shown. url is the full URL required to access WordPress XML-RPC on your blog. username is the account that you are using to blog. Now fill it out and evaluate it.
(setq org2blog/wp-blog-alist
      '(("myblog"
         :url "https://myblog.com/xmlrpc.php"
         :username "username")))
  • Display the Org2Blog user interface (UI) by executing the command org2blog-user-interface. You can do everything with Org2Blog using its UI (setting keybindings elsewhere is super easy, too, and you’ll cover it soon). For simplicity, these directions will refer to “things to do in the UI” in the style of UI [action].
  • The Main Menu:
    • /images/menu-main.png
  • Create a brand new Buffer Entry from a template: UI [New Buffer]
  • If you aren’t logged in, then Org2Blog will ask if you would like to log in. Yes, you should go ahead and log in.
  • A pre-populated Buffer Entry sits in front of you. Please fill it out with test data with title, category, and tags. Org mode requires you to keep a space between the keyword and the value: that is the only way for it to read them. If you accidentally omit the space, then Org2Blog will report it to you and suggest a resolution.
  • Save it as a Buffer Post Draft out on the blog: UI [Save Post Draft]
  • Watch for messages in the minibuffer letting you know what is happening.
  • #+POSTID is populated now.
  • View it: UI [View Post]
  • When you are ready to publish it, just do it: UI [Publish Post]

Congratulations! You just made your first blog post with Org2Blog! With this experience under your belt, you will be a lot more interested in how to get the most out of Org2Blog. it’s simple and powerful, and you can shape it into the perfect blogging tool for you. Work through usage sections at your own pace. Take the time to invest in Org2Blog and your blogging workflow. it’s not a race; it’s a pleasant walk: so take your time and have fun!

P.S. If you are interested, here are some other examples of the UI

The Help Menu–Just Hit “h”: /images/HelpMenu.gif

The “Insert Things” Menu”: /images/InsertThingsMenu.png

Category Completion: /images/CategoryCompletion.png

Readme: /images/ReadmeBuffer.png

Customizations Documentation Menu: /images/VariableMenu.png

The 7 Most Important Next Steps

The example at the start of this document is meant to be just that: an example. It only covers a fraction of what is possible for writing and publishing with Org2Blog. This headline covers a few things that fill the gaps in doing more and better blogging with Org2Blog.

Every Org2Blogger is unique, of course. However, Org2Bloggers all know Emacs and Org mode. The concepts and features are in place (in varying degrees) are common ground. Consequently, the bulk of the feedback about Org2Blog had a lot in common too. The following items are the top 5 things that pretty much everybody wanted to know how to do

Helping Yourself To The Basics

Org2Blog’s goal is to keep blogging fun. It strives to make complicated things easy and easy things more leisurely. So in that spirit, you can do everything you want to do via the menu. Start the menu by calling org2blog-user-interface.

The easiest way to get started with the basics is to play around with the menu. If for you that means reading, then start with:

  • UI [About]: A light introduction to the Org2Blog platform
  • UI [README]: A copy of this entire README.org in a writable buffer.

They’re both an excellent way to make your notes in place without making changes to the original. Just save your changes to your file, and then you’ll have them ready for the next time you are blogging.

Once you’ve successfully logged in and read a little bit about Org2Blog, then you’ll notice that you get started blogging very quickly. Whether you start with a Buffer or Subtree Entry, you’ll begin with the same workflow. Here is the workflow:

  • UI [Login]:
  • UI [New Buffer] or UI [New Subtree]:
  • UI [Save It]:
  • UI [View It]:
  • UI [Publish It]:
  • Make changes as you iterate over the Entry
  • UI [Save It]:
  • UI [View It]:
  • UI [Publish It]:

That workflow is 100% of blogging. The right 50% of the menu is dedicated to that alone! For each action, you just need to tell Org2Blog whether you are doing it from (the source) a Buffer Entry or a Subtree Entry and whether or not it’s a (destination) Post or Page. With that simplicity in mind, please read on to learn about the options for learning more.

Another way to play around with it’s to try out all of the menu items. Don’t worry, though, because it’s safe. Org2Blog never deletes anything on your computer. It will, of course, delete blog entries on the server, but never the source documents. What each menu item does, too, is pretty apparent by the name. If you want to read its documentation, then hit h, its key command will turn red, hit it, and its documentation will come up. They’re probably overly detailed, but it’s usually better to over-specify. If your preferred style of playing involves reading, running, and configuring things, though, then Org2Blog comes with a rich approach built right in.

Start by calling Customize and search for org2blog. Take a quick look at what is available. You might customize a bunch of things right away, or nothing at all. Store them in the back of your mind. One of the best things about customize is that you can configure variables right along with their definition. That tight integration of the system and documentation makes the whole thing easier to use and understand.

You have probably noticed by now; there aren’t a ton of function names listed in this document. That is by design. Org2Blog has a lot of functions and a lot of configuration options. So many that it would overwhelm a lot of us. On top of that, the document would probably get either wrong or just out of date pretty quickly. However, you do need to know the details at some point, so what is the happy medium? it’s simple: let Org2Blog teach you everything that you want to know precisely when you want to know it.

One of the selling posts about Emacs Lisp computer programs is that not only do they come with the Libre Software source code, but they also include all of the documentation in place. It means that you can ask Emacs to give you the documentation for whatever you want. Built-in documentation is a fine, powerful, and reasonable solution. it’s the best for programmers. For bloggers, though, it can be a little overwhelming a place to start. Org2Blog does its best to bridge the gap between the two by providing documentation for functions and variables directly from the menu. If you are the kind of person who just jumps right in and wants to see everything right at once, then UI [Values] is where you want to start. Otherwise, access them using Customize just like usual.

This combination of easy-to-use menus and direct access to the code is the best way to get started. Find something that looks interesting, read about it, do it, or both, then more. Whatever keeps you having the most fun is the right way to do it.

Writing More After You Have “Settled Into” The Software

Creating Your Writing Room

Making Room To Write

Some writers can create a dedicated room for writing. Definitely hardwood floors and a sturdy desk. Others prefer a lighter space. Whatever the preference it can be easy to build in your Org2Blog world too.

Although Org2Blog doesn’t make any visual changes to your writing room itself there are great packages out there that can. Here are a few of them:

Writeroom-mode
A distraction-free writing mode similar to the famous WriteRoom editor for macOS
Darkroom
Remove visual distractions and focus on writing.
Olivetti
A simple Emacs minor mode for a nice writing environment.
Finding And Saving Your Voice

The unavoidable burden for any writer is to find their voice. To help with that are some of the classics― On Writing Well: The Classic Guide to Writing Nonfiction by William Zinsser, Snoopy’s Guide to the Writing Life by Barnaby Conrad, and On Writing: A Memoir of the Craft by Stephen King. Help keeping that voice is another story however. It takes time, practice, discipline, and hopefully some good tools. Software grammar tools are one way to do it. There are plenty, of varying quality and pedigree, but Org2Blog will only focus on two: Vale and Writegood Mode.

Vale is the ultimate grammar tool. There isn’t much to expand or expound upon here. However, it’s powerful, configurable, and considered a master-level grammar tool. If now is the right time to jump in then the report is that flycheck configured like this for Vale is the best way to get started. For the other 80% of us Writegood mode is the best place to start.

To make your life easier Writegood provides a few features with a big payoff that are easy to use and understand. Here is what it gives you:

  • Identify the grade level required to understand the content
  • Highlight duplicate words
  • Highlight Weasel words
  • Highlight irregular passive voice verbs

Use UI [Writer Tools] to report UI [Grade Level] and toggle UI [Writegood].

To get even simpler consider your wordcount under UI [Writer Tools] Word Count. Simple is not simplistic: you can always say more with less. If you want a litle more flexible word counting try out wc-mode too.

From a technical standpoint Writegood is an ideal choice because it’s written in plain old Elisp without any external dependencies. Some people copy and paste their text into online grammar tools like Grammarly and that works great. The truth about Vale though is that although it is somewhat technical to get set up, once you have it working you will really enjoy its flexibility.

Why Writing Requires Good Character(s) And Unicode

Your reputation is what others think of you; your character is what you are. Your blog post is how you capture your thoughts; the characters are how you craft them. ― Anonymous

When blogging we need as much character as we can get and the easiest way to do that is by exploring the Unicode Character Code Charts to get what you need. Org2Blog and WordPress supports Unicode right out of the box. The first step is to try it out.

The easiest way to try out Unicode is to explore the Emoticons Code Chart. You’ll immediately recognize them. Either copy and paste or UI [Insert A] and type in the character name. You don’t even have to know its full name. Just type as little or a lot of it and strike the TAB key and you’ll get name completion. Now your character is there. What happens though when you get an empty white box instead of the character? Then you don’t have a font and the fix is easy.

Install these fonts to get some very good font coverage. It simply works out of the box with no configuration required

When you want to get to the next level of configuration what fonts get used for which characters then check out the unicode-fonts package.

Out of the box it does a great job choosing fonts for characters. When you are ready to make changes for example to specify a language to a different font from that default it’s very straightforward.

Once you get hooked on using the full range of Unicode characters you will get hooked. it’s a great way to explores s more and a special way to connect with writers around the world.

How Do You Spell That Again?

Why bother spellchecking for spelling errors?

  • Encourages readers to focus on your mistakes―not your message
  • You are being judged: they reduce your credibility
  • Spellcheckers can do it for you with nearly zero effort required!

Fortunately spellchecking comes pre-loaded with Org2Blog.

Configure it like this:

  • Install Hunspell with your package manager. For example these directions are for macOS:
    brew info hunspell
    brew install hunspell
        
  • Find and download your dictionary to the public Spelling folder. You need both an *.aff and *.dic file:
    cd mkdir /usr/local/share/words
    cd /usr/local/share/words
    wget -O en_US.aff https://cgit.freedesktop.org/libreoffice/dictionaries/plain/en/en_US.aff
    wget -O en_US.dic https://cgit.freedesktop.org/libreoffice/dictionaries/plain/en/en_US.dic
        
  • Configure Hunspell’s dictionaries
    export DICPATH="/usr/local/share/words/"
        
  • Load the variable and restart Emacs

Run it like this:

  • Maybe narrow to the content you want to spellcheck. See more in Using Narrowing.
  • Run [UI] Spellcheck
  • Step though your spelling corrections
  • Post happily!
We Can Type It For You: Wholesale

Ever get tired of typing the same words, structure, or content over and over? Org2Blog can make it easy with different forms of Auto typing.

The simplest auto typing is completing the word that you are typing. dabbrev-expand doesn’t need to know much. It considers what you typed, looks around and tries to find something similar, and presents it to you cycling through the matches. “Hippie” Expansion provides similar functionality too. The next thing you should learn about is Org mode Structure Templates.

Org2Blog comes with Org mode templates. Invoke the user interface by striking C-c C-. The kind responsibility of the template is on the right. The shortcut is on the left. Org2Blog already has the entry w in there to insert wp blocks. Strike that to see how it works. If you haven’t used the others blocks gives those a try too. They’re all helpful for blogging. For the most powerful auto typing read more about creating your own templates.

The two most powerful tools for auto typing are Skeletons and Tempo. Built into Emacs they’re easy to access. Take your time learning these and you will get great productivity gains in your personal blogging workflow.

Have You Heard Your New Post?

Reading your post out loud completely changes how you think about it. Specifically it makes it easier to find ways to make it better for the reader. Here are some of the most common challenges resolved and improvements possible found by reading out loud:

  • The ideas in your head make total sense. However that doesn’t mean that you wrote them down in the correct order―the readers might not be able to make sense of it
  • You might see the context of your ideas but haven’t provided enough for the reader to make sense of them.
  • Humans can catch spelling and grammatical errors that computers can not. This one is always surprising and gives you a great feeling when you do.
  • Reveals the tone of the paper. Does it reflect the tone you intended? Is it appropriate for the content?
  • For much more on the entire topic please read Reading Aloud by The Writing Center • University of North Carolina at Chapel Hill. Consider this a MUST READ.

If you are working with Org2Blog then what is the best way to read your post out loud? Using a text-to-speech app is how. The most important part is finding a voice that you like.

Find every text-to-speech voice out there. Listen to all of them. Use different kinds of content. Adjust the speed and tone. Listen over days. In time you will get a few top picks. You might find different voices for different kind of content. For example one voice for reading technical content and another for reading thoughts and reflection. The goal is to get you out of your head so you can hear someone else’s voice. Voice selection is critical. What is the best way to use and do it?

First: you can probably use the built in text-to-speech technology on your computer. On macOS for example it’s built in. There are a number of apps out there to perform text-to-speech too.

Second: CereProc voices, along with all of their other offerings, are well-respected both in the user and commercial user-space. They’re reasonably priced and have a voice to suit everyone.

Try listening to all of your writing. Listen to your posts, letters, essays and everything you can whether it’s in Org2Blog or not. It will make you a better writer and pay off for your entire writing life.

Just Writing

Automatically Configuring Your Environment

You can customize your writing experience by configuring Org2Blog whenever it opens up an Org2Blog file. You do that using org2blog-mode-hook.

Since Org2Blog documents are plain Org documents, Org2Blog can’t tell the difference between them just by looking at them. It needs a hint. The hint is simple: Org2Blog looks for a buffer property named #+ORG2BLOG, and if it finds it, it loads its minor mode. To make this happen, set it up in the Org mode hook:

(add-hook 'org-mode-hook #'org2blog-maybe-start)

Defining Custom Keybindings

In addition to using the menu, you might enjoy some personal keybindings for Org2Blog functions. Here is an example:

Here is how to identify the functions behind the User Interface that you can bind to keys:

/images/HelpMenu.gif

This sample uses the alt name-space because it’s supposed to be 100% free for user key bindings.

(defun org2blog-sample-keybindings ()
  (local-set-key (kbd "A-0") #'org2blog-user-interface)
  (local-set-key (kbd "A-9") #'org2blog-complete))
(add-hook 'org2blog/wp-mode-hook #'org2blog-sample-keybindings)

Logging In Faster

Org2Blog can automatically log you in if you configure a .netrc file in your home directory.

Your configuration should look like this.

machine ⟪myblog⟫ login ⟪myusername⟫ password ⟪myrealpassword⟫

or like this

machine ⟪myblog⟫
login ⟪myusername⟫
password ⟪myrealpassword⟫

Whatever format you use: first replace the contents of the double angle brackets with the actual values, and finally remove the double brackets themselves.

Then, configure your blog using those credentials, as shown below.

(require 'auth-source)
(let* ((credentials (auth-source-user-and-password "⟪myblog⟫"))
       (username (nth 0 credentials))
       (password (nth 1 credentials))
       (config `("wordpress"
                 :url "http://username.server.com/xmlrpc.php"
                 :username ,username
                 :password ,password)))
  (setq org2blog/wp-blog-alist config))

Decorating Your Room

Decorating your writing room truly makes it your own. Emacs themes make it easy with full theme support. Here are some resources to get started:

M-x customize-themes RET to choose them. Even faster: (load-theme 'leuven) is a great place to start

Coming Back For Seconds

Your Second Buffer Post

Perhaps you know some defaults you want for every kind of Entry. When you are ready configure them see these variables and functions:

  • Buffer Entry
    • org2blog/wp-buffer-template
    • org2blog/wp-buffer-format-function
    • org2blog/wp-default-title
    • org2blog/wp-default-categories
    • org2blog/wp-default-tags
  • Subtree Entry
    • org2blog/wp-buffer-subtree-template
    • org2blog/wp-buffer-subtree-format-function
    • org2blog/wp-default-title-subtree
    • org2blog/wp-default-categories-subtree
    • org2blog/wp-default-tags-subtree

With your configuration ready, start creating the Post.

Start by creating a UI [New Buffer]. A template populates your Entry. When you UI [Login] Org2Blog learns about your Categories, Tags, and Pages. Position the cursor on one of those lines and UI [Complete] and either choose a value or complete a value that you began typing. If you want one, you can add a #+DESCRIPTION and a #+PERMALINK too. d Please note that WordPress has a slightly unexpected behavior when completing Categories and Tags. Although Org2Blog can complete unused Categories, it cannot complete unused Tags. Although the unused Tag exists on the blog, it still can’t be completed while writing. Hiding unused tags is normal WordPress behavior for now.

Org2Blog includes some helpers for inserting content into your Entry under the UI [Insert A] menu:

  • UI [More Tag]: The WordPress “Read More” tag. Org2Blog will ask if you want to use a message inside of it, too.
  • UI [MathJax Shortcode]: If you want to use MathJax, this lets you do it.
  • UI [LaTeX Name]: Prove that MathJax is working.
  • UI [Link To Post]: Insert a link to a post from a list of posts on your blog.
  • UI [Link To Page]: Insert a link to a page from a list of posts on your blog.
  • UI [#+ORG2BLOG]: If your Entry doesn’t have the special tag, then it will insert it.

When you are ready, save your new Post. Open the main menu by calling org2blog-user-interface. Since you just created a Buffer Post, look at the menu items under the Buffers column and find the operation you want to perform. Your first step here is UI [Save Post Draft] to save your post on your blog. The language here is essential: actions you’ll perform in your actual blog map directly to menu items here. Next, do UI [View Post] to bring up a web browser so you can read and review your Post. From here, you can iterate through your writing process until you finally UI [Publish Post].

Your First Buffer Page

Working with Pages is virtually identical to working with Posts for a good reason: WordPress sees them as nearly the same thing, and Org2Blog does too. The only difference is that when you work with your Page, use the functions that have Page in the name.

In the walk-through here, that means using UI [Save Page Draft] and so on.

Store Multiple Entries In One File

Using Subtrees

Subtrees are a great way to keep multiple posts in one file. People use this to create a single file for a week or a month and store all entries there. Others, for example, take notes on a chapter or an entire book and keep them in a single place. Just like a plain old Org mode document: subtrees do what they do well.

Power users take note: you can store subtrees that post to different blogs by specifying the URL on the subtree. This “just works” like any other subtree post. Not something you might need much, but when you do, it’s a very cool feature.

The workflow for creating a Subtree Post is virtually identical to a Buffer Post. There are only two (but significant) differences:

  • Use UI [New Subtree] to get started.
  • Review the properties
  • They go in a drawer like any other subtree.
  • Unless you specify an option: the headline populated the TITLE.
  • Unlike a Buffer Entry: Tags are stored in POST_TAGS. Org mode already uses TAGS as a fundamental concept for subtrees, so we had to choose a different property name. POST_TAGS seemed pretty good.

Suppose you ever have your cursor in a subtree, any subtree, and you attempt to use a buffer function. In that case, Org2Blog will not perform the actions and give you a warning, preventing unexpected editing and posting behavior.

You can either save your Subtree Entry in a file or copy and paste it into an existing file.

Using Narrowing

Having already read through the manual and posted a Buffer Entry, you are almost comfortable with how they look. An entry has some configuration data at the top of the page, followed by the title and the content. it’s what you’ll be seeing time and time again. As you write more, you will probably start to wonder, “Why can’t I just store multiple buffer entries in a single buffer in the first place?! (And if you hadn’t already, then you will be wondering after you read the section on using Subtrees to store multiple entries!)” That is an excellent question.

The first reason is that it’s easier to make sense of your Entry types when their home is clearly defined: every single Buffer Entry is stored in a separate file, and multiple subtree entries are stored in a single file. For most users, this is a straightforward approach that handles most workflows that Org2Bloggers will ever require. Whether or not this workflow serves you, this explanation may still leave you wondering what exactly is the difference between a Buffer Entry and a Subtree Entry.

Buffer entries and subtrees are identical in purpose. You write, save, view, publish, and trash them. The only difference between them is their technical format. As you may have seen, buffer entries specify post configuration properties up at the top of the page, and subtree entries specify them just below the subtree. Now to come back around, you might be asking, “Well, if they’re identical, then why can’t I store multiple buffer entries in a single file?” The answer is that yes, you can.

You can store multiple buffer entries in a single file. You write, save, view, publish, and trash them precisely as you would expect. It all “just works,” that is, if you are willing to get a little more technical about using Emacs by learning something about Narrowing.

Narrowing means focusing on some portion of the Buffer, making the rest temporarily inaccessible. The portion which you can still get to is called the accessible portion. Canceling the narrowing, which makes the entire Buffer once again accessible, is called widening. The bounds of narrowing in effect in a buffer are called the Buffer’s restriction.

Narrowing can make it easier to concentrate on a single subroutine or paragraph by eliminating clutter. It can also limit the range of operation of a replace command or repeating keyboard macro.

14.5 Narrowing, from the The Emacs Editor Documentation

When you tell Org2Blog to act upon a single Buffer Entry, say [Save Post Draft], then Org2Blog needs to think that it’s looking at a single Buffer entry. Convincing Org2Blog is easy to do when there is only one Buffer entry because there is only one Buffer Entry. How do you make Org2Blog think that there is only one Buffer Entry when you start storing multiple Buffer entries in a single file, though? The answer is that you do it by merely using Narrowing.

Please read its definition two or three times until you feel good about it. it’s a simple idea, but it can take time for it to sink in. Once you start using it, though, you will find it to be a powerful tool useful for many situations that you deal with as a writer of any kind. Here is how to use it to store multiple Buffer entries in a single file:

  • Create the file blog.org in which to store multiple Buffer entries.
  • Create a Buffer Entry, as usual, using the UI
  • Instead of saving it, copy and paste it into blog.org
  • Give it a notable title and some content.
  • Do the same thing for another Buffer Entry. Now you have two in blog.org.
  • It should look something like this:

/images/Narrowing01.png

Now you are all set to start working multiple Buffer entries in a single file. You’ll go through the process of narrowing it down to a single Entry and working on it just as you’ve already done before. Here are the steps:

  • Identify the second Buffer Entry you just created. You will work on this from here on.
  • Highlight everything from the start of the Entry to the end of the Entry. You can do this using your mouse by positioning the pointer at the top of the post, pressing and holding the mouse button, then releasing it. Another way to do it’s to move the cursor up to that position, press Control-space, then move the cursor to the end.
  • Narrow to the selected region by pressing Control-x n n. That means pushing and holding Control-x, releasing it, then striking n once, and then finally once again.
  • If you did it right then, you would only see the second Buffer Entry. You have just narrowed down to the region you selected: the entire Buffer Entry.
  • From here, you can work with your Entry precisely as you did before.
  • It should look something like this:

/images/Narrowing.gif

As you can see, storing multiple Buffer entries in a single file is pretty compelling in theory. In practice, though, it can result in some confusion when you are in the writing flow, and suddenly, the rest of your file is missing. On the other hand, when you become more adept and working with the Emacs editor, you will find that Narrowing is one of the powerful tools you can’t live without.

If you read this far, then using Narrowing to manage multiple Buffer entries might be the right thing for you. Either way, I’m you know now that this is an option. If this is your introduction to Narrowing then I hope you enjoy its use and have the chance to play around with where it happens to fit into your workflow with Org2Blog or any of the problems you solve using Emacs!

Automatic Image Uploading

WordPress does a great job helping you manage image files using its Media Library. The Media Library User Interface is simple and powerful. Whether you post photos once in a while or you are posting pictures daily running a Photoblog the Media Library integrates nicely with both of and most of the most common blogging workflows. After blogging for a while and developing the beginnings of a personal workflow, it’s an excellent time to start considering where Org2Blog can assist you in working with image files in your Media Library.

Org2Blog can help you do one thing here: automatically upload images to your media library for you. The way it works is that when you publish your post to your blog Org2Blog:

  • Scans your Org2Blog Entry.
  • Finds a link to an image file on your computer.
  • Uploads the file to your Media Library.
  • On publishing
    • Modifies the link, so it points to the uploaded file on your blog.
    • Configures the size of the IMG linked.
    • Inserts the new link in the post.
    • Make a note in the Org2Blog Entry so that it remembers that it already uploaded the image file to your blog.

This approach is suitable for the following workflows:

  • “I Never Want To Touch The Media Library User Interface”
    • “But When I Do I Can Make It And The Entry Consistent”
  • “I Rarely Post Images And When I Do They’re All On My Blog”
    • This features make every image link point to your blog
  • “I’m Very Familiar And Comfortable With HTML, Org mode, And WordPress.”

In other words, this workflow is compelling, simple, and valuable to a very certain skilled and curious kind of user. It might not be for most of you, but if it’s, then you will like it.

By default, this feature is disabled. If, after reading this, you find that you are that kind of user or even just curious about how it works, then you can enable the feature by setting org2blog/wp-image-upload to a non-nil value like this.

(setq org2blog/wp-image-upload t)

And read more about how it works.

How It Works

Org mode is smart about Image links. When it finds images in an Org link for example file: or [[example.png]] it knows to generate an IMG tag in the resulting HTML. All of the file types listed in org-html-inline-image-rules are automatically supported. They work in Org2Blog the same as in Org mode: Org2Blog uses the Org mode HTML exporter to do all of its work which means that everything will work as you expect it.

All of the standard HTML image attributes work by prefacing the image link with a #+ATTR_HTML like and following it with the desired attribute including for example:

:alt
My alt def
:width
:height
:style
border:2px solid black;
:style
float:left;

Just like most exporters, you can also caption the image with a line like this:

#+CAPTION: My image caption

These two capabilities will get you very close to your desired image styling. The last thing to configure is how to handle image thumbnails.

Org2Blog will insert image thumbnails for all of the image files that you upload to your server. If you want to use this feature, first enable it by setting org2blog/wp-image-thumbnails to a non-nil value. Then choose a thumbnail size by configuring org2blog/wp-image-thumbnail-size. After uploading your image files, the inserted link will include a thumbnail preview of your image file.

Now that you have things configured, here is how to move forward with your post.

Create your post exactly as you would expect. Use Image links where you need them. It might look something like this:

[[file:testimage1.png]]

[[./testimage2.png]]

Posting your Entry automatically uploads the files to your blog. A note is stored so that Org2Blog remembers that it already uploaded those image files.

[[file:testimage1.png]]

[[./testimage2.png]]

# testimage1.png https://www.wisdomandwonder.com/wp-content/uploads/2019/03/testimage1-1.png
# testimage2.png https://www.wisdomandwonder.com/wp-content/uploads/2019/03/testimage2-1.png

Org2Blog is wholly disconnected from the Media Library. Therefore, it’s up to you to keep them synchronized. Here is a list of things you are required to manage and synchronize manually:

  • When you delete images
    • locally, you need to delete them in your Media Library.
    • remotely, you need to remove them from your Entry.
  • When you modify images
    • locally, you need to remove the upload note so that they will get re-uploaded to your blog.

Once you are comfortable with the Org2Blog lifecycle with WordPress, it becomes second nature to manage this manually. The first few times you need to handle this, it will be surprising not to see your changes posted. It will come to your mind quickly how to address it.

Automatic Image Uploading is flexible and just works.

Supported Properties

The best way to think about how Org2Blog defines Entry properties is first to think about its metadata. For example, there are posts, and posts can have parents. Each has a numerical identifier, so you’ll deal with the same thing when you work with them in your Org2Blog file. A permalink also behaves precisely how you would expect. If you haven’t looked at post metadata before, then open up a post and click around to see what data it uses.

Next, think about how Org mode metadata can supplement your WordPress data. For example, Subtrees can have a bunch of different date types. Each one of them will work as the date value for the Entry on WordPress.

Since they’re plain old Org mode properties, keep a space between the property name and its value.

  • Buffer Entry
    • DATE
    • TITLE
    • CATEGORY
    • TAGS
    • POSTID
    • PARENT
    • PERMALINK
    • DESCRIPTION (aka excerpt)
  • Subtree Entry
    • For Date
      • POST_DATE
      • SCHEDULEDD
      • DEADLINE
      • TIMESTAMP_IA
      • TIMESTAMP
    • TITLE
    • CATEGORY
    • POST_TAGS
      • Though they’re the same thing, due to technical reasons, when tags appear under a Subtree, they can’t use the TAGS property like an Entry; they use POST_TAGS instead. Please take note of this when you convert an Entry post to a Subtree post.
    • POSTID
    • PARENT
    • PERMALINK
    • DESCRIPTION (aka excerpt)

Tying It All Together

After playing around a little bit, you should have a better sense of what is possible. The following are some key points that will tie everything together:

  • Org2Blog’s fundamental approach to configuration simple. When you configure a feature using a variable, then every blog profile will use that value. That makes it convenient because you are likely to use the same settings on each blog. Think of it as a global configuration; every blog profile will use it. Sometimes you want to configure things uniquely for each blog. For example, you may have a conservative workflow on your work blog but are more easygoing on your personal, so your “confirm before doing things” will be different. Additionally, the default categories and tags would probably be very different too. See org2blog/wp-blog-alist for details.
  • You only have to UI [Login] when you want to save or publish your post. However, you won’t have code completion for your Categories, Tags, or Parent pages until you log in. Org2Blog will ask you which blog to log into: if there is only one, it won’t ask. If there are none, then it will warn you.
  • You only have to UI [Logout] if you are going to start blogging to a different server than you began. All it does is clear out the local variables used to store tags and categories from your blog.
  • When you UI [Save] an already published entry, WordPress will change that Entry into a Draft. The WordPress UI works the same way. If you have never used the WordPress UI before, now is the time. Sometimes using Org2Blog without any WordPress familiarity results in surprises when you forget to either publish or trash your draft and now there is a mysterious draft just sitting out there.

Whenever Org2Blog can’t do what you asked and understands why it will show you a message in the minibuffer and the Messages buffer. Suppose it doesn’t know why it gives you a warning in the minibuffer and the Warnings buffer. You’ll find details there that can both help provide you additional information to figure out what happened and resolve it yourself or to copy and paste and fill out an issue report on the issue tracker. Be sure to post issues before you start to get upset. it’s probably something we have all faced before, and talking about it will usually get it resolved pretty quickly.

  • You can store a single Entry in a file (a Buffer Post). You can store multiple entries in a Subtree Post. See more below.
  • Custom Key Bindings: When you use the menu, you will quickly find that you use 20% or the commands 80% of the time. For example, you may only ever use Buffer Posts and never use any other menu item than UI [Publish Post]: in that case, you only ever need to call one function! The menu item(s) to do what you want most of the time will quickly become “muscle memory.” At that point, it will be easy for you to configure your custom keybindings for the functions that back up the menu item. To find the function for the menu item, just open the menu, choose UI [Help], select the menu item, and Org2Blog will present you with the function that does the actual work. Take that function name and bind it to a key within this mode. See sample-keybindings at the beginning of this document for an example of how.
    • Here is a screenshot of the Help menu–Just Hit “h”:
      • /images/HelpMenu.gif
  • See org2blog-mode-map or org2blog/wp-keymap-prefix for details of the default keymap and prefix key.
  • You may find it just as easy to find a convenient key binding org2blog-user-interface and use that instead.

More Functionality

Org2Blog also helps you do many more good things. See below.

Global And Blog Specific Configuration

See org2blog/wp-blog-alist to learn about how to configure any number of your blogs. You’ve already seen an example of how to configure this value, and the documentation goes into more detail.

There are two ways of configuring features: global and blog specific.

If you know that you want a feature configured the same way for every blog in your configuration, you should configure the global value. For example, if you wish always to be prompted before posting, then (setq org2blog/wp-confirm-post t). Now you will be prompted before every post.

Imagine, though, that you don’t need the prompt for a personal blog where it’s OK to make many changes after posting. Here you can override the global setting by setting the value directly in the individual blog configuration. It would look something like this.

'("myblog"
  :url "https://www.wisdomandwonder.com/xmlrpc.php"
  :username username
  :password password
  :confirm t)

In the interest of brevity, the name of the global variable is a lot bigger than the name for configuring the individual blog. If you are overriding a global value, you already know a lot about it and don’t need to see its full name again.

Most variables are optional, but two variables * must* be configured within this system:

  • Global org2blog-xmlrpc or blog specific :url
  • Global org2blog-username or blog specific :username

An easy way to work with the difference between the global variable name and the blog specific name is to read the documentation for the global variable. It will show you the purpose of that setting, example values, and the property name if you want to use it in the blog-specific configure. it’s a compelling and convenient feature that makes working with multiple blogs very easy and even fun.

Inserting Things

Most Org2Bloggers end up inserting a few elements common to all of us. The menu item UI [Insert A] captures some of them. You can get help on them for more details and play around with inserting them too. You will be pretty surprised as to how often you end up using them:

Confirming Things

Sometimes you want to be prompted before doing things. Here are some of the possibilities see:

  • org2blog/wp-confirm-post
  • org2blog/wp-safe-trash
  • org2blog/wp-safe-new-entry-buffer-kill
  • org2blog/wp-show-post-in-browser

Raw HTML Creation

Sometimes Org2Blog doesn’t know how to generate the HTML that you need. For example, you might be working with special requirements for using a ShortCode. Another example is that you might be utilizing custom page elements that aren’t accessible any other way. The simplest example you may have already seen above is the WordPress more tag. Whatever the case, the easiest and most straightforward way to get what you need is to insert the raw HTML content you need directly.

To include a small snippet of raw HTML code in the Org file so Org2Blog can insert that HTML code in the output, use this inline syntax: @@wp:...@@. For example:

@@wp:<!--more Custom WordPress Tag-->@@

For larger raw HTML code blocks, use these WP export code blocks:

#+BEGIN_EXPORT wp
  All lines between these markers are exported literally
#+END_EXPORT

Create it by UI [Insert A].

Note: In the previous version of Org2Blog, Org2Blog raw HTML export blocks used the html tag to include raw HTML. Using the html tag had the convenient side-effect that Org2Blog inserted the raw HTML whether posting your Entry to WordPress or exporting the same document to HTML. However rarely used: this was the original behavior. Since it was rarely used, though, Org2Blog switched over to use the wp tag. wp is easier to remember and a good reminder of how you are using the structural block. That said: both wp and html do and will continue to work the same way. In the future, though, please use the wp tag instead.

Source Blocks

Org2Blog has first-class source block support. The headlines in this section explain how.

Org2Blog source blocks support both the #+NAME and #CAPTION property.

Note: When you have, and on a source block, then the values are included in the post too.

Warning: Source blocks do not work inside of plain lists.

Out of the box, source blocks are converted into <pre> tags. This is the most durable and straightforward approach: it’s plain old HTML. And another option is to SyntaxHighlighter Evolved.

Here is how they look and work.

Plain Source Box Format

First make sure that Org2Blog will generate plain on <pre> tags like this:

(setq org2blog/wp-use-sourcecode-shortcode nil)
#+CAPTION: My caption is my passport
#+NAME: Demo
#+BEGIN_SRC emacs-lisp
(setq pass "Hi")
#+END_SRC

Here is how the built-in syntax highlighting looks:

/images/SourceBlockNormal3.png

SyntaxhighLighter Evolved

SyntaxHighlighter Evolved is an extremely popular plugin for rendering source code. It supports a bunch of languages and configuration parameters (see here) in addition to open-source custom plugins for other languages.

Since you are an Emacser, you probably want to add support for Emacs-Lisp immediately by using rehanift’s wp-syntaxhighlighter-brush-lispy. If you’ve never installed a plugin before then, there are instructions on the page. The only thing that you might do differently is to create the folder wp-syntaxhighlighter-brush-lispy and copy the plugins files there.

To enable SyntaxHighlighter Evolved you need to set the variable org2blog/wp-use-sourcecode-shortcode to t.

(setq org2blog/wp-use-sourcecode-shortcode t)

Configure your source blocks for SyntaxHighlighter like below. SyntaxHighlighter Evolved automatically uses the default global settings you configured in it’s WordPress plugin page.

#+CAPTION: My caption is my passport
#+NAME: Demo
#+BEGIN_SRC emacs-lisp
(setq pass "Hi")
#+END_SRC

When you want to override it’s global configuration use

#+ATTR_WP: :syntaxhl light="true"

placed before the source block. The :syntaxhl property tells Org2Blog that everything following it’s a configuration parameter for SyntaxHighlighter. Those values get passed on. The #+ATTR_WP line must immediately precede the #+BEGIN_SRC line. it’s easier, though, to configure it globally and never touch it again.

With SyntaxHighlighter Evolved enabled:

/images/SourceBlockSyntaxHighlighterExposed3.png

SyntaxHighlighter Evolved Is Broken Now What?!

Sometimes your source block contents cause this plugin to do the unexpected. It will look at best horrible and more likely just wrong. Then to put it simply, your first reaction will be, “Why doesn’t this work😠?!” For example, your source block might be rendered as plain text without any special formatting. If you run into this situation, start debugging it without Org2Blog even involved by editing the Entry directly on WordPress.

For example, remove all of the contents of the source block and type in a single word. Preview the page. It probably worked correctly, so now paste in the first line of content that you removed just now. Keep repeating until it doesn’t work correctly anymore. If it looks like the problem is in Org2Blog, then please create an issue ticket, otherwise considering reporting the issue to the plugin maintainer.

When you run into an issue and want to “make the content look right,” then the easiest thing to do is manually wrap it in an HTML <pre> block.

Here is how to do it:

#+BEGIN_EXPORT wp
<pre>
o0O s5S z2Z !|l1Iij {([|})] .,;: ``''"" www
a@#* vVuUwW <>;^°=-~ öÖüÜäÄßµ \/\/ -- == __
the quick brown fox jumps over the lazy dog
THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG
0123456789 &-+@ for (int i=0; i<=j; ++i) {}
</pre>
#+END_EXPORT

LaTeX Support

amsmath Support

Org2Blog strives to adhere to the standards in https://www.ctan.org/pkg/amsmath.

WordPress LaTeX

WordPress has LaTeX support built-in. Although it’s incomplete, it’s built-in, so read it to figure out if you need more functionality than it provides. The biggest room for improvement is to implement the amsmath equation autonumbering. The easiest way to request enhancements to WordPress is to start by reading here.

Org2Blog includes its own exporter ox-wp. It does 80% of everything it needs. The biggest room for improvement is to implement the amsmath equation autonumbering.

MathJax

MathJax is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notation that works in all modern browsers.”

Whether you use MathJax with a WordPress plugin, manual inclusion, or any other means, you need to be aware of MathJax’s CDN options: you need to get it from somewhere, so choose one of the sources and note the URL.

First, tell Org2Blog to disable translation to wp-latex syntax because you want to use MathJaX instead.

(setq org2blog/wp-use-wp-latex nil)

Then the easiest way to use MathJaX with WordPress is to set up this MathJax-LaTeX plugin.

  • Steps
  • Install it
  • Configure it
  • Force Load: NO
  • Using MathJaX adds time for loading your post. it’s probably imperceptible, but you probably want page loads to be as fast as possible. If you plan to use MathJaX a lot or don’t mind the nearly imperceptible load time even if you are not using it, enable this setting: your browser will load MathJaX on every post.
  • If you are not going to use it frequently or want to require it when you need it manually, then use UI [Insert A] followed by UI [MathJaX Shortcode] to insert the MathJaX shortcode. When WordPress sees it, then MathJaX will get loaded for the page.
  • Default [latex] syntax attribute: Inline
  • Use WP-Latex syntax? YES
  • Use MathJaX CDN Service? NO
  • MathJaX no longer hosts their CDN, but there are many alternatives.
  • Custom MathJaX location? YES
  • This explains how to load and configure the library manually. Please read it, so you know what the plugin is doing.
  • Copy the CDN URL up to and including the MathJaX.js. Everything after that are configuration options
  • MathJaX Configuration: TeX-AMS_HTML

Now test your installation:

  • Test it out using these (and more) examples
- The word LaTeX
  - $\LaTeX$
- Inline
  - $\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$
- Equation
  - $$\sum_{i=0}^n i^2 = \frac{(n^2+n)(2n+1)}{6}$$

You should see something like this:

MathJax Example

MathJaX’s default configuration doesn’t default to the amsmath equation behavior. A future update here will explain how to enable it. You can read about the topic in great detail here.

Migrating Org Mode Files To Org2Blog Files

If you want to turn an existing Org mode document into an Org2Blog document, you only need to populate the required properties. Here is the easiest way how:

  • Create a UI [New Buffer] or UI [New Subtree and copy those default property values
  • Copy them into your file and populate them with what you want
  • If you want to use this Entry to provide content for an existing post on the server, then populate POSTID. When you do this and save or post your Entry, whatever was on the server will get replaced.

That is the process to migrate a single Org file; it’s pretty simple. How do you migrate a lot more files, though?

Fortunately, it’s still simple. Rather than performing the steps manually, you can automate the process with code. The code will do what you did by hand instead of having to type it all yourself. First, start by making sure that you are familiar with how to perform those steps manually.

First, take a post and convert it by hand. It will prove to you that you understand the process, you can log into your blog, and that everything works correctly. That is all you need to begin automating.

Create another post and convert it by hand. This time use the API to submit it. Look at the code for org2blog--test-buffer-post to see how it works. That code goes through all of the steps of posting, including demonstrating how to make changes. You don’t need to do that for migration. You only need to log in and publish the post (if you want to see a result code, read the function doc). Now you are ready to begin automating the migration of all of your Org files. When you have any questions, please be sure to reach out here, so your migration is as pleasant and fast as possible.

Export WordPress To Org

Once you start using Org2Blog for all of your new posts, you will want to start using it for all of your old posts too. The easiest way for that is to export your WordPress database to Org files. This project performs that export. Reports of successful exports of 2000+ entries are common.

Using Entry Templates

Out of the box, Org2Blog populates your new Buffer Entries with a template. If you want to change it you can configure org2blog/wp-buffer-template or org2blog/wp-buffer-subtree-template-prefix.

The former takes some reading and study of the code to utilize. A future release will simplify it in a future release. The latter is a template that is inserted without any value substitution.

Tracking Entries

You can automatically track all of the Posts that you make. Why might you want to do this?

Perhaps you want a logbook of when you published your Entries versus when you wrote them.

Maybe you want a single place to keep track of when you made all your Posts so you can leverage Org mode’s feature to get an overview of how you’ve been posting in terms of volume or topics covered and use that information to decide how to move forward. Each scenario is pretty specific, and it will probably be the same for you.

In my case, sometimes I want a record of what I did post so I can compare it to what is out on the server because sometimes I delete entries on the blog without deleting their source files in Org mode, leaving me confused about what is going on.

Indeed there are more examples than I could make up here. Please send me some scenarios that you use this feature—and speaking of that, here is how to use this feature.

Tell Org2Blog where to do the tracking by telling it two things:

  • What is the file name you want to store the tracking data in
  • Under what headline do you want to store that data

Either specify at the top level programmatically:

(setq org2blog/wp-track-posts (list ".org2blog.org" "MYBLOGNAME"))

Or in your blog config

(let* ((credentials (auth-source-user-and-password "wisdomandwonder"))
       (username (nth 0 credentials))
       (password (nth 1 credentials))
       (track-posts (list "org2blog.org" "MYBLOGNAME"))
       (config `(("wisdomandwonder"
                  :url "https://www.wisdomandwonder.com/xmlrpc.php"
                  :username ,username
                  :password ,password
                  :track-posts ,track-posts
                  :confirm t))))
  (setq org2blog/wp-blog-alist config))

when you post entries they will get logged in your log file under the headline specified. For example:

* MYBLOGNAME

** [[/Users/gcr/tmp/testpost.org][Hello, Buffer Post]]
:PROPERTIES:
:POSTID:   12578
:POST_DATE: 20190810T02:41:00+0000
:PUBLISHED: No
:END:

Hi.

If you specify a file that Org2Blog has some problem accessing, it will try creating and loading the file specified by org-directory. That way, you won’t lose anything. You can rename the file later after you get the desired file set working. The solution is usually to make sure that you specify the whole path either absolutely or relatively. It won’t work right to list a file name without its place in the directory system.

If it can’t do either, then you will get a warning message saying why it failed. The solution is usually to correct the file name or set the org-directory to something valid.

Doing Things After Saving And Publishing

Now your post or page exists both in your Org-Mode file on your computer and also in WordPress itself. That page or post inside WordPress contains a lot of metadata, and you might be interested in some of it. Here is documentation covering all of the fields. You can easily access that data using a hook function.

After publishing your post or page, Org2Blog calls the functions in org2blog/wp-after-new-post-or-page-functions passing them the post or page metadata. Maybe you’ve never seen a hook function like this before because it takes an argument. They’re still just plain old functions. Here they need to accept one argument so that Org2Blog can give you that metadata. it’s pretty simple.

Here is an example that displays your post or page information in the *Messages* buffer:

(add-hook 'org2blog/wp-after-new-post-or-page-functions (lambda (p) (pp p)))

Parent Pages

Many times you might find the need to display sub pages under a main page. WordPress allows you to create a parent page and then create child pages under it. ― What Is A Parent Page In WordPress

Use this feature by adding the Parent property to your Buffer Entry like this:

#+PARENT: My Parent

or your Subtree Entry like this:

:PARENT: My Parent

You can use UI [Completion] on it too.

Publishing And Sharing With Everyone

Living with first-class WordPress support is fun and comfortable. Some day though you may want to publishing your writing in a different format.

For example say you want to share your writing as flat text files with some of your techie friends. Or maybe you want to share them as PDF or Word files with your other friends and family. Because you ultimately writing Org mode files you can export your file to just about anything.

When you write your Entries with Org2Blog you are making your writing future-safe and more shareable than any other tool out there.

The Huge Power Of Customizations

By now, you’ve probably seen that Org2Blog can be tailored to your workflow. If you haven’t, the following will show you how easily that it can. If you already have, then you’ll see how you can make it even better. It all comes through Customization to your configuration.

The fastest way to learn about everything possible with Org2Blog is to read the documentation for the customizations. You’ve already seen some of them in examples, and that is a great way to start learning about them. When you have a particular itch to scratch and find answers in here, the support board, or function documentation, they’re all great ways to learn more. You can also benefit a lot from searching for all of the customization variables and reading the documentation for them. Here is how:

  • Call M-x occur
  • Insert (defcustom and hit enter
  • A list of defcustom statements appears in your buffer
  • Place the cursor on one and hit return
  • You are now in a buffer with the cursor positioned at the source code of that defcustom and ready to read its documentation

When you have time, read one or two of them and see where they might fit into your workflow.

Sample Posts

There are so many ways to work with posts. Here are some real-world examples.

Buffer Post

#+BLOG: wisdomandwonder
#+POSTID: 11659
#+ORG2BLOG:
#+DATE: [2019-02-01 Fri 19:38]
#+OPTIONS: toc:nil num:nil todo:nil pri:nil tags:nil ^:nil
#+CATEGORY: Emacs,
#+TAGS: MathJax, Org2Blog, Org mode, WordPress
#+TITLE: Blogging With Emacs🐃 From Org2Blog🦄 to WordPress

[mathjax]

Blogging from Org2Blog to WordPress /just works/ and that is just about all there is to it. All of the markup works. Even MathJax works:

Subtree Post

* VIM Changes Acronym to "VIM Imitates eMacs"
:PROPERTIES:
:BLOG:     wisdomandwonder
:DATE: [2019-03-21 Thu 07:09]
:OPTIONS: toc:nil num:nil todo:nil pri:nil tags:nil ^:nil
:CATEGORY: Emacs,
:POST_TAGS: emacs
:ID:       o2b:3F021C4E-E80A-4DD4-AA13-A91835F0023D
:POST_DATE: [2019-03-21 Thu 07:26]
:POSTID:   12271
:END:

I ran ~M-x butterfly~ and we both smiled as VIM and Emacs converge.

Changelog

See HISTORY.

Credits

Testimonials

  • I’ve recently discovered the absolute joy that is writing and publishing wordpress blog posts using Emacs 24 and org2blog. – cpbotha
  • Org2Blog is the reason I want to use Emacs for blogging. – Nic
  • Yesterday I installed Org2blog, which allows me to write my blog posts in Emacs org-mode and push them to my WordPress blog from within Emacs. So far I like it a lot! One less reason to leave Emacs :-), and hopefully also a reason to blog more often. – Lennart
  • org2blog is a beautiful plugin to post to wordpress blog. – Chen Bin
  • I love blogging with org2blog. – Jon Sander (jcs)
  • For those of you who’ve noticed that I’ve started being a more active blogger over the last few weeks, there’s a good explanation: I’ve discovered org2blog. – Ezra Glenn
  • Org2blog is THE best tool to publish from org-mode to WordPress. – Mistan
  • So you may wonder why I’m now blogging like there’s no tomorrow. The reason is org2blog/wp, a tool to publish directly from Org-mode in Emacs to WordPress blogs such as Hypotheses. – Michael Piotrowski

When Things Go Wrong Or Could Go Even Better

When Things Go Wrong

Plan on staying positive even when things don’t go as planned!

It probably isn’t unique to you, and it’s probably something easy to fix. Most surprises faced have to do with defects in the code, blog issues, and personal configurations. Together we will figure out what isn’t going quite right and make things right again.

Here is where to begin:

  • Study the README to learn how the feature you are reporting is expected to work.
  • Review the documentation by searching for keywords: it might be a documented feature.
  • Go here to search for the issue and maybe report it. Don’t hesitate because it’s easier to close an already solved issue than go through the pain of trying to figure out a solved problem.
  • If you need to dig deeper, read the documentation for org2blog-user-report. It walks you through the entire process of investigation. It can be intimidating at first. As you read through it, though, you will find that Org2Blog has a few clearly defined layers. When you “see” them, they will make a lot of sense. Once you are comfortable with the ideas there, enable reporting with UI [Reporting On]
  • Read about some past challenging issues and how debugging resolved them.

When Things Could Go Even Better

Org2Blog always has room for new and improved features. The process for making those improvements is welcomed and straightforward.

Here are the steps:

  • Ideas for new future features are captured in FUTURE file. Please read and review it to see if the feature is already listed in there.
  • Review the already submitted entries to see if it’s already in there. Typically ideas will either assigned for implementation or moved in the FUTURE file relatively quickly.
  • If you don’t find it in either of those places, then fill out a request here. Either way, don’t worry too much about tracking down whether it was listed or not already: the most important thing is figuring out what to do with it next.

Similar Applications

Development

See DEVELOPMENT.

License

/images/logo-icon.png