blogpost – WordPress blog client
blogpost [OPTIONS] COMMAND [BLOG_FILE]
A WordPress command-line blog client. It creates and updates blog entries directly from AsciiDoc (or HTML) source documents. You can also delete and list blog entries from the command-line.
- Manages WordPress Posts and Pages.
- Automatically uploads media files (images, video, audio).
- Only posts new or modified content and media files.
- Manages WordPress blog categories.
- cat, categories
- Specify the –categories option and either a BLOG_FILE or a –post-id to set the post’s categories. If the –categories option is not specified then all blog categories for all posts are listed.
- d, delete
- Delete blog post. Deletes the BLOG_FILE blogpost cache file but not the BLOG_FILE.
- Convert the AsciiDoc BLOG_FILE to HTML and print on stdout.
- i, info
- Print blog post information. Information is sourced from the client-side BLOG_FILE blogpost cache file.
- l, list
- List recent blog Posts. Information is sourced directly from WordPress server. Use the –pages option to list published Pages.
- p, post
- Post the BLOG_FILE to the blog. If this is the first time the BLOG_FILE has been posted a new post is created, otherwise the existing post is updated.
- -a, –attribute=ATTRIBUTE
- Set asciidoc(1) attribute value. Identical to asciidoc(1) –attribute option. This option may be specified more than once. Applicable to post command.
- A single asciidoc(1) option. This option may be specified more than once.
- -c, –categories=CATEGORIES
- A comma separated list of categories that will be assigned to the blog post. Prefixing CATEGORIES with a plus or minus character adds or removes the categories from an existing post. Category names are case insensitive. If an assigned category does not already exist it will be created. Applicable to categories and post commands.
- -d, –doctype=DOCTYPE
- Specifies the type of BLOG_FILE. Allowed values are html (WordPress compatible HTML file) or an AsciiDoc document type (article, book or manpage). Default document type is article. If you use the html doctype be aware that WordPress does not handle all HTML tags, this is not an issue with the AsciiDoc doctype values because AsciiDoc generates WordPress friendly HTML. Applicable to post command.
- -f, –conf-file=CONF_FILE
- Use blogpost configuration file CONF_FILE. This file is read after the (optional) implicit $HOME/.blogpost configuration file.
- Force blog file to upload even if it has not been modified since the last update command.
- Force media files to upload even if they have not been modified since the last update command.
- -h, –help
- Show this help message and exit.
- Specifies a comma separated list of one or more blog parameters that must be defined in the BLOG_FILE. If this option is not present then BLOG_FILE attribute parameter definitions are optional. See the ATTRIBUTE PARAMETERS section. Applicable to post command.
- The name of the directory containing those media files that have URLs with relative path names. Defaults to the same directory as the BLOG_FILE. The media file path is generated by joining MEDIA_DIR with the relative path name.
- -M, –no-media
- Do not upload media files. Applicable to post command.
- -n, –dry-run
- Simulate command execution without doing anything, instead report what would have been done.
- -p, –pages
- Apply COMMAND to blog Pages rather than normal blog Posts. Applicable to delete, list and post commands.
- Explicitly specify the blog post ID number. This option will only be necessary when there is no client-side BLOG_FILE cache file. Applies to delete and update commands.
- Send WordPress XML-RPC via proxy server URL.
- -t, –title=TITLE
- Set the blog post title. If this option is omitted and the blogpost-title attribute is not defined in the BLOG_FILE and the title is not in the cache file then the AsciiDoc BLOG_FILE title is used. Applicable to post command.
- -u, –unpublish
- Set blog post status to unpublished. Applicable to post command.
- -U, –publish
- Set blog post status to published. Applicable to post command.
- -v, –verbose
- Print more information about the actions being performed to stdout. Specifing this option twice to view asciidoc(1) verbose output.
- Show program’s version number and exit.
blogpost saves the values set by the following options in the BLOG_FILE blogpost cache file: –doctype, –doctype, –pages, –post-id, –publish, –unpublish and –title. This means that once a blog post has been created you won’t need to use them in subsequent commands unless you decide to change them.
The BLOG_FILE is an AsciiDoc formatted text file. blogpost(1) uses asciidoc(1) to convert the blog file to WordPress compatible HTML. If the –doctype=html then the AsciiDoc conversion is skipped.
You can insert a WordPress more tag in the blog file using the AsciiDoc block passthrugh macro:
Blogpost allows the following blog parameters to be defined inside an AsciiDoc BLOG_FILE: categories, status, title, doctype, posttype. The parameters are defined using AsciiDoc attribute entries — the parameter name, prefixed with blogpost-, forms the corresponding AsciiDoc attribute name. Examples:
:blogpost-status: published :blogpost-categories: blogpost,AsciiDoc,Blog client,WordPress
The –mandatory-parameters option is used to make selected BLOG_FILE attribute entries mandatory. Example:
Parameter precedence is (from highest to lowest):
- Command-line options.
- AsciiDoc attribute entries.
- Blogpost cache.
|Blog parameter name||AsciiDoc attribute name||Allowed values|
Comma separated list of blog category names (see –categories option).
article, book or manpage (see –doctype option).
post or page (see –pages option).
published or unpublished (see published and –unpublished options).
Blog title (see –title option).
blogpost(1) automatically creates the blogpost attribute which is useful for conditionally processing AsciiDoc document content.
You can upload media files to the WordPress server using XML-RPC but there is currently no way to programmatically list or delete media files held on the server. Blindly uploading new copies to the server every time the document is updated is an unacceptable.
To overcome this problem blogpost retains information about previously uploaded media (source paths, server URLs and media file MD5 checksums) in client-side per-document cache files. Cache files are stored in the same directory as the source BLOG_FILE but with .blogpost file name extensions. A document’s cache file is read before blogpost runs a command and is updated after running the post command. The delete and reset commands delete a document’s cache file.
blogpost uses cache files to ensure only new or modified media files are uploaded to the WordPress server. Because the caching is on a per-document basis, media files are not shared between documents.
In addition to storing media metadata, blogpost cache files also store the blog post ID, URL, title, creation and update timestamps along with the last used value of many of the blogpost command options. This is very handy, it means you don’t have to remember the blog post ID or the options you used to create the blog when you rerun the post command.
The generated HTML content is scanned for HTML anchor (a) and image (img) tags, if these tags refer to local media files then they are processed as follows:
- The BLOG_FILE cache (see METADATA CACHING) is checked to see if the media file has been previously uploaded, if it has then the media file is checked (using an MD5 checksum) to see if it has changed.
- If the media file is new or has changed then it is uploaded to the server.
- Finally the media file reference in the HTML content is replaced with the server URL of the uploaded media file.
You can disable media processing with the –no-media option.
Allowable media file types are: gif, jpg, jpeg, png, pdf, doc, odt, mp3, ogg, wav, m4a, mov, wmv, avi, mpg. Note that not all WordPress servers support all media file types, if you get an Invalid file type the file type is not supported — check with your WordPress hoster, they may have upgrade options which will allow you to upload.
There are two types of WordPress content, Posts and Pages. A Post is the WordPress term for a regular blog entry whereas a Page (sometimes called a static page) is an entry that lies outside the normal blog chronology. WordPress manages Posts and Pages separately — use the –pages option to differentiate between the two. See http://codex.wordpress.org/Pages for a detailed explanation.
Create, list, update and delete a blog post:
blogpost.py post blogging_with_asciidoc.txt blogpost.py info blogging_with_asciidoc.txt blogpost.py list blogpost.py post blogging_with_asciidoc.txt blogpost.py delete blogging_with_asciidoc.txt
Mercurial repository: http://code.google.com/p/blogpost/
Python WordPress library: http://www.blackbirdblog.it/programmazione/progetti/28
Written by Stuart Rackham, <email@example.com>
Copyright (C) 2008-2010 Stuart Rackham. Free use of this software is granted under the terms of the MIT License.