Skip to content

Latest commit

 

History

History
90 lines (58 loc) · 3.04 KB

README_.rst

File metadata and controls

90 lines (58 loc) · 3.04 KB
Raw

Phial

Phial is a simple Python library for building static sites.

The API is currently unstable. Don't use Phial in your project yet. But if you can't wait, join me in developing it ;). The rest of this README is one in a series of drafts of what's to come.

# hello.py

from phial import page

@page("index.htm")
def homepage():
    return "Hello World!"
$ pip install phial
$ phial --testing hello.py # Serves at http://localhost:9000

Phial is Unopiniated

Its small feature set includes:

  • YAML frontmatter parsing
  • UTF-8 and UTF-16 file support (unicode supported throughout)
  • Built-in development server
  • Automatic reloading
  • Sensible API
  • Lots of love

Its small feature set does not, and never will include:

  • Any template engine
  • An opinion on how you structure your site
  • Magical, hard to understand features
  • A huge list of dependencies

Phial is made for Python Developers

I'm tired of SSG's that use extremely heavy, and extremely leaky, abstractions.

When I make a static site I want to have absolute control over everything without having to dive into the internals of some crazy plugin system. At the same time, I don't want to have to reinvent a ton of simple, convenient things like automatic reloading or running a dev server.

Phial is my solution to this frustration. Let me know what you think.

Quick Walkthrough

As you saw in the short snippet above, it's certainly possible to make a Phial site that doesn't use any source files (ie: templates, documents, images, etc). Most of the time this isn't what you want though.

Here is a slightly more developed example.

from phial import page, open_file, register_simple_assets

register_simple_assets("styles.css", "images/*")

cats = []

@page("cats/{name}.htm", files = "cats/*.htm")
def bio_page(source, target):
    # Page functions are executed in the order in which they are declared
    # so the `cats` list will have all of the cats by the time we get to
    # the main_page() function.
    cats.append((source.frontmatter["name"], target))

    template = open_file("bio_template.htm").read()
    return template.format(content = source.content, **source.frontmatter)

@page("index.htm")
def main_page():
    links = "".join(['<li><a href="{}">{}</a></li>'.format(*i) for i in cats])

    template = open_file("main_template.htm").read()
    return template.format(links = links)

I avoided using any external templating or rendering engines in this example, but there's nothing stopping you from using Mustache, Jinja2, Markdown, reStructuredText, or any other library in your app.

Sites Using Phial

If you want to see even more developed examples, check out these sites! There's only one right now but it would be awfully nice if there were more... (nudge nudge)