Yagss

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. Javascript in the source folder should be es6, or anything babel can understand.
• 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 text content in the destination folder should be html with escaped entities and smart punctuation. The javascript in the destination folder should be ES5 that can work in all major browsers.
• 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 title, description, and 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.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 md, js, jsx, or jpg will be copied unaltered to the destination directory.

Quickstart

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

Configuration options

• siteUrl: The base url where this site will be hosted. Necessary for meta tags like canonical and 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