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

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

Weighing

the Options

Primary Considerations

• Preferred languages/tools of the site developer
• Ease of use
  • Availability/quality of docs
  • Language/template complexity
• Content features
  • built-in language features
  • versioning
  • internationalization
• Speed
  • to develop
  • to build
  • to load

• 10 years old! Lots of users, examples, content
• Built with Ruby
• Liquid templating: fairly easy to read
• Markdown content: well known, but limited
• Configuration and data files in yaml: easy to read, but whitespace sensitive
• Made for blogs, but can be used for docs and more
• Builds can be slow for large sites
• Runs out of the box in GitHub Pages (no plugins)
• Dedicated #jekyll channel in Write the Docs Slack

• 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
• Runs out of the box on Read the Docs
• Dedicated #sphinx channel in Write the Docs Slack

• Few years old; very active development
• Built with Go, but doesn't require Go to run (portability!)
• Go template language: steeper learning curve
• Content in Markdown, plus shortcodes
• General purpose, but docs themes exist
• 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
• Active support forum
• Dedicated #hugo channel in Write the Docs Slack

• Few years old; very active (venture-funded) development
• General purpose, but becoming popular for docs
• Built with JavaScript (React framework): very popular
• React component templating: steeper learning curve unless you're familiar with JavaScript/React
• Content in Markdown or mdx (powerful but JS-heavy)
• Static/SPA hybrid structure is fast to load
• Lots of plugins for customization (but still code-heavy)
• Discord server for community chat and support

• 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

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.

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 or in Slack
@verythorough

Thank you!

slides.com/verythorough/ssg-docs-mini