Static School

Static School is an open-source project with the goal of making it easier to discover, research, and (ultimately) choose a static site generator (SSG) for your next project. We try to provide in-depth analysis for all SSGs we cover, including data (updated daily) on activity, popularity, and performance.

Site Structure

Static School is built with Hugo and deployed daily with Netlify.

├── LICENSE
├── README.md
├── bench <Files related to data collection and benchmarking>
├── config.toml
├── content
│  └── ssg/ <Individual pages for each SSG>
├── data
│  └── report.json <An auto-generated, JSON-formatted report of all our data>
├── layouts
├── resources

Benchmarking

Dependecies: To run the benchmark suite, you'll need Python 3.7+ and Docker installed.

Each static site generator is tested against three size increments 10, 100, and 1,000 files. The files are copied from a corpus of approximately-equivalent files for AsciiDoc, Markdown, and reStructuredText.

The following commands will build and run the benchmark suite:

$ cd bench
$ make build
$ make bench ssg=<NAME OF SSG TO TEST>

The actual benchmarking is handled by the hyperfine command-line tool, which handles warmup runs, statistical outlier detection, and results formatting.

Contributing

If you'd like to submit a new static generator to our test suite, please follow these steps:

1. Create a new directory in /bench/generators/ that includes sample_site/, Dockerfile, and meta.yml.

   example_site/ is a functional example of the given static site generator—it's the template that will be used for all performance testing. When committed to this repo, though, its content directory should be empty.

   Dockerfile should contain all required steps to build example_site/ while adhering to the following structure:

   # Required:
   FROM jdkato/hyperfine
   
   # Custom steps:
   ARG repo="@testing http://dl-3.alpinelinux.org/alpine/edge/testing"
   
   RUN echo $repo >> /etc/apk/repositories && \
   apk add --no-cache --update zola@testing
   
   # Required:
   COPY meta.yml /meta.yml
   COPY example_site /example_site
   
   # Required:
   ENTRYPOINT ["python3", "/bench.py"]

   meta.yml acts as a means of standardization across multiple static site generators:

   # All supported formats from 'md', 'adoc', and 'rst':
   formats:
    - md
   
   # The CLI commands to (1) build the site and (2) obtain the tool's version:
   commands:
    build: 'cd {dir} && zola build && cd ..'
    version: zola --version
   
   # Any required front matter. This will be added to all test files.
   layout: |
    +++
    title = "Benchmark"
    +++
   
    {content}
   
   # The file naming scheme to use for test files:
   filename: test{0}
   
   # The location, relative to `/example_site`, to copy test markup files:
   content: content

2. Create a new directory in /content/ssg that includes logo.png (project logo), preview.png (website screenshot), and index.md (project description and metadata).

   index.md should define the following front matter variables (the example below is for Gatsby):

   title: Gatsby
   homepage: https://www.gatsbyjs.org/
   
   description: Build blazing fast, modern apps and websites with React.
   
   language:
     name: JavaScript
     link: https://nodejs.org/en/
     icon: devicon-javascript-plain colored
   
   templating:
     name: React
     link: https://reactjs.org/
   
   features:
     localization:
       type: plugin
       link: https://www.gatsbyjs.org/docs/localization-i18n/
     versioning: false
     custom_output:
       type: plugin
       link: https://github.com/dominicfallows/gatsby-plugin-json-output
     asset_pipelines:
       type: plugin
       link: https://www.gatsbyjs.org/packages/gatsby-plugin-minify/
     data_files:
       link: https://www.gatsbyjs.org/docs/recipes/sourcing-data
     image_processing:
       link: https://www.gatsbyjs.org/docs/gatsby-image/
     extensible:
       link: https://www.gatsbyjs.org/docs/creating-plugins/
   
   license:
     name: MIT
     slug: mit
   
   adoc: true
   md: true
   rst: false
   
   twitter: gatsbyjs
   repo: gatsbyjs/gatsby

Credits

This project was inspired by Netlify's MIT-licensed StaticGen website. The major difference is that Static School is much more than a "leaderboard": we provide in-depth benchmarking, guides, and tutorials.