Skip to content
This repository has been archived by the owner. It is now read-only.
guarana - a static site generator
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
guarana
src
.gitignore
README.md
gulpfile.js
package.json

README.md

Guarana v0.0.7 | Static Site Generator

Dependency Status

Guarana is an opinionated static site generator with blogging in mind. It consists of two main elements, development and blogging.
  1. Development: A gulp build-stream that will allow you to quickly build a static website.
  2. Blogging: A set of build tools that will parse your local Markdown and compile your blog with awareness of dates, categories, SEO tags.

The opinions

  1. Pug for templating.
  2. Sass for styling. (can be replaced)
  3. Markdown for blog content.

See the demo

  1. A demo blog made by Guarana

Installation

  1. Install gulp globally npm install gulp -g
  2. Clone this repository git clone https://github.com/levsthings/guarana nameYourProject
  3. Install surge globally (optional- if you want to deploy with Surge) npm install surge -g
  4. Run npm install

Section One - Development

An overview of the development stream

  • Compiles Pug
  • Compiles Sass, minifies Sass, auto-prefixes the output. (If you include bootstrap scss files in your src/scss/application.scss file, they'll also be treated.)
  • Transforms JavaScript with Babel ES2015 preset. Concatenates and minifies the resulted JavaScript.
  • Compresses images (It's lossless compression by default so it won't reduce much.)
  • Provides source maps for JavaScript and CSS
  • Moves your assets to development and production folders.

What you get when you clone Guarana

project
│   README.md
│   gulpfile.js
│   package.json
└───guarana //guarana scripts live here
└───node_modules
└───src //  develop your website here
│    └─── templates (pug)
│    └─── scss (your sass)
│    └─── js (javascript)
│    └─── img (images for static content e.g. logo)
│    └─── content (Markdown for blog posts)  
│ 			└─── img (images for blog posts)
│			└─── json(the result of markdown parsing)

The output of the development stream

The build results in two main outputs. First, everything you need for your website is compiled and served in a newly created /development folder. Source maps for JS and CSS will be included and browser-sync will serve you this folder for you to live-view.

Second, everything in the development folder will also get copied to a newly created production folder. This folder does not include source maps and it's ready to be pushed to web.

Here's how your folder structure will look like after you build. folders collapsed view:

project
│   README.md
│   gulpfile.js
│   package.json
└───guarana //guarana scripts live here
└───node_modules
└───src // you develop your website here
└───development // includes sourcemaps, served via browser-sync
└───production // doesn't include sourcemaps, ready to be pushed to web.

By default, .gitignore file ignores development and production folders because each build process starts with a cleaning of the previous build which means they'll get deleted frequently. Also, cleaning up manually right is a good thing to do.

Main Commands:

To Build:

gulp guarana

Clean-Up: (each build process starts with a cleanup but sometimes you need a clean-up after you're done working.)

  • Get rids of /development and /production folders.
gulp clean

Deploy: (Deploy to surge)

  • Deploys /production folder
gulp deploy

Development Workflow

Overview

  • Build
  • Serve and watch for changes in Pug, JavaScript, Sass and compile on the fly
  • See your work live with browser-sync
  • Auto refresh when changes to code are made.

Step 1: Always start with building

gulp guarana

Step 2: Serve and publish locally

First tab:

gulp serve

Second tab:

gulp browser-sync

Step 3: Develop your website! Work in your /src folder.

Section Two - Blogging

In this section, we'll take a look at how Guarana builds your blog using your Markdown files. By default, blog building steps are included in the main build process. Using the steps from the previous section is enough but we'll take a look at under the hood here.

####Build steps for blog (You don't need to use these manually, but it's good to know them.)

  1. indexBlogContent Guarana parses your local markdown content and outputs an index.json file containing all the Markdown with all the necessary information. The JSON is then stored in an objects and passed to Pug as locals for building the index.html page. The example index.pug will loop through your blog posts in a single html file.
  2. loopBlogContent This step is for creating an html page for each post you have. Unlike index.html, Guarana uses a seperate Pug compile step for this action. Basically, Guarana loops a Pug compile process for each post you have so that you can have seperate html files for each post. As a template to create posts, Guarana uses posts.pug (/src/templates/posts/posts.pug).
  3. categoryLoop Similar to the previous step, Guarana loops a Pug compile process for each category you have so that you can have seperate html files for each category page. As a template to create category pages, Guarana uses categories.pug (/src/templates/posts/categories.pug).

Blog variables and sorting

In between the parsing of Markdown to JSON and passing them to Pug for compile, Guarana steps in and stores the JSON data in JavaScript objects. These objects are used for sorting according to date, category etc. and then handed over to seperate Pug compile tasks.

If you clone this repository, you'll have some mock data to work with. But if you delete the mock markdown and the index.json file, your main build will fail because Pug expects the aforementioned data. In such case, first add your markdown and then run:

gulp indexBlogContent

Your data should be now ready and you can proceed to the full build and development steps.

Additional notes:

  1. By default blog post markdown are stored in /content folder.
  2. Pay attention to the mock markdown files and see what kind of data is passed to JSON. Especially slugs. They are referenced in Pug.
  3. By default, images for blog posts are put into /content/img. Your images will get moved in the build step and they will get merged with the /src/img folder, you don't have to do anything. The reason for having two different image folders is for a future remote building feature for authors to be able to just drop their markdown and post images to the content folder.

Section Three : Customization and Troubleshooting

If you want to customize one or more of the build steps or you want to understand how things work, go the /guarana folder, there you'll find all the build tasks with detailed comments.

Known Issues

  1. When you build, Pug might skip some of the locals we passed it due to the sequencing and you might not see the output you expected. If this happens, run the clean up command and build again.

Todo List

  • Implement remote building
  • Implement testing

Credits

You can’t perform that action at this time.