Skip to content
This repository has been archived by the owner on May 24, 2022. It is now read-only.

Latest commit

 

History

History
203 lines (141 loc) · 8.89 KB

README.md

File metadata and controls

203 lines (141 loc) · 8.89 KB
Raw

Build Status

Site-builder

Site-builder is a simple static site generator. It allows you to create and manage a website out of simple text files and templates. This gives you many of the advantages of a CMS, but because the result is plain old HTML, it's more secure and has higher performance.

Site-builder works by copying files from your content directory to an output directory, applying one or more transformation filters on the way.

Note: There are more stable and better-supported static site generators out there; this is just a personal project to help me learn and improve my code. If you're looking for a well-supported and very capable static site generator, look at Jekyll (Ruby), Hyde (Python), or Phrozn or PieCrust (both PHP).

Quick Start

  1. Download the .phar file. It's the whole app in one file, with everything it needs to run.
  2. Put sitebuilder.phar in the directory where you want to keep the installation.
  3. Run php sitebuilder.phar init to create directories, config, and sample files.
  4. Test your installation with php sitebuilder.phar rebuild. If it works, you should see a generated example.html file in the output directory.
  5. Replace the default template with your own. Twig is a pretty straightforward template language; just put {{ content | raw }} where you want your page content to appear. Read on for more help and links to the Twig docs.
  6. Create your content files. You can write plain HTML (and save as .html), or Markdown (and save as .md or .markdown). You can make sub-directories too. Read on for more info on Markdown, including a link to the documentation.
  7. Run php sitebuilder.phar rebuild to regenerate your site.

Why use it?

Using a CMS or Apache/PHP includes will build your site dynamically upon request, which adds a lot of overhead - your content probably doesn't change very often, and all you really need those things for is to keep your content and your templates separate.

By contrast, static site generators run offline and rebuild your site as flat HTML when you change your content. A web server like Apache can deliver flat HTML files hundreds of times more efficiently than processing PHP files every time they're requested.

Site-builder is yet another SSG. Out of the box it supports Twig templates, and content files in HTML and Markdown. It's also extensible, so you can add transformations for any other behaviour you want.

Requirements

  • PHP 5.3 or newer. If you use Ubuntu or Debian, you may need to install the php5-cli package to let you run scripts on the command-line.

If you aren't running the .phar edition, you'll need these:

  • Twig 1.6 or newer
  • "dflydev"'s Markdown library
  • Symfony2 Components: Yaml, Config, DependencyInjection, ClassLoader, Console

A composer.json file is included to handle the installation of these requirements. See the next section for more about this.

Installation

  1. Download or clone this repository.
  2. From the command-line, run curl http://getcomposer.org/installer | php and follow the on-screen instructions to install Composer.
  3. Run php composer.phar install to install all the required libraries into the vendor directory.
  4. Test the installation by running php sitebuilder.php rebuild. Check for files in the output directory.
  5. If you're helping to develop Site-builder, run php composer.phar install --dev to install PHPUnit, and run it with vendor/bin/phpunit. You can copy phpunit.xml.dist to phpunit.xml if you want to change it. Rebuild the phar with the compile.php script.

Usage

The basics

  1. Put your content (e.g. index.html, about-me.md) into the content directory. Content files are just that: the main content of the page you want to publish. The name of the file when you publish will be the same as the content file, except with .html instead of the original extension. You can create sub-directories in your content directory and they'll be created in the output directory when you publish, so don't feel like you have to cram everything into the same directory.

  2. The default template is template.twig in the templates directory. Change it however you like. You can also change the default template in config.ini. More on that later. The content of your content files is placed into the template variable called $content (or {{content}} in Twig).

  3. Run php sitebuilder.php rebuild to render every file and save it to the output directory.

Templates

Twig is a fast, clean, and extensible template language with a syntax very similar to Jinja and Django's templating systems. Read more about writing Twig templates here.

Twig escapes output by default, which is very safe and good practice. However the content variable which contains your page content probably shouldn't be escaped. You can tell Twig not to escape it by passing it through the raw filter, i.e. {{ content | raw }}

Content

Site-builder accepts content in either HTML or Markdown format. Pick whichever you prefer, or use both. Both have an optional "front matter" block which contains instructions you can pass to the template.

HTML & Twig content format

Look at content/example.html for an example. The file is like any other HTML file and you can write whatever you like into it. The only difference is an optional front matter block, which allows you to pass more information to the template when you rebuild the site.

When the page is published, the contents of the file are passed to the template in the content variable along with anything else you define in your front matter block.

---
title: This is my page title
---

<h2>Hello world!</h2>
<p>This is my content file. There are many like it but this one is mine.</p>

If you set the template variable in your front matter, then Site-builder will render the page with that template instead of the default.

Markdown & Twig content format

Markdown is an "easy-to-read, easy-to-write plain text format", which is then turned into valid, clean HTML. It was developed by John Gruber and is very popular. This page itself was written in Markdown. A simple example markdown content file can be found in content/markdown-example.md.

Read more about writing Markdown here.

There are four important things to note about Markdown content files in Site-builder:

  1. Markdown can contain plain old HTML, so don't feel constrained by it!
  2. Your markdown content files should end in either .markdown or .md
  3. Site-builder looks for (but doesn't require) a "front-matter" block where you can set variables to be passed to your template.
  4. Site-builder uses Markdown Extra by default. It add some features to Markdown, like tables, ids, code blocks, and footnotes.

The front-matter block is written in YAML and looks like this:

---
title: This is my page title
template: myTemplate.twig
---

My page title
=============

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor 
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis 
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu 
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in 
culpa qui officia deserunt mollit anim id est laborum.

When you rebuild the site, Markdown files are converted into HTML and then passed to either the default template, or whichever template you named in the front-matter block. The HTML content is set on the {{ content | raw }} variable in the template.

Contributing

I'd love to have pull requests to improve Site-Builder. Please raise an issue first though, in case someone's already working on the feature.

  • I think I've got good unit test coverage, but I'm no expert. Any help with tests would be appreciated.

  • Documentation (end user and developer). I've started to add doc-comments and there's this README, but there could be more and better, I know.

  • A navigation generator object passed to the templates that represents the site structure, so that templates can create left navigation. It should ignore resource files and be context aware (so links in sub-directories don't break).

  • Please submit pull requests to the dev branch! The master branch is for tested, stable releases only.

Contributors