A little static site generating gem.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.



A simple, opinionated static site generator.

Build Status Test Coverage Gem Version

Note: This is a new version of Dimples, and it's a complete rewrite. You can still find the original here.


  • Tilt - for the templates.
  • One of the gems Tilt uses for templating, depending on your needs.


Assuming you're using Bundler, add this to your Gemfile:

gem "dimples"

And then run bundle.


Dimples includes a very simple command-line tool, imaginatively named dimples, which lets you generate a site in the current directory by running dimples build.

It assumes your directory structure will look like this:

  • config.json
  • pages/
  • plugins/
  • posts/
  • public/
  • templates/
    • feeds/


Any files in pages/ will be turned into static pages, maintaining any folder hierarchy you're using.


A plugin allows you to customise posts and pages before and after they're generated.


Dimples assumes your posts will be named in the following format:



Any files in here are copied as is into the final site.


Templates wrap the contents of your pages and posts. Any template stored in the feeds subdirectory will map its filename to the feed's extension - templates/feeds/atom.(extension) becomes feed.atom, and so on.


Dimples supports YAML frontmatter at the beginning of a post, page or template file.

title: My first post
layout: post
- first
- static

Today I read documentation about a static site generator.

Some elements in frontmatter hold special meaning to Dimples: layout defines which template to render for the given source file (and this is true for pages, posts and templates.)


As your pages, posts and templates are rendered, Dimples makes special variables available:

  • site, the entire Dimples::Site instance.
  • page, the current page being rendered.
  • template, the current template being rendered.

Anything in your frontmatter is available to either the page (for a page or post) or template (for a template) objects.

title: My title
layout: category
custom_field: true

If this was a page or post, you'd have access to page.title, page.layout and page.custom_field, and if this was a template, template.title, template.layout and template.custom_field.


Key Description
site.posts All the posts in your site, ordered by the most recent first.
site.latest_post The most recent post on the site.
site.categories All categories across the site.


Key Description
page.title Defined by you, or auto-generated by the archive and category pages (otherwise it's empty).

When a post is being generated:

Key Description
page.date The date of your post based on the filename.
page.slug The last part of your post's filename.
page.categories An array of categories your post belongs to, if any. Each category has a name, slug and a list of posts available.

When a feed is being generated:

Key Description
page.feed_posts A list of posts for the feed to render.

When an archive page is being generated:

Key Description
page.archive_date The date of the current archive date.
page.archive_type Either year, month or day.


The template object pulls in anything from that template file's frontmatter, similar to how page works.


If the page being generated is part of a paginated collection, there's also a pagination object.

Key Description
pagination.posts A list of posts for the current page.
pagination.current_page The current page number.
pagination.page_count The total number of pages.
pagination.post_count The total number of posts.
pagination.previous_page The previous page number, if any.
pagination.next_page The next page number, if any.
pagination.urls.current_page The URL for the current page.
pagination.urls.first_page The URL for the first page.
pagination.urls.last_page The URL for the last page.
pagination.urls.previous_page The URL for the previous page, if any.
pagination.urls.next_page The URL for the next page, if any.


Dimples has a number of options for customising how it works - here are the defaults:

  "source": "./",
  "destination": "./public",
  "paths": {
    "archives": "archives",
    "paginated_posts": "posts",
    "posts": "archives/%Y/%m/%d",
    "categories": "archives/categories"
  "generation": {
    "paginated_posts": true,
    "archives": true,
    "year_archives": true,
    "month_archives": true,
    "day_archives": true,
    "categories": true,
    "main_feed": true,
    "category_feeds": true
  "layouts": {
    "post": "post",
    "category": "category",
    "paginated_post": "paginated_post",
    "archive": "archive",
    "date_archive": "archive"
  "pagination": {
    "page_prefix": "page",
    "per_page": 10
  "date_formats": {
    "year": "%Y",
    "month": "%Y-%m",
    "day": "%Y-%m-%d"
  "feed_formats": [
  "category_names": {},
  "rendering": {}

Source and Destination

Both of these options are full directory paths - by default, the source is the current working directory, and the destination is the same with public appended.


The relative paths used to build generated files - each is appended to the destination directory.

Key Default Description
archives archives The path for the main paginated archives.
paginated_posts posts The path for index-style pages for all posts.
posts archives/%Y/%m/%d The path for posts (suffixed with the individual post slug). This string is passed to Ruby's strftime Time method, so you can use any of its options here.
categories archives/categories The path for category index pages (suffixed with the individual category slug).


Choose what gets built when Dimples runs.

Key Default Description
paginated_posts true If we should build out paginated pages for all posts.
archives true If we should build the main paginated archive pages for all posts.
year_archives true If we should build paginated year archives.
month_archives true If we should build paginated month archives.
day_archives true If we should build paginated day archives.
categories true If we should build paginated pages for each category.
main_feed true If we should build the main feeds based on your posts.
category_feeds true If we should build feeds of the posts in each site category.


The default templates for various page types.

Key Default Description
post post A single post.
category category Category pages.
paginated_post paginated_post The paginated posts pages.
archive archive The main archive pages.
date_archive date_archive The year, month and day archive pages.


Settings for all paginated pages.

Key Default Description
page_prefix page The prefix used when generating page URL slugs ("page2").
per_page 10 The number of posts to show per page. This applies to your feeds, too.

Date formats

These are used to define the auto-generated title for each type of archive page, and they're passed to Ruby's method for formatting dates.

Key Default Description
year %Y The year format.
month %Y-%m The month format.
day %Y-%m-%d The day format.

Feed formats

An array of feed formats your site supports - these will be matched by name to the templates within the templates/feeds/ directory, so atom will use templates/feeds/atom.(extension).

Category names

By default, Dimples will capitalise your category's slug as its title, but you can override that here:

  "category_names": {
    "bsd": "BSD",
    "mac": "Macintosh"


These options will be passed directly to the renderer Tilt picks for your posts, pages and templates based on the file extension.