Static Site Generators: A 2-hour Intro

Jessica Parsons

@verythorough

slides.com/verythorough/ssg-2hr

About Me

Documentation Engineer

Instructor

Local Co-organizer

What we'll cover

• How we got here
   
• How static site generators work, and why they're useful
   
• How to choose a site generator
   
• How to make your own generated site
   
• How to keep learning after today

But first, a warm-up

Pair with a classmate and introduce yourselves. Then do the following steps on both of your computers:

1. Visit https://jekyll-sustained.netlify.com/
2. Each person navigate to a different page on the site.
3. Right click on the page, and select View page source (or use a different method)
4. Compare the source code for your two pages. How are they the same? How are they different?

A Little History

Web pages as files

Simple Static Sites

Web pages as files

Simple Static Sites

• Pros: pretty fast & secure, very simple
• Cons: repetitive to build

Web pages as files

Simple Static Sites

Templates & Databases

Let the computer do the work

Templates & Databases

Let the computer do the work

• Pros: quicker to build and change
• Cons: slower, less secure, more complex

Templates & Databases

Let the computer do the work

Single-Page Apps (SPAs)

The browser as app server

• Pros: less time between pages
• Cons: slow first load; more work for client

Static Site Generators to the Rescue!

Static Site Generators

Automating in advance

Static Site Generators

Automating in advance

Static Site Generators

Web pages are files again

Static Site Generators

The best of both worlds

(in many cases)

Pros:

• fast, secure, scalable on CDN
• computer still does the repetitive work
• can add JavaScript for between-page loads

Let's build a site!

Clicking this 👆 button will automatically:

1. Connect your GitHub account to Netlify.
2. Clone my sample repo to your GitHub account.
3. Set your Netlify build settings and start building your site.

Weighing

the Options

Primary Considerations

• Familiarity of languages & tools used
• Availability/quality of docs & resources
• Features vs complexity
• Specialization (blogs, docs, etc.)
• Speed: to develop, build, load

• 10 years old! Lots of users, tutorials, themes
• Originally made for blogs, but used for more
• Built with Ruby: versions can be a hassle
• Liquid templating: fairly easy to read
• Markdown content
• Configuration and data files in yaml: easy to read, but whitespace sensitive
• Builds can be slow for large sites

• Even older than Jekyll (by a few months)
• Focused on docs: more niche (less content), but popular
• Built with Python: integrate with Python code comments
• Jinja templating: fairly similar to Liquid
• Content in reStructuredText: very powerful, less known
  (also supports Markdown)
• Built-in versioning
• Multiple output formats, including PDF, LaTeX, ePub

• Few years old; very active development
• Built with Go, but doesn't require Go to run
• Go template language: steeper learning curve
• Content in Markdown, plus shortcodes
• Flexible and extendable, but complex
• Docs are extensive, but can be hard to read
• Dynamic menus and tables of contents
• Reputation for very fast builds

• Few years old; venture-funded development
• Lots of docs and other help content
• Built with JavaScript (React): very popular
• React component templating: steeper learning curve unless you're familiar with JS/React
• Content in Markdown or mdx 
  (powerful but JS-heavy)
• Lots of plugins and themes (but still code-heavy)
• Static/SPA hybrid structure is fast to load

• Fairly new; built by Facebook
• Made for docs: simple built-in theme with menus, versioning, internationalization, and search
• Docs are short, but product is fairly simple
• Content in Markdown
• Also built with JavaScript/React, with same benefits and caveats as Gatsby
  • React component templating
  • Fast-loading static/SPA hybrid structure

Docusaurus

• Newest of all (< 1 yr)
• Made for docs: simple built-in theme with menus, versioning, internationalization, and search
• Built with Vue, another JavaScript framework that's gaining popularity
• Content in Markdown with docs-focused extensions, plus ability to use Vue in Markdown
• Built-in "last updated" functionality
• Similar benefits & challenges to other JS-based generators

VuePress

And so many more...

StaticGen.com

How to evaluate

• Browse the docs
• Search for tutorials and reviews
• Search for themes or starters
• Explore the files in a sample project
• Try it out!

More to Explore

• Clone your repository and build locally
• Try another Jekyll starter:
  • Skinny Bones (a fancier basic site)
  • Tom Johnson's Documentation Theme
• Try other generators!
• Manage content with a Headless CMS like Netlify CMS
• Watch a video about the evolution of the CMS

Questions?

Find me on Twitter
@verythorough

Thank you!

slides.com/verythorough/ssg-2hr