Static Site Generators for Documentation
Jessica Parsons
@verythorough
slides.com/verythorough/ssg-docs-mini
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
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
- 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
- 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!
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.
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
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
