Welcome to PyBlue

fractal1.gif

A simple static site generator.

PyBlue allows the reuse of visuals (header/footer) and data across many pages and it can generate static sites from dynamic templates.

This page was created with PyBlue from the file located in docs/index.html

Why PyBlue?

There is no shortage of static html generators. PyBlue is a personal project that aims to address my personal annoyances with other options. I have evaluated quite a few alternatives even used some over longer periods of time. None of the choices did what I needed for my work. Hence came the motivation to write my own.

fractal3.png

The following are some of the reasons why PyBlue exists:

  1. All features are optional!
  2. Requires no special configuration to get started.
  3. Automatic linking! Reorganize the site without having to worry about broken links.
  4. Automatic syntax highlighting of code.
  5. Integrates seamlessly with Markdown.

And then of course it has many advanced features:

  1. Advanced templating Django Templating system and all that it offers.
  2. Support extending the template language via custom template tags.
  3. Pyblue can be told to load data into any page.
  4. The template system can operate on data loaded into the page.
  5. Tiny codebase, eminently hackable. PyBlue is around 500 lines of code.
  6. Runs on all Python version from 2.7 to 3.6

Install

pip install pyblue --upgrade

Or download it from the PyBlue at PyPI. Alternatively to install the latest version:

git clone git@github.com:ialbert/pyblue.git
cd pyblue
python setup.py develop

Usage

The documentation that you read now has been created from the files in the docs folder.

To see extra help on options run: pyblue -h

Features

Context

fractal2.png

The pages are rendered through the Django Template language. To make use of the templating you need to understand how this templating language works.

By default there is extra data associated with each page. For example the {{ page }} variable is available:

Note how in this last case we also made use of the filesizeformat builtin filter of Django. Users may add more information even load a python module into the page.

More details on the Context page.

Links and Images

Users can also make use of pyblue specific template tags that are automatically available. For example the link tag generates relative paths to any other file.

fractal4.jpg

Important: Note how in this case the file is located in info/context.html Yet we did not have to put the full path the linking tag. PyBlue found the file and linked it properly.

Why did that work? The {% link "context.html" %} command performs a regular expression search on all files in the directory and once it finds a match it produces a link to it with the proper relative path. This keeps links correct even if the files were to be moved later.

Note that the search string is a regular expression and it is sufficient to specify the shortest unambiguous part of the filename. PyBlue will find it and link it.

As a matter of fact this is one reason PyBlue was written. I got very tired of fixing broken links after a site reorganization. PlyBlue now does it automatically.

The {% img "fractal.png" %} tag works similarly to the link tag. but generates image links. It also takes the css parameter where css classes may be passed to the image. The CSS itself will have to be defined in the page header or the site asssets.

Markdown

To include markdown content into an HTML document place it between {% markdown %} and {% endmarkdown %} template tags.

Fenced code blocks

When using markdown fenced codeblocks may be used. Include code between ``` symbols that can also take language hints:

import sys
for line in open("data.txt"):
    print line.strip()[:10]

Include code

To include syntax highlighted code from a file write {% code "context.py" lang="python" %}

#
# The data file named context.py in the root folder
# will be loaded automatically into the page.
#

NUMBERS = range(5)

# It may contain any valid python construct.

def say_hello(name):
    return "Hello %s" % name

greeting = say_hello("World!")

This file is also special because of its name: context.py. The contents of this python module is available inside every page under the name of context.

For example writing {{ context.greeting }} produces: Hello World!.

This is where the full power of pyblue shows. You see, you can go wild and add any and all data that you might need. Call out to any program, read any file etc. It is Python all the way down.

Include markdown

Alternatively one can instruct PyBlue to include the rendered content of markdown files.

To include the file example.md in its original content one would use {% code "example.md" %} this would produce:

---

**Note**: This text comes from a **markdown** file.

    print "Hello World!"

---

This same file could be included as html with {% markdown_file "example.md" %} In that case it will produce the following:

Note: This text comes from a markdown file.

print "Hello World!"

Note how in both cases an automatic search takes place PyBlue will find the location of the file example.md wherever it might be on the root directory. That's super convenient.

Advanced templates

The django templating system allows extending or including other templates or sections.

These features support template inheritance and composition.

Read on from more Advanced Features and Markdown test page

Licensing