WordPreSt adds a reStructuredText input mode to the WordPress post/page
editor. Once installed, reStructuredText may be input directly into the
editor and converted to HTML with the click of a mouse. The reSt source
is saved with each post/page for future edits. The rendered HTML output
is stored as the actual post content to allow modification after
rendering if desired. Plugin settings control the features of the reSt
convertor and include automatic table of contents links, post title
generation from reSt, header level customization, and others. A “View
document source” link is also (optionally) available for each post.

WordPreSt requires no template modifications and every effort has been
made to ensure a truly seamless integration into WordPress.

Unzip the plugin package into the /wp-content/plugins/ directory. The
zip file will automatically extract into a wordprest subdirectory.

Activate the plugin through the “Plugins” admin menu in WordPress.

Configure the WordPreSt settings (in the “Settings” admin menu) and
provide an absolute path to the Docutils rst2html.py script.
WordPreSt does its best to locate the script automatically, but
often requires manual configuration.

“reStructuredText is an easy-to-read, what-you-see-is-what-you-get
plaintext markup syntax and parser system. It is useful for in-line
program documentation (such as Python docstrings), for quickly
creating simple web pages, and for standalone documents. reStructuredText
is designed for extensibility for specific application domains. The
reStructuredText parser is a component of Docutils. reStructuredText
is a revision and reinterpretation of the StructuredText and Setext
lightweight markup systems.”

Markdown is a great text format (and conversion tool) and I’m a huge
Gruber fan and all, but it’s really quite limited in the grand scheme
of document management. Markdown is not multi-document aware, meaning it
only knows about the one file it is parsing at a time, and lacks the
ability to link between internal references across files. A few of its
features are add-ons requiring plugins, which are not available in every
implementation of Markdown either. It’s a generally less-configurable
format as well, where reSt provides extensive optional settings for
various elements.

Perhaps most importantly though, reStructuredText has many output convertors
allowing you to write once, parse a thousand times, into almost any conceivable
format out there. If the output format you desire does not exist, it’s
(fairly) trivial to create your own. Markdown is strictly an (X)HTML
convertor which severely limits your options if you want to publish your
documents across different media.

If you have shell access to your hosting server, you may be able to simply run
easy_install docutils. If easy_install is not available, you will need
to download and install Docutils according to the instructions on the
Docutils home page.

Wow, I’m flattered! I’m also very broke, so that works out perfectly! Of course
I’ll accept donations, and the guys over at GitHub have been nice enough to
hook me up with a Pledgie account to make it incredibly easy for you to
show your gratitude for my hard work. Any amount would be greatly appreciated.

Without HTML auto-update enabled for a post, there is a very slim chance
that changes to the reSt source will be lost if you navigate away from
the editor. One solution would be to hook into WordPress’s own auto-save
hook, which saves a draft version of your post. There will be some crazy
post ID handling that will need to be done, but it appears that meta data
can be saved to drafts as well, so it’s feasible that we could save the
reSt with each auto-saved draft.

A “load reSt from file” button would be super useful for folks like me who
prefer composing posts in an offline editor. The file’s contents would have
to be sent to the server and then passed back to the reSt editor and
(optionally) rendered into the HTML editor.

HTML conversion options should be configurable on a per-post basis,
overriding the global options. The post specific options could be stored
in an additional meta field.

The reSt toolbar could use a few more tools to make it easier to insert
some of the more configurable reSt directives, like images. Directives
that require options or that have multiple presentation modes (links for
example) will probably be handled through a pop up / modal box interface.

WordPress has a few other places where posts can be inserted, like
QuickPress, that should be optionally reStructuredText enabled.

Pygments can be used for syntax highlighting if available, but the setup
might be a little too complicated for beginners. Even though the irony
there is really funny, it would be a good idea to add a couple of settings
to handle which Pygments stylesheet to use, possibly on a per-post basis
as well. A “custom” option would allow the user to provide his own Pygments
CSS. Of course, WordPreSt should automatically determine whether or not
to include the Pygments styles when displaying a post/page.

Getting the absolute path of rst2html.py is definitely the main
stumbling block for new installs. The settings screen should have a button
to determine (via AJAX) whether or not the current setting is correct.
WordPreSt automatically tries to locate the script upon activation, but
the auto-locate feature could be useful from within the settings page
as well. Docutils could probably be detected more accurately through a
Python script, and if not found, an option to install through the settings
page would be very helpful (if possible). Eventually it may even be possible
to package a standalone Docutils package, requiring only the Python
interpretor to work.

Sometimes you just have to look up the syntax for a more rarely used reSt
directive. A toolbar link to the Quick reStructuredText reference page
would come in handy from time to time.

I just did a fresh install of wordpress 3.0.3 and wordprest 1.0.
The wordprest tab appears in the edit page but no html is generated from reSt. I tested my /usr/bin/rst2html (no .py under ubuntu) this script works fine when run manually. I dono where to look at to debug this … the reSt code is actually saved in the wordpress database in the wb_postmeta table but its like there’s no link between the reSt tab and the html tab in edit mode …

any hint ?

ps : I installed wordpress just because I wanted to use use reSt 🙂

xdissent

Yeah, it’s not compatible with WordPress 3.0 yet. I’ve got a modified version running on my site that works, but it needs some cleanup before release for sure. I’ve been very busy, plus the official WordPress plugin release process is really annoying, so I haven’t gotten around to tidying it up. I’ll try to devote some time this weekend to rolling out a new version. Sorry for the frustration!

Fred

Glad to ear that, I would have been much more disapointed if it was supposed to work, since it’s not but its already partially working, I’m quite confident. This week end would be perfect but I suppose it’s not exactly the most favorable week end of the year to get some coding done … I’d still be very grateful towards you if you released it next week :p My old blog can wait its refresh a little …

What WP 3.0 compatibility takes? Currently I am running HTML thro rst2html.py by hand and then copy-pasting into WP source code view.

http://twitter.com/IanKRolfe Ian Rolfe

Hi there, I’d like to see this working on WP 3.4. Are you likely to be doing any work on this in the forseeable future? I tried it and the rEst tab doesn’t appear in the editor at all. I guess they must have changed the hooks in the editor.