JOPA Internals

Internals

The idea of Jopa is extendability through simplicity. Everything in Jopa's world is a bash script, and almost everything is controlled through the use of environment variables.

This is done for you to be in control of what is going on and be able to apply any logic at any step of site generation. You can do anything bash scripts can, and modify your content as you wish - no need for unnecessary plugins, libs, yadda-yadda-yadda. Just you and your shell - grep, cat and cut, anything.

But how does Jopa actually work?

Pages

First, it goes through the list of pages, specified in $pages variable, and, to render them, does source them as a bash script. This leads the environment for further processing. The sourcing is done on a per-page scope, to avoid interference.

By default, $pages equals to pages/*.jsh wildcard. The extension is short for "Jopa shell", to differ your posts from regular shell scripts (remember, everything is a script).

Pages can have any arbitrary logic, but most of the time they just define metadata such as title, description and, obviously, the actual page content. To make text easier to write, Jopa defines multiline helper with an optional "filter" that can be used to transform content from one format to another (we are generating a website, after all, so we probably want the content to be in HTML). Here is an example of a page:

title="My wonderful page"

multiline markdown content << 'JOPA'

# Hello World!

Just my blog post, how are you?

JOPA

Here, we define two env variables: $title and $content (names are arbitrary), but $content is defined with multiline helper that passes text through markdown utility (which you should install independently) to generate HTML content. Notice << 'JOPA' on the line with multiline call and JOPA at the very end. These are so-called "heredocs" and in bash to define multiline strings. You can read about them somewhere else, just note, that most of the time you want the first delimiting identifier to be in single quotes, otherwise your text is subject of command evaluation which is a dangerous thing... Imagine the following page:

multiline content << JOPA

Don't do $(rm -rf ~/) in your scripts!

JOPA

You probably don't want this to be executed... But sometimes you do want the evaluation in these strings (for example, for in-line variable expansion), okay, it's up to you. Just be warned.

Another note is that you can use any thing as your delimiter, even Emojis. Isn't this fun?

Layouts

Next, after a page is sourced env variables are (re)defined, but if $layout is not defined yet while $layout_file is, the latter is also sourced. The script in this file must define $layout (and can do this conditionally). Again, you can have any logic, for example, have defaults for $title:

website_title="My Website"

# prepend website title to any page's title
if [[ "$title" ]]; then
  head_title="$title | $website_title"
else
  head_title="$website_title"
fi

# define mandatory layout variable
multiline layout << 'JOPA'

<!doctype html>
<meta charset=utf-8>
<title>${head_title}</title>
<h1>${title}</h1>
${content}

JOPA

Then, the string in $layout is used as a template to render the resulting file using envsubst utility, which basically replaces all variables in the template with their actual values. Logic-less templates you say? Kind of.

Well, is that simple.

Indexes

But here is one more thing. What about the index page, table of contents, Atom/RSS feeds and all alike? We need to display links to our wonderful pages somehow, in most cases on the main page - the website's index. For this purpose, there are indexes and the each helper.

Indexes are regular pages, except that they are processed separately from other pages and, obviously, are not "indexed", i. e. will not be present in the resulting list of pages. You must specify indexes in space-separated $indexes env variable, for example:

# add Table Of Contents page to the list of indexes
indexes="$indexes $from/toc.jsh"

By default, only $from/index.jsh is in this list.

Below is an example of such a page:

multiline indexer_main << 'JOPA'
  <li>
    <a href="/${target}">${title}</a>
  </li>
JOPA
index_main="$(each "$pages" render "$indexer_main")"

multiline content << JOPA
  My posts:
  <ol>${index_main}</ol>
JOPA

Here, we have regular page content defined, but it uses $index_main variable, which is defined as the result of each function call on a set of $pages, and each page is then fed into render "$indexer_main" function, i. e. rendered with the defined template. You also see that $target variable is used - this is a file name for a page being processed and you can use it to refer to the page.

Of course, instead of calling render you can call your own function which can do filtering, skip some pages you don't want to be displayed, and only then call render from.

Hope this sheds some light on how this pretty simple thing is working for you to be able to move to the next (but optional!) step - extending Jopa.