Flat-file Website and Blog Tutorial

This tutorial will walk you through creating a simple web site and blog using plain markdown files and jinja templates ( there will be no database, no web UI).

1. Ensure you have Java 1.8u40 or greater on the class path:

>java -version

If not, download and install Java from Oracle or from the OpenJDK.

If you have multiple java versions on your machine, you may have to symlink the Java 1.8 binary to /usr/bin/java

2. Create a new directory for your site:

>mkdir mysite

3. Download or install the stallion binary into a folder called “bin” and give the file executable permissions:

> mkdir mysite
>cd mysite
>mkdir bin
>curl -L -o bin/stallion https://stallion.io/downloads/stallion-core/latest/stallion
>chmod 700 bin/stallion

4. Run the stallion setup wizard:

bin/stallion new

Choose option #2 – “Text File Web Site”

Complete the wizard as desired.

5. Run the server. Go to http://localhost:8090 in your browser, and you should see your site!

6. Customize your template

Templating is based on the Jinja templating language, which was ported to Java via the jinjava project.

The wizard will generate the following templates for you:

• templates/base.jinja - the base template that the others will inherit from
• templates/page.jinja - for normal pages, like the “about” page
• templates/listing.jinja - for the blog pages that list recent posts, or posts by category
• templates/post.jinja - for an invidual blog post
• templates/contact-us.jinja - a page with a contact form at the bottom

Start the Stallion server, then open up the page http://localhost:8090/about with your browser. Then open up templates/page.jinja in a text editor. Change the token <h2 class="post-title">{ page.title }}</h2 to <h2 class="post-title>Page title: <em>{ page.title }}</em></h2>. Reload the “/about” page, and you should see the text become italic and be prefixed with “Page title:”

Now open templates/base.jinja. Find the footer area and add <div>&copy; { now.year }} { site.name }}</div>. Reload the site in your web browser. All the pages in your site should now show “© 2016 Your Site Name” at the bottom.

In templates/base.jinja go to the sidebar area right below the </nav> tag. Add the following snippet:

<h3>Recent posts</h3>
<ul>
     &#123;% for blog_post in posts.filter('published', true).sort('publishDate', 'desc').pager(1, 3).items %}
     <li><a style="color:white;" href="&#123;&#123; blog_post.permalink }}">&#123;&#123; blog_post.title }}</a></li>
     &#123;% endfor %}
</ul>

You should now see a list of up to three of your most recent blog posts on your sidebar.

See the templating reference section for all you can do with templates.

7. Create a new page

Pages or blog posts are text files with the main content written in markdown. You can read the basic documenation for markdown here. If you want more details on the markdown implementation, under the hood we use the pegdown library with tables, smarty quotes, and footnotes supported.

To manually create a new page, create a new .txt file in the folder “pages.” To manually create a new blog post, create a new text file in the folder “posts.”

You can also use the following command as a helper command to create a new draft blog post: bin/stallion new-page. The default post text will be instructions on how to view the post and make it live.

The format for a post or page text file is as follows:

• The first line of the text file should be the title
• The second line should be a line of equals signs
• Then include metadata, which is the attribute name, followed by a colon, followed by the attribute value.
• Then a blank line
• Then the markdown content

Simplest possible page/post

About the Knights
========================================
draft: false

The Knights of the Roundtable are one of the world's premier fighting teams.

A page/post with all the options

About the Knights
========================================
draft: false
publishDate: 2016-04
slug: /about-the-knights
metaDescription: About the world's premier fighting squad.
template: alternative-template.jinja
tags: fighting, jousting
author: Merlin
previewKey: asecret123
oldUrls: /about;/the-knights
customKey: someValue
anotherKey: someThing

The Knights of the Roundtable are one of the world's premier fighting teams.

Here is an explanation of each option:

• draft either true or false. If true, the page will not be visible.
• publishDate the date the page goes live. If the current time is before the publishDate, the page will not be visible.
• previewKey allows you to view a draft or future-dated page. Go to the page URL, and add a query string ?stPreview=(previewkey). You can make the preview key whatever you want.
• slug the path component of the URL to this page. If your domain is http://mysite.com and the slug is /about-us the page will be viewable at http://mysite.com/about-us. If slug is empty, it will be generated from the file name.
• oldUrls a semicolon separated list of previous slugs. If you change the slug, you should add the old slug to this list, so that people with the old link will get a 301 redirect to the new page.
• author the author of the page
• template by default, pages use the page.jinja template. But a page can render with an alternative template if you wish.
• metaDescription this will be used for the meta description html tag in the page head.
• someKeyIMadeUp you can make any additional metadata you want, and then display the information in the template using { page.someKeyIMadeUp }}

8. Additional Command-line Options

When running Stallion, there are some options you can configure at the command line:

• Run bin/stallion without options to see a list of commands.
• Run bin/stallion <command> help to see available options for that command. For instance bin/stallion-flat serve help will show you options for the serve command, such as running on a custom port.

9. Further reading

• Templating reference
• Deploying your site to a server