castlepointanime/brancher

Lightweight static site generator using Twig

dev-master 2015-10-18 11:02 UTC

Requires

• php: >=5.4.0
• erusev/parsedown-extra: ^0.7.0
• kriswallsmith/assetic: ~1.3
• mnapoli/front-yaml: 1.5.0
• symfony/config: ~2.7
• symfony/console: ~2.7
• symfony/dependency-injection: ~2.7
• symfony/event-dispatcher: ~2.7
• symfony/filesystem: ~2.7
• symfony/finder: ~2.7
• twig/twig: ~1.0
• webnium/json-pointer: dev-master

Requires (Dev)

• phpmd/phpmd: @stable
• phpunit/phpunit: ~4.7
• sensiolabs/security-checker: ~2.0
• squizlabs/php_codesniffer: 2.*

GPL-3.0+

• Tyler Romeo

README

Brancher is a generic static site generator, based on Symfony components and using the Twig templating language. It was designed to be easy to use, but extensible and usable for any type of site structure.

License

Brancher is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

For this documentation:

Copyright (C) 2015 Tyler Romeo. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

Code samples in this documentation are placed in the public domain, or under the Creative Commons 0 license if needed by jurisdiction.

Why Brancher?

We created brancher because there were certain features we couldn't find in other static site generators:

• Storage of arbitrarily structured data (and the ability to iterate over it)
• Easy processing and filtering of JavaScript and CSS resources
• Addition custom PHP extensions to the build tool for site-specific functionality

Unlike other static site generators, this is not blog-focused. There is no flat "_posts" directory that contains all of the dynamic content for the site. Instead this is meant for non-blog websites that sometimes contain multiple levels of structured data.

Requirements

Brancher is PHP-based, so it needs a couple of things:

• PHP 5.4 or greater for command-line (usually available as the package php5-cli)
• Composer, a dependency management tool for PHP

That's it! All the libraries Brancher needs will be installed in the vendor/ directory of your project using Composer. Check out the Composer documentation for more details.

Installation and Use

Brancher can be installed and used with Composer:

# Install
composer init
composer require castlepointanime/brancher

# Use
./vendor/bin/brancher build
# => The current folder will be rendered into _site/

Directory Structure

A typical Brancher project has a following typical directory structure (note that the location of each directory can be customized):

.
├── index.html
├── _config.yml
├── _templates
|   ├── base.twig.html
|   ├── layout.twig.html
|   ├── header.twig.html
|   └── footer.twig.html
├── _resources
|   ├── js
|   |   ├── my_library.js
|   |   ├── other_library.js
|   └── css
|       ├── base_style.css
|       ├── home_style.css
|       └── other_style.css
├── _data
|   ├── news
|   |   ├── 2015-08-10-post-of-some-sort.html
|   |   └── 2015-09-20-another-news-post.html
|   └── staff
|       ├── ceo.html
|       ├── cfo.html
|       └── software_engineer.html
└── _site

An overview of the purpose of each of the directories:

Configuration File

As mentioned before, there is a _config.yml file, whose location can be customized, that can be used to specify build parameters. (Note: the config file is processed using Symfony, meaning it can be any file extension that the Symfony config component supports, specifically YAML, XML, PHP, and INI.)

Example Config file:

brancher:
    build:
        # The <root> directory
        root: src

        # The <output> directory
        output: _site

        # Any --template-dir directories
        templates:
        - templates

        # The --resource-dir directory
        resources: resources

        # Any --data-dir directories
        data:
        - data

        # Any directories to --exclude
        excludes:
        - vendor

Warning: Command line options will override whatever is in the configuration file. If an option is not specified on either the command line or config file, then the default mentioned above will be used.

Read More

That's the basics! If you want to read more about a specific component of Brancher, visit any of the pages below:

• Writing Pages and Templates: Introduction to using Twig templates with Brancher
• Adding Site Data: Using data in the --data-dir directories inside your site's pages
• Using Assetic for Resources: Processing and versioning resources using Assetic
• Built-in Extensions: Usage for some built-in extensions that provide functionality in Brancher
• Making or Installing Extension: Making your own extensions and hooking into the build process