Static Site Generators for Documentation

Jessica Parsons

@verythorough

 

slides.com/verythorough/ssg-docs-mini

About Me

Documentation Engineer

Netlify
Girl Develop It

Instructor

Girl Develop It

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

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

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
Jekyll
  • 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
Sphinx
  • 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
Hugo
  • 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
Gatsby
  • 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...

Let's build a site!

Deploy to Netlify

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

Questions?

Find me on Twitter or in Slack
@verythorough

Thank you!

slides.com/verythorough/ssg-docs-mini

Mini-Workshop: Static Site Generators for Documentation

By Jessica Parsons

Mini-Workshop: Static Site Generators for Documentation

Static Site Generators have become increasingly popular for publishing documentation in a docs-as-code workflow, as evidenced by many projects and products like Docker, Kubernetes, React, MongoDB, Twitch, 1Password, and the U.S. Web Design System. In this mini-workshop, you’ll get an introduction to the static site generator landscape, and apply what you learn by publishing your own site in class. Presented at Write the Docs Australia 2018: https://youtu.be/2RCqk-nEn90

  • 891
Loading comments...

More from Jessica Parsons