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:
- Content can be written in markdown and HTML.
- More flexible site URL structure: the url for each document must be specified in the document header and is independent of the file's location within the content directory. This way you can freely structure your content and choose your preferred style of URLs, e.g.
example.com/path/doc/
orexample.com/path/doc.html
.
Features
- Create responsive static Web sites
- Full control over layout and design with easy-to-use templates
- Free choice of front-end libraries like jQuery, Twitter bootstrap, or HTML5 boilerplate
- Built-in Web server with info level logging for immediate editing feedback in the browser
- Use your favorite editor to create content
- Manage, deploy and backup the site with the tools you know, e.g. tar, rsync, git, mercurial, subversion
- Commands for site creation, generation, and serving
- Automatic generation of document indexes in created directories
- Site configuration
- No server side scripting security issues
- RSS feed generation for all content directories and tag directories
- Execute code in bin dir during generation and serving
- Canonical URL as
canonical
variable available in all templates - Url encoding in templates using the
urlencode
filter
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.