Static Publishing

Static publishing turns a VoodooPad document into a lean, mean, Markdown formatting, static blog generating machine. In addition to supporting Markdown, with static publishing you can also sprinkle Scriptlets into your templates and blog posts for dynamic output. You can even use JavaScript events for customization.

Quick Start

1. It's a good idea to experiment using Static with a new document rather than an existing document. Start by creating a new document.
2. Choose the "Setup Document for Static Publishing" option from the action menu in the Static palette. This will automatically create 3 new pages in your document (see the customizing with templates section below for further details), as well as change the default new page format in your document to Markdown.
3. Pick a folder where you will save your site. You can do this using the Change… button near the "Publish folder" label in the Static palette (this can be in your Dropbox folder if you want to publish directly to there).
4. As part of the setup process, a new page named "Hello World" is created in your document. You can delete the contents of this page and replace it with your own. Use the 'Publish "Hello World"' checkbox in the Static palette to turn on and off publishing for this page. Press the Publish button to add the page to your site. Tada! You've created a new blog entry, and generated your site!

Customizing with Templates

Here are a list of special pages created when you set up your document for static publishing. You can modify these pages to customize the output of your weblog. You can open them using the action menu in the Static palette, or from the Pages palette.

• VPWebExportPageTemplate: This page is the HTML wrapper for all the pages in your blog. If you want to overhaul the whole look and feel of your weblog, this is the page to modify.
• VPStaticPageEntryTemplate: This special page is what is used as a template for individual posts for the index page.
• VPStaticRSSEntryTemplate: This page is similar to the VPStaticPageEntryTemplate, but is used for entries in the RSS feed.

Customizing with Events

If you are handy with JavaScript, choose "Open Event Script" from the action menu of the Static palette to show the VPStaticExportScript page. You'll find a handful of functions which are called at various stages of publishing. For instance, the staticSetupConfiguration function is used to customize various settings of your blog such as its name and home URL. You can add or modify the HTML before it is written to disk, and you can see events when publishing starts and finishes.

• The staticSetupConfiguration function is called first, and is used to configure various settings for your blog. There are some default values in here which you'll probably want to change up.
• staticExportWillBegin function is called next, and can be used to setup or modify your own global variables, or maybe write out some extra pages or assets.
• staticExportItemWillBegin function is called last, and gives you an opportunity to cleanup when the export is finished.
• staticExportDidRenderHTMLForItem is called when a post has been converted to HTML, and before it is written to the index page, archive page, or rss feed. You can use this opportunity to change content on that post, or add to it. By default, the staticExportDidRenderHTMLForItem function includes an example for doing simple macro expansion. For instance, writing $vp$ in your post will print out a link to VoodooPad's website. You can delete those macros, or add to them.
• staticExportWillAppendItemToFrontPage is called before a post is added to the front page. You can use this opportunity to add custom HTML that you might want to show up between posts.
• Likewise, staticExportDidAppendItemToFrontPage is called after a post is added to the front page.
• staticExportArchivePathForItem gives you an opportunity to customize where the archive pages are kept. If you're not happy with the format that Static uses, then you can change up this function.
• staticExportArchivePathForAssetItem is similar to staticExportArchivePathForItem, but instead of returning a relative path for posts, it will return a path for an embedded asset that shows up in a page.
• The staticSupportPages function can be used to return a list of extra document page names which you want written out at publish time as well. Things like an about page, or maybe contact information.

You can also add your own functions to the VPStaticExportScript page which can be called from scriptlets. For instance, if you added the following function for wrapping image tags with an optional caption:

function imgTagWithCaption(imgURL, caption) {
    var s = '<center><img class="bb" src="' + staticSetup['siteURL'] + imgURL + '" alt="' + caption + '" /><div style="color: #666; padding-top: 2px;">' + (caption ? caption : "") + '</div></center>';

    return s;
}

You could then refer to it in your page entries:

<%= imgTagWithCaption("images/foo.png", "My Great Picture") %>

Previewing

View a preview of your current post by choosing the View ▸ HTML Preview menu item. Every time you save your document, the preview will update.

Markdown

Static publishing document pages are written in Markdown. If you aren't familiar with Markdown, you can find out more from daringfireball.net.

Images and Other Assets

If you have images embedded in your document, and you want those included with your site, you can refer to them in your page:

![Alt Text](Foo.jpeg "This is an image in the document")

Static will notice you are using the image and write it out into an assets/ directory, and then rewrite any HTML so that it points to that image in the assets directory. Note: you can change the location of the image written by modifying the staticExportArchivePathForAssetItem function in the VPStaticExportScript.

Hosting

You will have to find your own way to host your website. Since Static renders everything to static files, even the most basic service will work.

Comments

You can use a service such as Disqus or Livefyre to add comments to your blog.

Open Source

Static is part of the VPExtras project on GitHub: https://github.com/ccgus/VPExtras/tree/master/plugins-bundle/Static. If you are a developer you can download and modify the plugin, make additions, and alter parts of it as you see fit.

Sample Sites

Here are a couple of sites on the internet that use VoodooPad's Static Publishing:

• http://shapeof.com/
• http://shapeof.com/pizzalab/