Welcome to Poltergeist, yet another static site generator based on Gulp. Here is a quick summary of what it does:
- Static and simple
- Supports HTML with inline Markdown
- Supports Markdown with inline html
- Supports FrontMatter to add meta-data
- Supports advanced layouts and templates
- Supports SASS
- Concatenates, minifies, versions and gzip assets (images, fonts, css, js and html)
- Generates a RSS feed
- One command to develop for with
gulp - One command deploy to S3 with
gulp deploy - Supports Cloudfront distributions and manage cache invalidation
git clone https://github.com/pillars/poltergeist.git
rm -rf .git README.md CHANGELOG.md
npm install -g gulp
npm install
cp .env.example .env
We remove the .git folder because there is no benefit in keeping ties with this repository. You can instantiate a new repository for your project with git init.
You can skip setting the values in the .env file for now but you will need them for deploying. You will want to edit the src/site.json file though to enter your site information:
- title: The default title for the site (can be overridden for each page)
- url: The site url
- author: Who are you?
- email: Where can we reach you?
- feed: How do you want to name your RSS feed? Leave blank to disable the RSS feed.
To start the development server, simply run gulp. It also watches for changes, recompiling the assets and templates. By default, the site will run at localhost:8000.
Templating is done with nunjunks. You can quite easilly replace the renderer by playing with the renderHTML() function in the Gulpfile. Poltergeist works with HTML (nunjunks templates), Markdown or any combination of the two.
If you want to create pages with complex layout and logic, Poltergeist supports nunjucks templates. Let's look at the index.html:
---
title: My Site
---
{% extends "layout.html" %}
{% block content %}
<div class="container">
{% for post in posts %}
<div class="post">
<h2 class="post-title">
<a href="{{post.url}}">
{{post.title}}
</a>
</h2>
<p class="post-excerpt">
{{post.excerpt}}
</p>
<p class="post-meta">
{{post.date}}
{% if post.tags.length %}
-
{% for tag in post.tags %}
{{tag}},
{% endfor %}
{% endif %}
</p>
</div>
{% endfor %}
</div>
{% endblock %}
This extends the layout.html and the Front Matter defines the title that will be used for the page. It also loops through the posts but we will get to that shortly.
If you feel like adding some markdown to your nunjucks template, no worries. Do something like that:
{% markdown %}
# This is markdown in a nunjucks tempalte
{% endmarkdown %}
There are time when you simply want to write content and HTML is overkill. So we support markdown files with the .md extension. Let's look at an example:
---
title: My Site
---
# This is a <span>Markdown</span> title
We still have the title. Note that we do not declare a layout, but it will use layout.html by default. You can change that by adding a layout: mylayout.html to the Front Matter. Another thing worth noting is that HTML isn't escapte so you can use some inline HTML. It is convenient when you need some flexibility.
Templates come in two flavors: Posts and Pages. Each have its own directory.
Every post must be a folder formatted like src/posts/2016-06-24-slug with an index.html in it. It allows to have a pretty url like /2016/06/slug as well as ordering the posts. Poltergeist leaves the day out of the url because there is no benefit. Some people dislike having the date in the url, I think it is of great value. I want to know at first sight if I'm reading a recent or old article.
The Front Matter for posts can take whatever you feel like. There is an excerpt key in the example file. Note that the date and url fields are auto generated from the folder name.
You can keep the images related to a post inside the post folder. Simply create an images/ folder. Inside your post, the imageFolder variable allows you to forget about where the files are. To add an image do something like:
<img src="{{imageFolder}}/image.png" alt="" />or:
[]({{imageFolder}})There is no constraint of format here. You can use the same strategy as posts by using folders and index.html files or you create whatever.html files.
Poltergeist comes with a single scripts.js file. It might be enough for a small site but it also has its limits. Good news, we already have nunjucks for templating so you can use it here too. Any file in the src/assets/js/ folder can be included. It is up to you to take care of the order and make sure things are properly included. Simply add this for instance {% include "./vendor.js" %} and the src/assets/js/vendor.js file will be included.
All javascript file are uglified before being deployed.
Poltergeist comes with SASS support. If you want to organize your CSS in multiple files, refer to the SASS documentation. It basically consist of adding something like @import 'prism'; and the src/assets/css/_vendor.scss file will be included (note the underscore).
All css files are minified before being deployed.
Poltergeist will upload your site to the specified bucket on S3 and if you have a CloudFront distribution, it will make sure to invalidate what needs to be. But first you want to configure your credentials in the .env:
- PRODUCTION_ASSET_URL: The cloudfront or S3 domain name where the site is hosted. Something like
abcdefg123456.cloudfront.net - S3_BUCKET: The S3 bucket where the site is hosted. I usually use the domain name like
yoursite.com - AWS_REGION: The AWS region of the bucket. See docs here.
- AWS_ACCESS_KEY_ID: The AWS access key
- AWS_SECRET_ACCESS_KEY: The AWS secret access key
- CLOUDFRONT_DISTRIBUTION: The CloudFront distribution id
If you need help setting up S3, Route53 or CloudFront, read this tutorial.
You also want to make sure that the AWS keys have access to the S3 bucket and Cloudfront. Once that's the case, you can deploy by running gulp build:deploy.
This project is inspired by the work of Sean Farrell and Zell Liew and a bunch of other folks.
- Sitemap.xml
- Social sharing
- Tags
- Months pages