Yagss (yet another generator for static sites) is a static site generator. That means it takes a folder full of files in formats that are (hopefully) easier to write and maintain than HTML, CSS, and JS and converts (transpiles) them into a folder full of HTML, CSS, and JS files that can be hosted on a web server, without the need for a dynamic back-end like WordPress, Django, or Rails.
A few design beliefs drive the feature set Yagss aims to provide.
- The build tool should be responsible for generating the entirety of the destination folder from a combination of the source folder, helper code, and the site configuration. In other words, the destination folder should be disposable.
Yagss makes a few assumptions about how the site’s source files are structured:
- Posts and pages will be saved in files with the extension
.md. These files will feature a yaml front-matter section followed by a markdown section, and optionally additional alternating front-matter and markdown sections.
- The yaml section will contain metadata for the post/page like
author, but you can add any key/value and it will be passed to the template, which is also specified in the yaml section.
- Metadata that is global to entire site can also be provided in the site’s
yagss-config.yamlfile. Those values will be the default values that can be overridden by values in the yaml sections of individual posts/pages.
jsto the yaml section, with the value being the name of the primary js file.
- That js file can make use of es6 imports, so it is assumed that there will be no more than one js file specified for the page/post.
- The markdown section will be transpiled to be the
contentpassed to the templating context. It uses smartypants rules to make quotation marks “smarter”. When used in templates, it should be used with
dangerouslySetInnerHTMLbecause it is already HTML.
- There will be one style document which will be global for the entire site. This will be generated by a scss file and files it imports that are located in their own directory outside of the main source directory.
- Jpeg files should be saved in the source directory in their full resolution. The build process will create scaled-down versions at the resolutions specified in the site’s
- All files in the source directory that don’t have the extensions
jpgwill be copied unaltered to the destination directory.
The easiest way to get started is to use the npx generator, create-yagss-site.
npx create-yagss-site my-new-site cd my-new-site npm install npm run start
siteUrl: The base url where this site will be hosted. Necessary for
canonicaland social sharing tags.
title: A default value for page title if none is provided
description: A default value for page description if none is provided
srcDir: location for site content pre-transpilation and pre-transcoding
destDir: location for converted site assets, used for local development and for deployment
templatesDir: location for “server-side” templates,
cacheDir: location for storing files to make site-building faster
scssFile: It is recommended to have a single file used for site-wide global styles.
imgSizes: array of integers for image widths jpg source files should be converted to