Presumably if you are here it is because you want to contribute to our blog. Thank you. Here are some helpful instructions for making that process easy.
- Clone the repo
- Install bundler if you don't already have it:
gem install bundler - Install the required gems, using bundler:
bundle install - Start up Jekyll in "watch" mode:
bundle exec jekyll serve --watch --drafts - Load up the site locally:
open http://localhost:4000
The Jekyll content lives in the working branch, while the published content
lives in the master branch. The default branch when you clone is the
working branch, and you should never have a need to switch to master unless
you are a blog owner. We have organized our branches in this non-standard way
so that we can be in full control of the content that is published. If we just
committed posts to master, then the standard GitHub Pages workflow would
use Jekyll to convert them to publishable content. In that case, we are
restricted by what GitHub has decided is safe for them to run.
The workflow for submitting a post goes like this:
- Fork the repo on github.com:
open https://github.com/opower/opower.github.io/fork - Add the fork to your local repo:
git remote add <remote-name> <fork-url> - Make sure you are on the
workingbranch:git checkout working - Update your local repo:
git pull origin - Fetch your fork, too:
git pull <remote-name> - Create a branch for your post:
git checkout -b <post-slug> - Write your new post as a draft:
vim _drafts/<date>-<post-slug>.markdown - Run Jekyll to check the content looks good:
bundle exec jekyll serve --watch --drafts - Commit your draft:
git commit _drafts/<date>-<post-slug>.md - Push your draft to your fork:
git push <remote-name> <post-slug> - Open a pull request against
origin/workingon github.com
One of the blog owners will work with you to finalize the post and will publish it.
Posts should follow these standards:
- Written in Markdown using kramdown's syntax extensions
- End with a
.markdownextension - Include at least the following in the YAML Front Matter:
layout: posttitle: <The post title>author: <first.last>
- Wrap at 80 characters
- Use the
{% highlight %}tag around code blocks, preferably specifying the language - Link to images or assets from the root URL:
To help with some of the formating, for the vim users, we suggest using the
vim-markdown plugin from Tim Pope, in conjunction with Tim's
vim-pathogen plugin. Additionally, be sure to set set textwidth=80
for Markdown files to have vim wrap automatically for you.