Static Site Generators for Documentation
Jessica Parsons
@verythorough
slides.com/verythorough/ssg-docs-mini
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488477/scroll.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488478/shield.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488476/scales.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488482/tools.jpg)
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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488477/scroll.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488477/scroll.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488477/scroll.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488477/scroll.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458490/cats-html-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458406/file-server.jpg)
Web pages as files
Simple Static Sites
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488460/cats-html.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458406/file-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488470/laptop.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488460/cats-html.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488483/website.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458490/cats-html-word.jpg)
request "cats.html"
Web pages as files
Simple Static Sites
- Pros: pretty fast & secure, very simple
- Cons: repetitive to build
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488460/cats-html.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488466/dogs-html.jpg)
Web pages as files
Simple Static Sites
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458490/cats-html-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5977965/dogs-html-word.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488474/pets-template.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458415/pets-php-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488465/db.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458404/database-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488457/app-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458417/plus.jpg)
Templates & Databases
Let the computer do the work
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488470/laptop.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488460/cats-html.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488483/website.jpg)
request "cats.php"
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458569/cats-php-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488457/app-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488474/pets-template.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488465/db.jpg)
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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488457/app-server.jpg)
Single-Page Apps (SPAs)
The browser as app server
- Pros: less time between pages
- Cons: slow first load; more work for client
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488457/app-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488470/laptop.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488468/gears.jpg)
Static Site Generators to the Rescue!
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488478/shield.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488478/shield.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488478/shield.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488478/shield.jpg)
Static Site Generators
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488474/pets-template.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458417/plus.jpg)
Automating in advance
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458413/pets-html-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488461/cats-md.jpg)
(or database)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488459/build-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5978115/cats-md-word.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488474/pets-template.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458413/pets-html-word.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488459/build-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458397/batch-md.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458396/batch-html.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458406/file-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458402/cdn.jpg)
Static Site Generators
Automating in advance
Static Site Generators
Web pages are files again
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458406/file-server.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488470/laptop.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488460/cats-html.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488483/website.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5458490/cats-html-word.jpg)
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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488476/scales.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488476/scales.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488476/scales.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488476/scales.jpg)
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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488481/thinking-face.jpg)
- 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...
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488481/thinking-face.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488481/thinking-face.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488481/thinking-face.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488481/thinking-face.jpg)
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.
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488482/tools.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488482/tools.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488482/tools.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488482/tools.jpg)
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
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488464/compass.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488475/question.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488475/question.jpg)
Thank you!
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488473/line-xl.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488472/line-s.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488479/star.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488479/star.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488681/star-flip.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/566016/images/5488681/star-flip.jpg)
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
- 3,452