Skip to content
master
Switch branches/tags
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 

white flower daisy fing shawiwey by Mark Gonzales

Hex.pm Build status Dependabot Status

gonz

I can write anything and just put it in a zine, and then it's out there. It is like blogging but on paper. It is what I started to do before the computers were all popular.

Static site generator. Heavily inspired by Obelisk (thanks for a great project!).

Quick start

Start a new elixir project:

mix new mysite

Add gonz dependency:

defp deps do
  [
    {:gonz, "~> 3.1"}
  ]
end

Use gonz to scaffold your site skeleton:

mix deps.get
mix deps.compile
mix gonz.new MyAwesomeSite
mix gonz.build
mix gonz.serve

Open http://localhost:4000/ in your browser.

Now you probably want to start editing the default theme (or create a new one). See my own personal site for an example.

Goals

Some things I've had in mind while hacking on gonz:

  • Use case: personal homepage with blog like posts, and static pages.
  • Write posts and pages in Markdown.
  • Support themes / templates with EEx only. I doubt I will add support for anything else
  • Simple to use and get started with, using mix tasks
  • Few dependencies
  • Clarity over performance. Performance shouldn't be horrible, but is not a top priority at this point.

Features

  • Write pages and posts in Markdown
  • "Themes" with EEx templates
  • Front matter is specified as an elixir map
  • You can put categories on pages/posts, then themes can handle them in whatever way they wish.
  • There is a special category :nav_item that will enable themes to handle some pages as navigation items.

Mix tasks

These are the most common ways to interact with gonz while building your site.

gonz.new [site-name]

Creates a new gonz project/site.

Arguments:

  • site-name: Optional name of the site to create, just determines how the bootstrapped site will look.

gonz.post <post-title>

Creates a new post in posts/ with the specified title.

Example: mix gonz.post "My amazing post about Things"

Arguments:

  • post-title: Required title of the post

gonz.build [theme-name] [output-directory] [posts-per-page]

Builds the site.

Arguments:

  • theme-name: Optional name of the theme to use, defaults to "default"
  • output-directory: Optional name of the build/output directory. Defaults to "./build"
  • posts-per-page: Optional number of pages per index page. Defaults to 10.

gonz.serve [output-directory] [port]

Serves the built site for local development.

Arguments:

  • output-directory: Optional name of the build/output directory to serve files from. Defaults to "./build"
  • port: Optional port of the http server, defaults to 4000.

gonz.purge [output-directory]

Removes all files related to the site. This can give you a fresh start. Mostly used for manual testing new sites easily.

Arguments:

  • output-directory: Optional name of the build/output directory. Defaults to "./build"

Planned tasks

mix gonz.page title

Adding static assets to your site

Example: You want to add the image "pangolin.png" to a post

  1. Copy pangolin.png to "./assets/images/" (you may have to create the "images" subdir)
  2. In your post file markdown, insert: ![A cool pangolin](./assets/images/pangolin.png)
  3. Build the site 🎉

Themes

The easiest way to create your own theme is to copy the default one, and use it as a reference on how and what data is available. Example of a custom theme can be seen in forvillelser

The exact API for themes are subject to change. The available data for the theme templates are returned by Document.to_assigns/1

Building your site with a non-default theme

If you use a custom theme, don't forget to specify the name of it when you build your site, ex: mix gonz.build mythemename build 10

If this gets repetitive I suggest you create a target in a Makefile.

Github pages howto

  • Enable github pages for your project (pick "Master branch /docs folder" source option)
  • Create a docs dir in your project root
  • When building the site make sure you specify the docs dir as the output directory: mix gonz.build <theme> docs
  • Add all files in docs and commit, push. 🎉

Netlify howto

Even simpler! My own site uses Netlify, so you can copy the Makefile in Forvillelser.

  • Then configure the project in netlify to use make as the build command, and build as the publish directory.
  • Now all you need to do is write your posts, commit and push them and netlify will build the site and publish it. 🎉

Why

Why create something new instead of using Obelisk, Serum, or Coil?

Short answer: Fun, learning, and flexibility.

Longer answer: I checked out all of these projects. Out of the three I really liked how Obelisk looked to use, but it did not compile out of the box. Once changing some dependencies (plug), it compiled, but when running it crashed. I looked closer at the github page and noticed that the project was a bit abandoned. Then I figured "meh, let's code"!

Todo

  • What about drafts..
  • Rethink code structure, can simplify a lot of things and make it more consistent I think. The clarity bullet in the goals section is not quite there yet :)
  • Low hanging speed ups (Task.async?)
  • Assets. Right now it's all or nothing. What if I want to publish a separate page that needs some assets that nothing else needs?

Upgrading themes from 2.x to 3.x

  1. Change from Document.category to Document.item
  2. Change nav_item: true to categories: [:nav_item] in front matter