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
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
developer edits
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
- Default and Read the Docs style
- Search included
- 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!
Thank you!
The Best of Both Worlds: A Git-Based CMS for Static Sites
By Jessica Parsons
The Best of Both Worlds: A Git-Based CMS for Static Sites
API documentation is necessarily a collaboration between writers and developers, and merging the disparate workflows of these groups can be a challenge. With static site generators that build sites from Git-committed markdown code, text-editor-bound developers are starting to show interest in joining the party. On the other hand, technical writers still reach for a tool where they can focus on writing, where they don’t have to think about whether they need to have a space in their ## Heading to make it format properly, and where they don’t have to worry about esoteric Git commands. Netlify CMS helps bridge this gap, by providing a simple UI wrapper for Git functions, with a real-time markdown preview. All actions in Netlify CMS are translated to regular git commands on the repo, viewable and editable by traditional Git functionality as well as the editor UI.
