Guarana v0.0.7 | Static Site Generator
- Development: A gulp build-stream that will allow you to quickly build a static website.
- Blogging: A set of build tools that will parse your local Markdown and compile your blog with awareness of dates, categories, SEO tags.
- Pug for templating.
- Sass for styling. (can be replaced)
- Markdown for blog content.
See the demo
- A demo blog made by Guarana
- Install gulp globally
npm install gulp -g
- Clone this repository
git clone https://github.com/levsthings/guarana nameYourProject
- Install surge globally (optional- if you want to deploy with Surge)
npm install surge -g
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.)
- Compresses images (It's lossless compression by default so it won't reduce much.)
- Moves your assets to development and production folders.
What you get when you clone Guarana
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.
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.
Deploy: (Deploy to surge)
- Deploys /production folder
- See your work live with browser-sync
- Auto refresh when changes to code are made.
Step 1: Always start with building
Step 2: Serve and publish locally
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.)
- 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.
- 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).
- 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
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:
Your data should be now ready and you can proceed to the full build and development steps.
- By default blog post markdown are stored in /content folder.
- Pay attention to the mock markdown files and see what kind of data is passed to JSON. Especially slugs. They are referenced in Pug.
- 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.
- 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.
- Implement remote building
- Implement testing