socrata / dev.socrata.com

Socrata Developer Site

This is the Github Pages source code for the Socrata Developer Portal (currently deployed to http://dev.socrata.com.

Contributing

We love pull requests! If you'd like to contribute, feel free to fork this repo and send us pull requests.

Setting Up

The site is a customized Jekyll site, so there are some steps you'll need to take care of to get your environment set up:

1. Make sure you have the gh-pages branch checked out: git checkout -b gh-pages origin/gh-pages
2. Pull in the site templates and CSS/SASS, which come from submodules: git submodule update --init
3. Make sure you have Ruby version installed. Check .ruby-version to see the preferred version. If you're using rbenv or rvm, this should automatically be set up.
4. Install the Bundler Gem installed: gem install bundler
5. Set up the Gem bundle: bundle
6. To run a local server for development, run rake serve. Your server will be available at http://localhost:9292

If things seem to be going wrong (styles aren't generating, blog post isn't showing up on the blog index page), try doing rake clean and then rake serve again.

Submitting a Blog Post

We love submissions from the community! If you'd like to submit a blog post about something you've built with the Socrata APIs, about open data technology, or something we might just be interested in, craft your blog post as a pull request and submit it for review:

1. Review other posts and submissions to get a feel for the tone and language, and to see how others have formatted their posts.
2. Fork this repo into your account
3. Create a new blog post running rake blog and following the prompts
4. Write your post in Markdown, following a few rules:

• Set the author key in the YAML front matter to your GitHub username so you get proper author credit
• If your post uses any images, add them to the img folder, prepended with your post date
• Proof your post either using the instructions above to build and view the site, or using a Markdown preview tool like Marked or the one provided by GitHub.
• (Optional) Use MathJax to provide TeX formatting for formulas. We use \\( as the starting delimiter and \\) as the ending delimiter.

5. Submit your post and any required files as a pull request against the gh-pages branch.

We'll review your post for content and acceptability. If there are any problems, we'll either fix them or let you know why we can't accept your post.

Please note that by submitting a post to the Socrata Developer Blog, you are are granting us an irrevocable license to distribute your work on dev.socrata.com or other mediums we choose. It will be covered by the same Creative Commons license as the rest of the content of dev.socrata.com.

Before Submitting

Before submitting, please run rake test to run the test suite and confirm that you haven't broken anything. You may need to install phantomjs to run the test suite: npm install -g phantomjs

Continuous integration tests will be run when you submit a pull request, so this will save time if issues later crop up.

Modifying CSS/SASS

Site styling is controlled via css/local.sass and it's automatically regenerated by Github Pages with each push.