Starting Points

Here are a few different ways of starting your own web application:

Using Markdown and GCSS

Using Markdown for the document contents and GCSS for styling it is a straightforward way to create content for the web. A typical project file structure may look like this:

|-- style.gcss

The style data in style.gcss is automatically applied to the Markdown document. GCSS files are translated to CSS on-the-fly, when served. Markdown documents are translated to HTML on-the-fly. is a special filename that tells Algernon that it should be served when the mywebpage directory is visited. style.gcss is also a special filename, telling Algernon that any Amber or Markdown documents in the same directory should be styled with this file.

A simple Markdown document may look like this:

# Large headline

## Smaller headline

Text goes here

* One item
* Another item

A simple GCSS style file may look like this:

  color: orange
  background-color: black
  margin: 3em
  font-family: sans-serif
  font-size: 2em

This should look familiar to people that are familiar with CSS or Sass. GCSS is a CSS preprocessor inspired by Sass and Stylus. Like Sass, GCSS also provides ways to abstract CSS. Visit the GCSS documentation for more information.

Using HTML and CSS

HTML and CSS is a classical combination. It can be written by hand or be generated by a GUI-driven application like KompoZer. When using Algernon in combination with an application that generates HTML and CSS, the advantage is that you can view the result in several browsers, instantly, when the page is saved. It can also be browsers that connect to Algernon remotely. By enabling the auto-refresh feature, a tiny JavaScript snippet is injected into the HTML pages, that refreshes the page upon file save.

A typical project file structure may look like this:

|-- index.html
|-- style.css
|-- js/framework.jss    
|-- css/framework.css

For deployment, disabling the auto-refresh feature and enabling enough cache to hold the static files, should provide good performance.

Using Pongo2, GCSS and Lua

to be written

Using Amber, GCSS and Lua

Amber is a template language that is converted to HTML on-the-fly, when served. Using a combination of Amber, GCSS and Lua is the recommended way to write Algernon web applications.

A typical project file structure may look like this:

|-- index.amber
|-- style.gcss
|-- data.lua
|-- img/logo.png
|-- js/framework.js
|-- css/framework.css

index.amber is the main page (served as HTML), style.gcss is the style (served as CSS), data.lua is a special Lua script, where all functions and variables are exposed to the Amber templates in the same directory. The rest are just examples of other file types one might want to include.

Here is an example for counting visitors that uses both Amber, GCSS and Lua:

doctype 5
    title #{title}
    h1 #{title}
      p Page views: #{counter()}

Amber is pretty close to HTML, but cleaner. doctype 5 is for declaring support for HTML 5. #{title} is replaced with the value of the title variable from data.lua below. #{counter()} calls the counter function from data.lua.

@import url(//

  color: #111
  background-color: #eee
  font-family: 'Oswald', sans-serif
  font-size: 2em
  margin: 3em

  margin-left: 0.7em

This GCSS template imports a CSS file from //, which makes it possible to use the Oswald web font on the web page. The font for the HTML body is set to 'Oswald', sans-serif, which uses the default sans-serif font as a fallback.

For this example, paragraphs (p) has a left margin the size an em (slightly larger than the height of a letter) times 0.7.

title = "Counter Example"

-- Count from 1 and up. Return the current value.
function counter()
  -- Use the "pageview" KeyValue and increase the "counter" value with 1
  return KeyValue("pageview"):inc("counter")

A global variable named title is declared and initialized with a string. A function named counter is declared. KeyValue is a function that is part of the Algernon API and can be used for communicating with the database backend. In this example, the value for the counter key is increased by one, for the "KeyValue" (hashmap) named pageview. The new value is returned.

The result of the combination of data.lua, style.gcss and ìndex.amber` is a webpage that counts the number of visits. This way of doing things provides a clear separation between data, logic, style and page structure, while avoiding the verbosity that HTML and CSS requires.

Using Lua and a directory structure

It is possible to output HTML by using only Lua. There are also functions available for outputting Markdown or Amber directly from Lua into the document that is being served.

A Lua web application may look like this:

|-- index.lua

The index.lua file may then generate and serve HTML, or serve another file. Here is one such example:

Using Lua without a directory structure

It is possible to create a web application that does not rely on a directory structure for finding which files to serve, but rather use a single Lua script that can set up handlers manually, and serve selected directories. Here is one such script (from react-tutorial):

handle("/comments.json", function()

  -- Set the headers
  setheader("Cache-Control", "no-cache")

  -- Use a JSON file for the comments
  comments = JFile("comments.json")

  -- Handle requests
  if method() == "POST" then
    -- Add the form data table to the JSON document
    -- Return the contents of the JSON file


servedir("/", "public")

Web Application Archives

Algernon supports running Algernon Web Application Archives.

If the project directory is zipped down to a .zip file and renamed to end with .alg, you have an Algernon Web Application Archive. This is similar to how WAR files work in Java. WAR files are also zipped down web applications that contains all needed resources for deployment.

Algernon can serve Web Application Archives. Just provide the full .alg filename on the command line instead of a directory name, like this:

algernon myapplication.alg