The Org2Blog Project README.org

About

Blog from Org mode to WordPress.

Table of Contents

Requirements And Compatibility

Org2Blog runs against the version of Org mode that comes pre-loaded with
Emacs. Org2Blog will require a relatively recent version of Emacs to
keep it up to date with Org mode.

Org2Blog requires at least Emacs 27.1 and Org mode 9.1.9.

That is the minimum version required and will probably work fine with
most newer versions too.

Installation

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 are
made. It contains new features and bug fixes faster than the stable
version. Although it is 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 is 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 is 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

Here is where to start:

The constant org2blog-def--package helps manage Org2Blog's
dependencies. Here are helper functions to quickly get you started:

  • org2blog-def-checkout-statement creates Git commands to get the
    code from GitHub into the directory you want it stored. Call it and
    input the directory name. Finally copy and paste the commands from
    *Messages* into your Terminal to run them.
  • org2blog-def-load-statement creates Elisp code to load the
    libraries. Call it and input the directory name. Copy and paste the
    commands from *Messages* into your init file. Finally
    run them. Now they will get loaded each time you start Emacs.

For example, you should see something like this:

git clone https://github.com/hniksic/emacs-htmlize.git /Users/gcr/mysrc/htmlize

And this

(add-to-list 'load-path "/Users/gcr/mysrc/htmlize")

Now you've got everything you need to run Org2Blog against its source
code.

With this set up you can start playing around with things and even
making changes. When you scratch an itch: create your branch and submit
a pull request. It's fun, easy, and makes Org2Blog better for all its
users.

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 is 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:
  • Create a brand new 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 post 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 post-draft 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 post it, 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 is 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 is not a race; it is 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":

The "Insert Things" Menu":

Category Completion:

Readme:

Customizations Documentation Menu:

The 6 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 are 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 is a (destination) post or a page. With that
simplicity in mind, please read on to learn about the options for
learning more.

Another way to play around with it is to try out all of the menu items.
Don't worry, though, because it is 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 are probably overly
detailed, but it is 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 is
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 is 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

  1. Just Writing

    1. 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.

      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 [鈥淚nsert 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 [鈥淟aTeX鈥?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 entry, 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].

    2. 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.

  2. 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)

  3. 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:

    This sample uses the alt name-space because it is
    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)

  4. 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 鉄猰yblog鉄?login 鉄猰yusername鉄?password 鉄猰yrealpassword鉄?

    or like this

    machine 鉄猰yblog鉄?
login 鉄猰yusername鉄?
password 鉄猰yrealpassword鉄?

    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 "鉄猰yblog鉄?))
       (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))

Store Multiple Entries In One File

  1. 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 is a very cool feature.

    The workflow for creating a subtree entry is virtually identical to
    a buffer entry. 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.

  2. 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 is 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 is 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 are 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
    is 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 is 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:

    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 is 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:

    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 is 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 Are 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 is, 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.

  1. 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 is 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 are plain old Org mode properties, keep a space between the
property name and its value.

  • Entry
    • DATE
    • TITLE
    • CATEGORY
    • TAGS
    • POSTID
    • PARENT
    • PERMALINK
    • DESCRIPTION (aka excerpt)
  • Subtree
    • For Date
      • POST_DATE
      • SCHEDULEDD
      • DEADLINE
      • TIMESTAMP_IA
      • TIMESTAMP
    • TITLE
    • CATEGORY
    • POST_TAGS
      • Though they are 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 is 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":
  • 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 is 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 is 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 [鈥淚nsert 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

An easy way to create this block is to use Structure
Templates.
Org2Blog comes with a template for creating raw HTML code blocks.
However, it doesn't load it automatically. To automatically add the
template each time you start Emacs, add
(org2blog-structure-template-add) to your startup file.

Inside of your file type <wp then strike TAB to create the snippet,
or <WP to create the raw HTML block you need.

You will know when you need this feature and will immensely enjoy being
able to use it.

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 is plain
old HTML. And another option is to SyntaxHighlighter Evolved.

Here is how they look and work.

  1. 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:

  2. 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 is a configuration
    parameter for SyntaxHighlighter. Those values get passed on. The
    #+ATTR_WP line must immediately precede the
    #+BEGIN_SRC line. It is easier, though, to configure it
    globally and never touch it again.

    With SyntaxHighlighter Evolved enabled:

    1. 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

  1. WordPress LaTeX

    WordPress has LaTeX support
    built-in. Although it is
    incomplete, it is built-in, so read it to figure out if you need
    more functionality than it provides. Org2Blog attempts to address
    some of its deficit by implementing the feature itself: in
    particular, support both additional embedded math formats and the
    equation environment. Org2Blog doesn't address everything you may
    need, so consider submitting a feature request when you find missing
    LaTeX markup. org2blog/wp-use-wp-latex is enabled by default.

  2. 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 is 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 [鈥淚nsert 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-MML_HTMLorMML

    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:

    <img src="https://github.com/org2blog/org2blog/blob/v1.1.0/images/MathJax.png" alt="MathJax Example"
width="50%" height="50%">

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 is pretty simple.
How do you migrate a lot more files, though?

Fortunately, it is 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 posted your entries versus when
you wrote them.

Maybe you want a single place to keep track of when you did 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 are still just plain old functions.
Here they need to accept one argument so that Org2Blog can give you that
metadata. It is 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)))

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 are 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.

Some Questions And Some Answers

In some ways Org2Blog can be surprising. Since it bridges that gap
between Org mode documents and WordPress blog posts sometimes there can
be a little friction. That is where most of the questions come from in
the form of something like "Why does Org2Blog ...fill in the blank...?
Because it is really weird!". Be at ease though, this section should
clear up some the weirdness ASAP.

Why Does Org2Blog Talk About Save, View, Publish, And Trash So Much?

Most software out there has some version of Create, read, update and
delete
(CRUD). In our case it has to do with WordPress Entries and Pages. In
techie language you would talk about CRUD'ing them. In WordPress
language you talk about Saving, Viewing, Publishing, and Trashing.
Org2Blog chose to use the WordPress language: it is less surprising and
makes it easier to keep the idea that Org2Blog fits into your WordPress
workflow in your mind.

Take time to learn that workflow outside of Org2Blog. It will save you
from uncomfortable situations where your entry enters a weird state.
At least it can feel weird. For example when you make changes to an
entry and save it, it will enter the Status of Draft. From
here you only have two options to move it back to a Published state:
Save the changes you made, or Save it without any changes. If you've
never encountered this before it can be upsetting when the URL for your
entry always says preview=true. Whenever you get into a confusing
situation be sure to access your blog inside of the WordPress UI to find
out more about what is happening. Usually it is something really simple.
Then step back and see what Org2Blog is doing within the WordPress
workflow.

Those words are also used because they reflect the natural workflow of
working with WordPress that looks like this:

猱嶴ave 鈫?View 鈫?Publish猱?Trash鈦?

Blogging with WordPress is an iterative workflow, going through the
cycle as many times as desired. Org2Blog supports and facilitates this
workflow very well. This workflow is so important in fact that the
entire right side of the main menu is dedicated to realizing it.

Why Does Org2blog Talk About Buffers, Subtrees, Posts, And Pages So Much?

WordPress doesn't see much difference between a Post and a
Page, so Org2Blog doesn't either. Here is what I mean:

Blog is shorthand for Web Log. Every post you make on your
blog is called an Entry. Org2Blog stores
Entries in either a Buffer or a Subtree. Every
Entry can be either a Post or a
Page. This simplicity can actually lead to some less
comfortable situations where you accidentally publish one thing as
another (it is pretty easy to fix anyway though).

Although Org2Blog is implemented how WordPress works, it can surprising
to see these words used. However you'll get used to it pretty quickly.

Why Isn't The Package Name Org2WordPress?

When Org2Blog was created its technical name, its package name, was
org2blog. Unbeknownst to us there was another package out there named
Org2BlogAtom with the same package name!

These unforeseen naming conflicts do happen more than you might thing
and it had to be resolved. Since they both had the same package name
they needed some way to differentiate themselves from each other and the
slash/suffix approach was chosen resulting in org2blog/atom and
org2blog/wp. So why doesn't this package say 'Org2Blog/WP' all
over the place today?

That is another historical accident. This package became known simply as
Org2Blog without the /WP, and the name stuck. Part of the reason might
be that Org2BlogAtom seems
unavailable and no longer
maintained. Its wiki
page hasn't had any updates on the topic either. Having made this
decision it made sense to change the artifact naming scheme to
org2blog instead of org2blog/wp. It is easier to understand and
adheres to artifact naming best practices. Over time existing /wp
names are slowly being migrated. That still doesn't answer the original
question yet!

Org2Blog is blogging software. You write everything in Org mode and
publish it to a blog. It is pretty simple. Currently it publishes to
WordPress. Could it publish to any other blog? With some work
definitely. Its impossible to rule out using Org2Blog to blog to other
blogs in addition to WordPress.

In that historical context and considering goals today the name remains
Org2Blog instead of Org2WordPress.

What Is MetaWeblog And Why Is It In Org2Blog?

The MetaWeblog API is an
application programming interface created by software developer Dave
Winer that enables weblog entries to be written, edited, and deleted
using web services.

WordPress
implements the
API.

Org2Blog implements a MetaWeblog client in metaWeblog.el.
It has two uses.

First it implements an XML-RPC MetaWeblog client. This is generic and
should work with any blog software that exposes the API.

Second it implements a WordPress XML-RPC
client.

Org2Blog uses this client to work with WordPress

metaweblog.el is provided a package from Org2Blog to make
it reusable for others via the standard packaging system.

Why does Org2Blog Use Both The XML-RPC MetaWeblog and WordPress API

Both APIs are required to get the job done.

For historical reasons the WordPress API client is implemented inside of
metaWeblog.

How does Org2Blog manage autoloads?

Preemptive TL;DR: It doesn't---Packages are not supposed to manage
autoloads.

The autoload
facility
delays loading Elisp files until their contents are actually used
improving Emacs startup times. To state it even more simply: it is how
to lazy-load packages. Anytime you see code prefixed with the default
magic autoload
comment
;;;###autoload you can use it (for example call a function) before the
its package is loaded. Org2Blog has lots of autoload'ed functions.
Emacs learns about them by reading the autoloads file. There are three
entities that can manage the autoloads file along with their decision
of whether or not they will:

  • Org2Blog: Won't do it
  • You: Should not do it
  • A Package Manager: Will do it by design---And Easily

Org2Blog does not manage an autoloads file because packages are not
supposed to manage it. Usage and management of an autoloads file is a
personal decision made by the user or their choice package manager. By
design packages never assume the responsibility. For reference at
the moment there are 5,258 packages in MELPA and only one of them
includes an autoloads file. Like anything there are exceptions to the
rule but Org2Blog isn't one of them. Another entity who can manage the
autoloads file is you.

With an inordinate amount of effort you can create the autoloads file
and load it yourself. However it is likely not worth the effort. Disk
drives today are fast. Disk drives of 20 years ago are almost as fast
(this applies to whatever the current year is). Drive speed improvements
take care of the load time issue. That leaves the time required to
manage the autoloads file. If you want to manage the autoloads file
yourself you need to create, load it, and update it whenever autoloaded
values are changed. It is even more work better left to a program. If
you insist then have at it. Otherwise make your life easy and let the
package manager do it for you.

Package Managers by design are responsible for creating the autoloads
file for you. It requires no effort and likely zero customization on
your part. It is that simpler. Even better though would be something
simpler.

The simplest way to handle autoloads is simply never to use them at all.
There is essentially never a good
justification
for using autoloads. There is almost always another way to achieve your
goal. The worst part is that once people start relying on that features
autoload behavior you can never remove it later on without creating pain
for the user.

The best code is the code that doesn't exist: that includes autoloads.
Bit by bit Org2Blog will keep moving towards a future without them.

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 is 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 is 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
    is 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.

Development

  • You may have already set up your codebase to run Org2Blog, but if
    you haven't, then find out how up in the Installation section.
  • Readme

    • If you decide to make changes to the readme, you need to rebuild
      the table of contents. Install the package
      org-make-toc. Then
      call org-make-toc. You can also install it by hand like you
      did the other packages, like this:

      cd ~/src
git clone https://github.com/magnars/s.el.git
git clone https://github.com/magnars/dash.el.git
git clone https://github.com/alphapapa/org-make-toc.git

      Use this code to load it:

      (add-to-list 'load-path "~/src/s")
(require 's)
(add-to-list 'load-path "~/src/dash")
(require 'dash)
(add-to-list 'load-path "~/src/org-make-toc")
(require 'org-make-toc)

    • You may wish to automatically update the Readme's table of
      contents by adding these file local variables:

      # eval: (require 'org-make-toc)
# before-save-hook: org-make-toc
  • Contributing

    • Read the contributing guidelines.

    • Before your commit make sure that byte-compile-file,
      checkdoc, and package-lint-current-buffer don't report any
      errors. The first two are included with Emacs. package-lint
      you can either install using MELPA or you can also install it by
      hand like you did the other packages, like this:

      cd ~/src
git clone https://github.com/purcell/package-lint.git

      Use this code to load it:

      (add-to-list 'load-path "~/src/package-lint")
(require 'package-lint)

    • Note: Org2Blog uses non-standard separators in its naming.
      The naming will address it in a future release.

      error: `org2blog/wp-version' contains a non-standard separator `/', use hyphens instead (see Elisp Coding Conventions).
  • Testing
    • Programmatic Interactive System Testing
      • Working with posts and pages is the most critical 80% of
        this package. This core functionality should always work
        well and be easy to test. And it is easy to test. It only
        takes 3 steps to get the system tests running.

        • Define three system variables for the blog you will test
          against like this:

          O2BXMLRPC="https://yourblog.com/xmlrpc.php"
O2BUSER="user"
O2BPASSWORD="password"

        • Load and evaluate System Test
          Program          .

          • Start Emacs in an empty environment before loading
            Org2Blog and performing the testing by starting
            Emacs like this: emacs --no-init-file
          • Load (or open and evalute it) it because it is not a
            package.

        • Now you've got everything you need to start
          automatically going through the entire blogging process.
          The test functions will log you in, create and display
          posts, modify them, publish them, and finally trash
          them. At each step, there is a pause so you can observe
          what is happening on the blog. Testing is a great way to
          see how the workflow works, too, if you've never
          blogged before. These four functions cover everything.

          • defun org2blog--test-buffer-post
          • defun org2blog--test-buffer-page
          • defun org2blog--test-subtree-post
          • defun org2blog--test-subtree-page
      • If you need a test WordPress system to use you can set up a
        free WordPress blog here.
    • Manual System Testing
      • Here is a detailed Test Plan for
        manually testing every feature of this system. It is a great
        way to see everything that can be done with Org2Blog.
  • Release Process.
  • Rules

License

posted @ 2023-04-29 22:54  lywon  阅读(17)  评论(0)  编辑  收藏  举报