Installation

First install nefelibata using a virtual environment:

$ pip install nefelibata

This will add a program called nb to your path.

If you’re impatient, you can run:

$ nb init blog
$ cd blog
$ nb build

And looks at the files inside the build/ directory.

Creating the site directory

Once you have installed nefelibata you should initialize a directory that will hold your content:

$ nb init blog
$ ls blog
nefelibata.yaml  nefelibata.yaml.full  posts/  templates/

Here, the file nefelibata.yaml stores the configuration for your site. The posts/ directory will contain your posts, and should already have a directory called first/ with an initial post. The templates/ directory has the templates for generating your blog and its Atom feed, as well as a Gemini capsule. Multiple themes are supported for the HTML builder, but there’s currently only one called “minimal”.

Configuring your site

The file nefelibata.yaml.full has comments describing all the sections.

Creating a new post

Your skeleton blog already has a post called first/. You can edit that post, or create a new one with the command:

$ nb new "Hello, World!"

(Note that you always need to run the nb command from inside your site directory.)

This will create a new directory called hello_world/, with the following structure:

posts/hello_world/
posts/hello_world/index.mkd

If you have the EDITOR environment set, nefelibata will automatically open your editor to edit index.mkd. You can place any custom CSS, Javascript or images in the corresponding directories, or any other extra files in the hello_world/ directory.

You’ll notice that the index.mkd file has headers and a body. The file itself is actually stored as an email, using the RFC 5322 format. The most important headers are:

• subject: this is the title of your post.

• summary: this is a one-line summary of your post.

• keywords: a comma-separated list of keywords/tags/tags.

Additionally, once the post is published a date header will be added.

Building the site

To build your site, simply run:

$ nb build

This will convert the Markdown files to HTML and/or Gemtext and build the site, with pages for tags and categories as well. Later, once posts have been announced to social networks, this command will also collect replies and store them locally as YAML files.

Publishing the site

Finally, you can publish your site with the command:

$ nb publish

This will upload the site using any configured publishers (like S3), and announce new posts to social networks.