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 source folder should contain the original, unoptimized assets for each post and page. For example, an image in the source folder should be the high-resolution jpeg file with no compression exported out of Lightroom/Photoshop. I believe the equivalent for text content is a combination of yaml for the post’s metadata and markdown for the post’s content.
• The destination folder should contain the optimized assets that are suitable for publication. For example, in the destination folder there should be multiple sizes of compressed jpegs for each high-resolution image in the source folder.
• 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 .yagss. These files will feature a yaml section followed by a markdown section, with -*-*- separating the two sections.
• The yaml section will contain metadata for the post/page like title, description, and social_image, 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.yaml file. Those values will be the default values that can be overridden by values in the yaml sections of individual posts/pages.
• If the page/post has any javascript, it should be specified by adding js to 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 content passed to the templating context. It uses smartypants rules to make quotation marks “smarter”. When used in templates, it should be used with dangerouslySetInnerHTML because 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 yagss-config.yaml file.
• All files in the source directory that don’t have the extensions yagss, js, jsx, or jpg will be copied unaltered to the destination directory.