Logya Documentation

Logya is a command line tool to generate static Web sites, designed to be easy to use and flexible.

You may ask why another static site generator, when there are so many others? Valid question, simple answer: all the others are doing it wrong. No, seriously, tools like Jekyll, Hyde or mynt are very powerful and probably provide more features out of the box than Logya ever will.

Two key differences comparing Logya with the above tools are:

Features

Requirements

Installation

Logya is an open source Python application, check out the source code on Github. To install Logya with pip run:

sudo pip install logya

If you cloned the repository, you can install Logya from the project's root directory with the following command:

sudo python setup.py install

Getting Started

Create a starter site:

logya create mysite

This command will create a new sub directory in your current working directory called mysite, that includes the resources for a logya starter site.

Change to the starter site directory:

cd mysite

Generate files to deploy:

logya generate

This command generates HTML files from the documents found in the content directory, indexes for Web site directories, and copies static resources to the newly created deploy directory.

Serve site from deploy directory:

logya serve

Run this command in the root directory of your mysite project and it will serve the static files from the deploy directory. When you edit files in your projects source directory and reload them in the browser they will be updated, so this can be used for live editing your site and see changes immediately.

Get help on logya command:

logya -h

Show the help output of the logya command with information on sub commands and options, for help on a sub command call it with the -h option, e.g. logya create -h.

Directory Layout

The following folders and files are recognized when generating a Web site with Logya.

content - required

The content directory contains all of the site's documents. Documents can be located in sub directories and must end in the file extensions .html, .md or .markdown.

templates - required

The templates directory contains all of the site's Jinja2 templates.

site.cfg - required

This file contains the site configuration.

static - optional

This static directory contains all static resources like JavaScript, CSS, image, and server configuration files.

bin - optional

This directory contains scripts that are called during generation and serving. Scripts can for example generate pages from content that is fetched from a database or from the web.

Python scripts can access the logya object via the logya global variable.

Document Structure

Documents are dived into header and body parts.

Document Header

The header is in YAML format. It starts and ends with 3 dashes. In the header you must specify url and title other attributes such as description, scripts and style sheets are optional. All attributes can be accessed in templates.

Attribute values can range from simple strings to nested data structures that are automatically available in templates.

The only exception with a pre-defined value format is the created attribute. If you set it, it must adhere to the format YYYY-MM-DDTHH:MM:SS without surrounding quotes as shown in the example. If you don't set the creation time in a document header, the file modification time will be used for sorting documents in indexes.

---
url: /
title: Logya Documentation
template: post.html
created: 2012-03-18 13:59:16
previewimage: /path/to/previewimage.png
---

Tags

You can tag documents using the tags attribute, which is assigned a list of comma separated tags, for example:

tags: [example tag 1, example tag 2, example tag 3]

If you specify document tags the tags sub-directory will be created containing indexes with links to the corresponding documents, in this case don't create document URLs that start with /tags/.

To create a list of links to these index pages from a post you can access the tags_links template variable, which is populated automatically and mustn't be specified manually in the document header:

{% if tag_links %}
  {% for url, anchor in tag_links %}
    <span class="tag"><a href="{{url|e}}">{{anchor|e}}</a></span>
  {% endfor %}
{% endif %}

Document Body

The remaining part of the document is treated as the content that goes in the body of the created HTML page. This content can either be written in markdown or marked up with any HTML tag that can be in the body of an HTML document. The body format is indicated by the file name extension.

HTML

<h1>This is a heading</h1>
<p>This is a paragraph</p>

Markdown

# This is a heading

This is a paragraph

Configuration Settings

Below you find configuration sections and settings:

[site] section

All settings in this section will be available to all templates, so names for configuration variables mustn't be used as names in document headers.

base_url
base_url is the only required setting needed to create the canonical variable and to generate RSS feeds.

[templates] section

index
The template to use for generated index.html files. If not set, indexes won't be created.
doc
The template to use for generated content documents. If not set, the document won't be created.

[extensions] section

Currently this section is not supported. I consider using it for turning extensions on and off.

Development Tips

The following tips are intended for people developing logya application code.

Create a command that points to the development source:

ln -s $HOME/code/logya/logya/main.py $HOME/bin/logyadev

This creates a symbolic link in your home bin directory to access logya commands from your development source, assuming it resides in the first directory specified above. To not override the logya command from your installation the command is called logyadev.

Credits

Logya is being developed by Ramiro Gómez. The Logya logo was created using the Earth, Internet icon by IconEden.

Fork me on GitHub