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:
- Visit https://jekyll-sustained.netlify.com/
- Each person navigate to a different page on the site.
- Right click on the page, and select View page source (or use a different method)
- 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
request "cats.html"
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
request "cats.php"
get template
query database
fill content
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
(or database)
Static Site Generators
Automating in advance
Static Site Generators
Web pages are files again
request "cats.html"
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
Cons:
- ecosystem not as mature (yet), so can require more coding
Let's build a site!
Clicking this 👆 button will automatically:
- Connect your GitHub account to Netlify.
- Clone my sample repo to your GitHub account.
- 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
- 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
And so many more...
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