Flying Meat
FS • VoodooPad: Web Export
Make sure to check out the new wiki located at http://flyingmeat.com/wikka/. This one will eventually be retired.

Web Export

Web Export is a new feature in VoodooPad 2.5. It allows you to export your document as HTML files, with options for marking up the pages as Textile, Markdown, or just treating it as plain text.

In addition, you are given the opportunity to specify "Web export plugins" to apply special formatting with the export.

Here's a quick rundown of the various options available in the Web Export window.

Export format: This is the format that you would like the text in your VoodooPad pages to be written out as.

  • RTFD to HTML is probably going to be the most used option- it tries to match exactly what your pages look like on output.
  • No Markup exports your pages as-is. No attempt is used to try and interpret any formatting in the pages.
  • Plain Text exports the pages without any special formatting, or images, but does format for line breaks.
  • Interpret as Markdown exports your pages using a popular text to HTML formating script. For more information on Markdown please visit http://daringfireball.net/projects/markdown/
  • Interpret as Textile exports your pages using another popular text o HTML formatting script. For more information on Textile, please visit http://www.textism.com/tools/textile/

Output directory: This is the folder where the html files and images are written to.

Web export plugin: You may select a specific plugin to be used to provided extra workflow options, or template for exporting. These plugins are located in your "~/Library/Application Support/VoodooPad/Web Export PlugIns" folder.

Preflight script: This is a unix script (or application) that you may choose to be run before the actual export is taken place. This is useful if you want to create resources such as folders or supporting files to manage your workflow.

Postflight script: This follows the same idea as the preflight script, but is run after the export has taken place. For example, you could use this to automate the uploading of your html files and images to a server.

Preset: If you spend a little bit of time and energy into setting up what scripts need to be run, and what folders you want everything to be exported to, then you might want to save those setting for use at a later time. That's what this setting is for. Use the + button to add or modify a preset, use the – button to remove a preset.

Reset button: This resets all the export options to their default state.

Close button: This closes the Web Export window.

Export: This kicks off the export, and progress is updated via a label in the lower left corner of the window.


Special Pages:

The Web Export feature allows you to create special pages within your VoodooPad document, which supply additional information, scripts, or templates to be used alongside whatever plugin is used for export.

WebExportPreflightScript: This page will be executed like a normal shell script, and is called at the beginning of the export.

WebExportPostflightScript: This page will be executed like a normal shell script, and is called at the end of the export.

WebExportProperties: this page will be written to meta.xml, so you can place config information in here if it is needed.

WebExportPageTemplate: this page will override the template given in the selected plugin.

Including other pages / macro substitution:

<!--#include page="header" -->

That'll include the page named "header" in your document.

Special Variables.

$page$
This will be replaced with the contents of the page.
$alias$
This will include the first alias you have for a page.
$alias[0]$
This will also include the first alias you have for a page.
$alias[1]$
This will include the second alias you have for a page.
$alias[2]$
The third alias for a page...
$alias[x]$
Etc... (you get the point).
$displayName$
This will insert the page name. ($title$ works as well, but is deprecated).
$categories$
This will list the categories the page is in.
$documentName$
This will include the document name, with the .vpdoc extension
$documentTitle$
This will include the document name, excluding the .vpdoc extension
$year$,  $modifiedYear$, $shortDate$, $longDate$, $time$, $shortTime$,
$timeDate$, $modifiedShortDate$, $modifiedLongDate$, $modifiedTime$,
$modifiedShortTime$, $modifiedTimeDate$
These will list the dates in various formats, for both the create date, and last modified dates.

AppleScript

Web Export can be controlled via AppleScript. Below are a couple of examples doing this.

Automator

There are a couple of Automator actions for invoking Web Export in VoodooPad. Launch Automator and you will see them listed if you have installed VoodooPad.


Information for advanced users or plugin developers.

Export / Script Execution Order

The following steps are what takes place when you press the "Export" button in the Web Export window. The hope is that this information will be useful for anyone wanting to make a plugin, or for advanced uses.

1. Preflight script specified in the export window is run.
2. WebExportPreflightScript page, if available, is run.
3. Preflight script(s) specified in the "PreflightScripts" array of the plugin's Info.plist file are run.
4. Pages are exported to output directory.
5. meta.xml is written out to the output directory if the boolean key "WriteMetaInfo" is set to yes in the plugin's Info.plist
6. Category files are written out.
7. Postflight script(s) specified in the "PostflightScripts" array of the plugin's Info.plist file are run.
8. WebExportPostflightScript page, if available, is run.
9. Postflight script specified in the export window is run.

Shell Script Environment Variables:

These are environment variables that VoodooPad exports, for use in pre and postflight scripts.

VPWebExportOutputDirectory: The directory the files are written to.

VPWebExportVoodooPadDocument: The document that is being exported.

VPPluginPath: The path to the web export plugin that is being used.

Plugin Info.plist keys

These are the various keys you should have defined in the plugins Info.plist file. This is really only of any use if you are wanting to write a Web Export plugin.

NSExcludedElementsDocumentAttribute – An array with items to exclude for the apple rtf->html converter. Values are given on this page: http://developer.apple.com/releasenotes/Cocoa/AppKit.html (search for NSExcludedElementsDocumentAttribute) 10.4 only.

DisplayName – what shows up in the pulldown list for the plugin.

PrincipalTemplate – the path to the html template to use when exporting.

PreviewImage – the path to a png image, which will be used for a preview in the WebExport window.

PreflightScripts – an array of paths, pointing to scripts to be run before the export takes place.

PostflightScripts – an array of paths, pointing to scripts to be run after the export takes place.