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:
- An easy way to intro new folks to using git/github/markdown.
- A lightweight publishing process (Jekyll creates static files) that makes switching to a new platform later possible.
- 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 bundler installed:
gem install bundler
Go back to your old window and run
rake build
Make sure you have homebrew installed:
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
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 %}
defaults:
- playerColor: "688AAD" # $accent_blue from screen.sass
- width: "660"
- height: "413"
- videoWidth: "660"
- videoHeight: "413"
- playButton: true
- embedType: "standard"
- 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 }}
foreman start
- compile site,
- launch local server,
- and track changes to site/styling (localhost:3040/doc)
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.
This also means that if you make changes to HAML or SASS files, you'll need to commit both files -- the HAML and the HTML, the SASS and the CSS.
Did you find something tragically old in the docs? Yeah, me too. Here's how to delete that bad boy.
- Delete the markdown file locally, and remove any references to it in the site index. (on wistiacom)
- Try to set up a redirect -- if there is a better place to send people, DO THAT. Bug Emily if you want to set one up.
- After you've pushed changes to master and deployed, make sure that ish is gone by heading to the page. Hard refresh, friend--don't forget!
- if it isn't, purge the page in Fastly's cache from skycrank with
curl -X PURGE http://wistia.com/doc/thepageurl - last but not least, ask Google to remove it from the interwebs/search if there is no redirect.
Wistia Doc uses Sass and Compass. See more about Compass: http://compass-style.org/
Wistia-doc uses Swiftype search engine to crawl and index the Wistia Docs.
The Wistia Docs indexes and stats can be found in the wistia-doc engine on Swiftype. There, one can configure the
look & feel, search results, and other customizations.
To add search functionality to a page, simply add the .st-default-search-input class to an <input> tag and run the
Switype installer on the page:
<script>
(function(w,d,t,u,n,s,e){w['SwiftypeObject']=n;w[n]=w[n]||function(){
(w[n].q=w[n].q||[]).push(arguments);};s=d.createElement(t);
e=d.getElementsByTagName(t)[0];s.async=1;s.src=u;e.parentNode.insertBefore(s,e);
})(window,document,'script','//s.swiftypecdn.com/install/v2/st.js','_st');
_st('install','[KEY]','2.0.0');
</script>
Push code to github:
git push origin master
Want to chat? Weird, me too. You can email me, or reach me on twitter.