Journey plugins are Lua scripts that will be executed when a custom helper in your theme is called.

Consider the following line in a .hbs file within your theme:

<h1>{{customheader}}</h1>

The customheader helper is not part of the standard repertoire of Journey. The helper will output an empty string, which means the above line will be rendered as:

<h1></h1>

However, once you write a plugin in Lua, put it in your /path/to/journey/content/plugins directory, and register it as the customheader helper, the above line could look like this:

<h1>The string your Lua script returns from its customheader function</h1>

A plugin only needs to implement two functions to be fully operational:

register()

which needs to return a table of strings and

helpername()

which needs to return a string. helpername needs to be replaced with the name of the helper you'd like to implement. customheader in the above case.

Let's write a plugin that implements the customheader helper.

Create a new directory named headerplugin in /path/to/journey/content/plugins.

Create a new file in /path/to/journey/content/plugins/headerplugin and name it customheader.lua.

Paste in the following code

-- This function registers our plugin with Journey and tells it which helpers should be handled by the plugin.
function register()
	return {"customheader"}
end
-- This function gets called every time Journey needs the customheader helper.
function customheader()
	return "This is great!"
end

and save the file.

Here's what you just did:

• You created the register function which needs to return a table with the names of the helpers you want this Lua script to implement.
• Then you created the customheader function which gets called every time an .hbs template with the {{customheader}} helper is rendered. That function needs to return a string. That string will replace the helper in the source of the rendered html page.

Now restart Journey to load the plugin. Assuming that you have a theme with the following line in a .hbs file:

<h1>{{customheader}}</h1>

that line will now be rendered as:

<h1>This is great!</h1>

To write complex plugins you probably want to import modules into your Lua script. It's a good idea to keep those modules in a sub folder of your plugin directory to make the plugin portable.

Let's say you have a module in a sub folder relative to your .lua file: mymodule/mymodule.lua with the following content:

local mymodule = {}

function mymodule.foo()
    return "foo!"
end

return mymodule

To import Lua files from a sub folder, you need to add that folder to the package.path. To get the current directory of a Lua script at runtime, Journey plugins can use the getCurrentDir() function:

-- Adding the directory of our module to the path.
package.path = getCurrentDir() .. "/mymodule/?.lua;" .. package.path
-- Loading our module.
MM = require "mymodule"
-- This function registers our plugin with Journey and tells it which helpers should be handled by the plugin.
function register()
	return {"foo", "bar"}
end
-- This function implements the foo helper and uses our module.
function foo()
	return MM.foo()
end
-- This function implements the bar helper.
function bar()
	return "bar!"
end

To get information out of Journey, you can use the following functions in your plugin:

• getCurrentDir(): Returns the directory of the current .lua file as a string.
• print(argument): Prints its argument to the Journey log.
• getNumberOfPosts(): Returns the number of posts attached to the currently rendering page as an integer.
• getPost(index): Returns the post at the given index. (index must be an integer equal to or smaller than the one returned by getNumberOfPosts(). Note: The index starts with 1, as that is the Lua way.)
• getAuthorForPost(index): Returns the author of the post at the given index. (index must be an integer equal to or smaller than the one returned by getNumberOfPosts(). Note: The index starts with 1, as that is the Lua way.)
• getTagsForPost(index): Returns the tags of the post at the given index. (index must be an integer equal to or smaller than the one returned by getNumberOfPosts(). Note: The index starts with 1, as that is the Lua way.)
• getBlog(): Returns the blog data.
• getArguments(): Returns the arguments attached to the helper.

table:

{ ["id"] = number, -- always an integer
["uuid"] = string,
["title"] = string,
["slug"] = string,
["markdown"] = string,
["html"] = string,
["isfeatured"] = boolean,
["ispage"] = boolean,
["ispublished"] = boolean,
["date"] = number, -- date of publication as unix timestamp, always an integer
["image"] = string }

table:

{ ["id"] = number, -- always an integer
["name"] = string,
["slug"] = string,
["email"] = string,
["image"] = string,
["cover"] = string,
["bio"] = string,
["website"] = string,
["location"] = string,
["role"] = number, -- 1 = Administrator, 2 = Editor, 3 = Author, 4 = Owner, always an integer }

table of tables:

{ { ["id"] = number, -- always an integer
["name"] = string,
["slug"] = string }, ... }

table:

{ ["url"] = string,
["title"] = string,
["description"] = string,
["logo"] = string,
["cover"] = string,
["assetpath"] = string,
["postcount"] = number, -- always an integer
["postsperpage"] = number, -- always an integer
["activetheme"] = string }

table:

{ string = string, -- e.g. if the helper was {{test absolute="true"}}, this would be "absolute" = "true" (quotation marks around the second part are ignored). {{test argument}} on the other hand would be "argument" = "".
string = string,
string = string, ... }

• If you'd like to use your custom helper as an if argument in a theme, your Lua function needs to return an empty string ("") for false, any other string (e.g. "t") for true.
• Journey uses GopherLua to execute plugins. GopherLua implements its own Lua VM, so please refer to the GopherLua Read Me for differences to the standard Lua VM.