The Best of Both Worlds:

A Git-Based CMS for Static Sites

Jessica Parsons

slides.com/verythorough/best-of-both

About me

Traditional CMS Architecture

writer edits → CMS writes to DB

visitor arrives → query DB to build page

💖 Benefits

  • Powerful and feature-rich
  • Easy content editing
  • Widespread use

💔 Challenges

  • Server-bound
  • Heavy-handed
  • Separate workflow from dev

Static Site Generators

Replacing a Piece of the Puzzle

writer edits → CMS writes to DB

visitor arrives → query DB to build page

developer edits → pre-builds site as files

visitor arrives → request finished file

files

Taking the traditional CMS and...

Pre-built

  • Built in Ruby
    • Markdown for content
    • Yaml for config & post fields
    • Liquid for templating
  • Originally made for blogging
  • Community plugins and themes
  • Official SSG of GitHub Pages

So many more!

  • Similar to Jekyll, but built in Go
    • Markdown for content
    • YAML, TOML, or JSON  for config
    • Go native templating
  • Reputation for speed
  • Rising in popularity
  • Not as mature, but docs are improving
  • Several documentation themes:

Some are made just for docs

  • Built in Python
    • Content in ReStructuredText
    • Jinja templating
  • Variety of output formats, including LaTeX, ePub, and manual pages
  • Used by Read the Docs
  • Built in Python
    • Content in Markdown
    • Jinja templating
    • YAML config
  • Pre-templated built-in themes
  • Navigation in alpha order, or by config
  • Built in JavaScript (Node)
    • Content in Markdown or AsciiDoc
    • Output as website or ebook
    • Pre-templated, with search
  • Paid, hosted version available at www.gitbook.com
  • Open source "toolchain" repo on GitHub
  • Made for API documentation
  • Built in Ruby
    • Based on Middleman
    • Content in Markdown
    • Pre-templated
  • Check the wiki for more detailed docs

💖 Benefits

  • Free, high-quality hosting
  • Content separated from tools
  • Fits with dev workflow
  • If open source, visitors can fix typos :)

💔 Challenges

  • Not as full-featured
  • Content must be written in code

(yes, markdown counts as code)

Only one piece of the puzzle

files

Pre-built

Assembling the puzzle

files

Pre-built

Assembling the puzzle

files

Pre-built

Assembling the puzzle

files

Pre-built

Assembling the puzzle

files

Pre-built

The missing piece!

files

Pre-built

???

Several possibilities

Some are tool-specific

Jekyll Admin

Some are tool-specific

GitBook Editor

 

Some are tool-specific

Prose.io

Some are proprietary

Seeking a broader solution

  • Adaptable to multiple generators
  • Open source
  • Extensible & customizable
  • Creates a UI-wrapper for Git functions
    • Works with the GitHub API
  • Single-page app made with React.js
    • Can host with the site or separately
  • Extensible and customizable
    • Create custom widgets and styled previews
  • Open source
    • Enthusiastic and growing community
  • Requires GitHub API
    • Can be public, private, or self-hosted
  • Works with some generators better than others
  • Authentication without Netlify is undocumented
    • Actually, a lot is still undocumented!

Caveats, for now

Let's continue the conversation!

slides.com/verythorough/post-monolithic-cms

 

@verythorough

(on Twitter, Slack, GitHub, etc.)

Thank you!