Gingersnap is a static site generator built in Go.
Clone the repo
git clone https://github.com/tunedmystic/gingersnap && cd gingersnapBuild and install the app binary
make installCheck out the demo site, built with Gingersnap.
Gingersnap is a static site generator built in Go. It converts markdown files into a fully functional website.
With a single command, users can setup an entire project, allowing them to jump straight into editing and content creation.
Projects have a limited set of features and configuration. This helps keep the blogging workflow streamlined and ensures a more straightforward experience for users.
Table of Contents
First, create an empty directory and navigate to it.
mkdir mysite && cd mysiteNext, use gingersnap to initialize a project. A starter project will be scaffolded, complete with blog posts and media assets.
gingersnap initThen, use gingersnap to start a development server on localhost:4000.
You can add/edit content, and the server will restart to reflect the changes.
gingersnap devFinally, use gingersnap to export the project as a static site.
The site will be exported to the dist/ directory.
gingersnap exportA gingersnap project contains the following directory structure:
├─ posts/
├─ media/
├─ gingersnap.json
Posts - The posts directory contains all the site content as markdown files. Gingersnap uses the metadata within each markdown file to determine the post's title, slug, category etc.
Media - The media directory contains all media assets that are used in the posts. These assets can be images, audio, video, etc.
Config - The config file stores settings and layout configurations for the site. More details about the config file below.
The gingersnap.json config file stores settings and layout configurations for the site. Here is an overview of the config options.
Defines site-specific settings.
name |
The name of the site |
host |
The host of the site |
tagline |
A short description of the site (50-70 characters) |
description |
A long description of the site (70-155 characters) |
theme |
The color theme of the site (see available themes) |
display |
Render the posts in "grid" or "list" style |
"site": {
"name": "MySite",
"host": "mysite.com",
"tagline": "short descr ...",
"description": "longer descr ...",
"theme": "pink",
"display": "grid"
}Defines sections for the homepage. This (optional) setting requires a list of categories.
The "$latest" tag is a custom section that represents all latest posts.
The "$featured" tag is a custom section which represents all featured posts.
Gingersnap will then build the homepage based on this given list.
"homepage": ["category-slug", "$latest"]Defines anchor links for the top navbar. This (optional) setting requires a list of anchor link objects.
| Text | The anchor link text |
| Href | The anchor link href |
"navbarLinks": [
{"text": "About Us", "href": "/about/"},
{"text": "My Article", "href": "/abc/"}
]Defines anchor links for the footer. This (optional) setting requires a list of anchor link objects.
| Text | The anchor link text |
| Href | The anchor link href |
"footerLinks": [
{"text": "About Us", "href": "/about/"},
{"text": "My Article", "href": "/abc/"}
]Defines the export destination. This (optional) setting requires a repository path where the site will be exported to.
"repository": "/path/to/static/repo"{
"site": {
"name": "Gingersnap",
"host": "gingersnap.dev",
"tagline": "The Snappy Way to Build Static Sites.",
"description": "Gingersnap is a simple and effortless static site generator. Get up and running with one command, and export the site when you're ready to publish!",
"theme": "pink",
"display": "grid"
},
"homepage": [
"$featured",
"go",
"$latest"
],
"navbarLinks": [
{"text": "Go", "href": "/category/go/"},
{"text": "Python", "href": "/category/python/"},
{"text": "SQL", "href": "/category/sql/"},
{"text": "About Us", "href": "/about/"}
],
"footerLinks": [
{"text": "Home", "href": "/"},
{"text": "About Us", "href": "/about/"},
{"text": "Sitemap", "href": "/sitemap/"},
{"text": "Privacy Policy", "href": "/privacy-policy/"}
],
"repository": "/path/to/static/repo"
}The site.display setting will tell Gingersnap to render Post blocks as a list or as a grid. Post blocks are used in the homepage, in category pages, and in post detail pages.
Here is an example of how these two displays are rendered.
Here are some tips for working with Gingersnap projects.
Any post marked as draft will never be processed or exported by Gingersnap. You can make a post draft by adding draft: true in the markdown front matter.
Featured posts are pinned posts that Gingersnap displays on the homepage.
You can make a post featured by adding featured: true in the markdown front matter.
You can display featured posts on the homepage by adding the "$featured" section to the homepage settings.
A standalone post has no relation to other content across the site. Examples of standalone posts are a "contact" page, an "about" page, or a "privacy-policy" page.
When Gingersnap displays a standalone post, it will not include related or latest posts on the page. A standalone post does not need the following front matter fields: category, image_url, pubdate or updated.
You can make a post standalone by adding page: true to the markdown front matter.
Each post must contain a lead image. You can set the lead in the markdown front matter with the image_url and image_alt fields.
To keep things simple, all lead images must be in webp format and must have a resolution of 1280x720.
Gingersnap will display the lead image in the post detail page. Alternatively, you can hide the lead image in the post detail page with hide_image: true.
Gingersnap comes with the following color themes, each with a primary (left) and secondary (right) color. The primary color is applied to the site header and the category links. The secondary color is applied to all heading tags, except h1.
You can also simplify the themes by adding "-simple" to the theme name in the gingersnap.json file.
{
"theme": "pink-simple"
}When you specify a simple theme, Gingersnap will use the primary color of the root theme, and will use black as the secondary color.
And that's it! Have fun building sites with Gingersnap! 🍪 ❤️