How to create your website using verless

Since I planned to create a new personal website for myself and didn't want to stick with PHP again, I created a simple and lightweight Static Site Generator called verless. In this article, I'll demonstrate how to rapidly create static websites using verless.

Of course, you need to install verless first or run it with Docker.

Scaffolding a new project

First of all, we're going to initialize a new project - a Coffee Blog - to get started quickly. verless makes this fairly easy:

$ verless create project coffee-blog

This creates a small, customizable standard project. Basically, a project is nothing else than a directory containing some components required for verless. In this case, our directory is called coffee-blog.

Developing and customizing a project

You don't need a third-party webserver like Apache for local development, because verless already comes with a built-in webserver.

One of the disadvantages of Static Site Generators is that you have to re-build your entire website each time you change a single file in your project. Fortunately, verless is able to watch your project for changes when serving the website, and it will automatically re-build the project each time you change a file.

This will serve our project on localhost:8080:

$ verless serve -w coffee-blog

The -w or --watch flag will verless make watch the project for changes.

Project configuration

verless created a top-level configuration file called verless.yml for you. Here you can set metadata, define your navigation items, enable plugins and set your theme.

Let's change into the coffee-blog directory and put some stuff into verless.yml:

version: 1
site:
  meta:
    title: My Coffee Blog
    subtitle: About Espresso & Cappuccino
    description: I'm Clara and write alot about coffee.
    author: Clara Crema
    base: http://localhost
  nav:
    items:
      - label: Home
        target: http://localhost
plugins:
  - atom
theme: default
build:
  overwrite: true

Creating content

Time to create our first article! All content is stored as Markdown files inside the content directory of our project. If you haven't quit serve yet, press Ctrl + C to stop it. Run the following command inside the project directory to create a new file:

$ verless create file making-barista-quality-espresso.md

This creates a new Markdown file as content/making-barista-quality-espresso.md. The filename defines the URL of the page, and it is relative to the content directory - so this one will be available at localhost:8080/making-barista-quality-espresso. It is that simple.

Editing content

The advantage of verless create file is that it initializes a Markdown file with a default Front Matter. The Front Matter is a small YAML section inside the Markdown where you can define metadata:

---
Title:
Description:
Date: 2020-10-12
---

Let's write some content about Barista-Quality Espresso:

---
Title: Making Barista-Quality Espresso
Date: 2020-08-14
Description: This is a guide for making italian Espresso.
Tags:
    - Espresso
    - Coffee
Img: /static/espresso.jpg
Credit: Burst on Pexels
---

Do you enjoy a high-quality italian Espresso as much as I do? Quite
frankly, making Espresso at this level isn't easy - but with the right
tools, patience and practice, you'll be able to make delicious coffee
at home.

...

I've also copied a photo into the static top-level directory of our project, using it as an image in the Img field. It will be available under localhost:8080/static/espresso.jpg.

Themes

Maybe you've already seen that our project contains a themes directory where verless stores all themes. After creating a new project, it already contains the default theme.

For our Coffee Blog, we could merely customize the default theme, but we're going to create an own theme called light for this tutorial. Just issue this command inside our project directory:

$ verless create theme light

This creates a new light directory inside themes, containing all components that a theme requires: A configuration called theme.yml and the templates and assets directories.

With these basics, we're good to start templating and styling.

Templating

Each theme requires at least two templates:

• A template for rendering Markdown content: page.html
• A template for rendering overview pages for each directory: list-page.html

Let's edit templates/page.html inside our new theme and write something like this:

<!DOCTYPE html>
<html>
    <head>
        <title>{{.Page.Title}}</title>
        <link rel="stylesheet" href="/assets/style.css" />
    </head>
    <body>

        <h1>{{.Page.Title}}</h1>

        <img src="{{.Page.Img}}" />

        <p>{{.Page.Description}}</p>
        <small>
            Posted on {{.Page.Date.Format "Jan 2 2006"}}.
            Photo: {{.Page.Credit}}
        </small>
        <p>{{.Page.Content}}</p>

    </body>
</html>

As you see, verless provides a stable and type-safe template API: In page.html, there are objects like .Page and .Meta available, and they possess fields like .Title. This makes verless themes re-usable across projects.

To get a complete list of available fields in the particular templates, check out the template reference.

Next, we'll edit templates/list-page.html. For each directory inside content - for example, a blog directory -, verless generates a overview page containing all pages in that directory. These are so-called list pages.

In our list-page.html, we want to provide a simple list of page titles with hyperlinks the individual pages:

<!DOCTYPE html>
<html>
    <head>
        <title>{{.Page.Title}}</title>
        <link rel="stylesheet" href="/assets/style.css" />
    </head>
    <body>

        {{range $page := .Pages}}
            <div>
                <h3>{{$page.Title}}</h3>
                <small>
                    Posted on {{$page.Date.Format "Jan 2 2006"}}
                </small>
                <p>{{$page.Description}}</p>
                <p><a href="{{$page.Href}}">read post</a></p>
            </div>
        {{end}}

    </body>
</html>

Don't forget to set the theme! We need to enable the theme in verless.yml by replacing theme: default with our new theme:

theme: light

Serving or building the website

If you're inside the project directory, serve the website using the following command and check if everything works as expected:

$ verless serve -w .

The generated website should look similar to this:

To get a deployable website that you can upload to your web hosting or cloud provider, you can build the project using verless build:

$ verless build .

The built website will go into the target directory of our project and you're good to upload it.

Plugins

verless supports some plugins that are desirable for many, but not all project out there - so verless wants you to explicitly active the plugins you need. Maybe you noticed that small plugins section in verless.yml:

plugins:
  - atom

This small plugin automatically generates a RSS feed for you. When serving our project, check it out here: localhost:8080/atom.xml
You may also check out the plugin reference.

You're now good to create your own styles, configure your pre-build hooks for generating CSS and create your very own website!