The Wistia Documentation (http://wistia.com/doc) is built on top of Jekyll. Jekyll is a ruby-based static site generator. woot.

If the doc was a living being, it would live in a cave. A sweet cave, but a cave all the same. Being short a cave, it lives here in this repo instead.

The Wistia Doc houses our app-specific notes and instructions on using Wistia.

We looked at a lot of documentation software, but it all felt very...impersonal. Like we wanted to get the doc out there as fast as we could, so we used this one-size-fits-all approach. That didn't feel super Wistia.

By using Jekyll, we got three sick benefits:

1. An easy way to intro new folks to using git/github/markdown.
2. A lightweight publishing process (Jekyll creates static files) that makes switching to a new platform later possible.
3. Complete control over the styles/javascript on the page.

The idea is writing docs should just be about the content. Styling/formatting should be done once, or using something simple (ie Markdown). If writing docs was more complicated, we'd never update them.

git clone
bundle install

If you don't have homebrew:

ruby <(curl -fsSk https://raw.github.com/mxcl/homebrew/go)

In a new window, run:

brew install elasticsearch
elasticsearch -f -D es.config=/usr/local/opt/elasticsearch/config/elasticsearch.yml

Go back to your old window and run

rake build

if you don't have node installed:

brew install node 

make sure this is in your .bashrc:

vim ~/.bashrc

add this line to the end of your .bashrc file

export NODE_PATH=/usr/local/lib/node_modules

install CoffeeScript:

npm install -g coffee-script

btw, wget is used to pull global Wistia header from wistiacom.

brew install wget

Update markdown files in _posts directory. Based on markdown syntax by John Gruber.

To add a new post, use:

rake np title=FOO

This will create post file with title slug and YAML block.

Images get uploaded to the Bakery - currently live in Project in home acct.

Images have their own Jekyll 'tag':

{% post_image hashed_id: *image hashed id* (string), width: *width* (integer), class: *classes* (string) %}

Videos are generated using an oEmbed plugin:

{% wistia_embed hashed_id: AAAAAAA, videoWidth: 660, videoHeight: 400 %}

defaults:

• playerColor: "688AAD" # $accent_blue from screen.sass
• width: "660"
• height: "413"
• videoWidth: "660"
• videoHeight: "413"
• playButton: true
• embedType: "seo"
• controlsVisibleOnLoad: false

For single line code, use the <code> block with class "full_width".

For inline code, just wrap in backticks.

For involved code blocks, use the codeblock plugin syntax.

Links also use a custom filter, so we can control the root path:

{{ '/link-to-page' | post_url }}

rake preview

• compile site,
• launch local server,
• and track changes to site/styling (localhost:9292)

Changes to posts, javascript, and sass will take effect dynamically (you'll still need to re-load, you slacker).

Note: Changes to layouts, includes, config files, and static pages (anything in HAML) need to be re-converted. Re-run rake preview to see updates.

Wistia Doc uses Sass and Compass. See more about Compass: http://compass-style.org/

Pretty much none, just:

git push origin master

If we update a post URL, or allow multiple URLs to point to a single document, restart Unicorn on the docbox in order for them to take effect.

sudo /etc/init.d/unicorn restart

Restart Elasticsearch

rc-status
/etc/init.d/elasticsearch stop
/etc/init.d/elasticsearch start

Want to chat? Weird, me too. You can email me, or reach me on twitter.