Skip to content


Repository files navigation

white flower daisy fing shawiwey by Mark Gonzales Build status Dependabot Status Casual Maintenance Intended


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"}

Use gonz to scaffold your site skeleton:

mix deps.get
mix deps.compile
mix MyAwesomeSite
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.


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.


  • 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. [site-name]

Creates a new gonz project/site.


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

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

Example: mix "My amazing post about Things"


  • post-title: Required title of the post [theme-name] [output-directory] [posts-per-page]

Builds the site.


  • 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.


  • 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.


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

Planned tasks

mix 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 🎉


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 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 <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 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"!


  • 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