Contributing to the Dev Center

Contributing to the Dev Center

Iron.io's Dev Center is built on top of Github Pages for a reason: we want to encourage the community to point out flaws in our documentation and even suggest fixes, through pull requests.

We've created this document as a guide for our own team when editing and adding to the Dev Center, but it should be useful for members of our community who would like to contribute as well.

The Git Flow

Our Dev Center is built, maintained, and published in a Git repository. A sample workflow would look something like this:

• Fork the repository if you don't have write access.
• Create a new branch, giving it a descriptive name: git branch adding-foo-page. Each change should be a new branch off of the gh-pages branch.
• Checkout your branch: git checkout adding-foo-page.
• Modify the files you want to change.
• Commit the changes to your branch:

git add .
git commit -m "Added foo page because X Y Z."

• Push the changes to a remote branch named after your local branch: git push origin adding-foo-page.
• Use the Github interface to send a pull request

Once your pull request is received and reviewed, it will be commented on or merged. Once merged into the gh-pages branch, it will be live on http://dev.iron.io.

Conventions

The Dev Center is built on Jekyll. Rather than a bunch of code, the Dev Center relies on conventions to create content appropriately. The following conventions should be followed:

• Articles should be placed in the _posts directory, with a name like DATE-PRODUCT-CATEGORY-title.md, where DATE is YYYY-MM-DD, PRODUCT is either worker or mq, CATEGORY is the article's category, and title is the slug of the article's title (lowercase, hyphens replacing spaces).
• Content should define the following variables in their frontmatter:
  • title: the title of the content
  • layout: default. Always default.
  • section: the section the content belongs in. Usually worker or mq, depending on the product.
  • permalink: the full path to the content, not including dev.iron.io. E.g., "/worker/articles/data/local-storage"
  • breadcrumbs: the breadcrumbs for the content, in the order they should appear. Omit the product. Each breadcrumb is an array of two parts. The first is the URL slug of that part (leading /, no trailing /), the second is the name of that part. E.g., /worker/articles becomes ['Articles', '/articles'], as the product (worker) is omitted.
  • categories: the categories the content belongs to. Articles should include the product (worker or mq) and articles, at the very least. Should also belong to one of the predefined categories. Other content should include the product, at the very least.
• Non-article content should be placed at the path you want to access it at. Create directories as necessary to recreate the URL structure, creating a final directory for the content's slug. Save the content as index.html or index.md (depending on the markup language used). E.g., content that belongs in /worker/reference/foo would be mean creating a /worker/reference/foo/index.md file. Note: Do not do this for articles. Put those in _posts.
• The language switcher is built in. To use it, there are three steps:
  1. Define the languages you wish to include in the switcher. Do this by setting the languages frontmatter. The languages frontmatter is a YAML array of objects, each containing three properties:
     • name: the name of the language. E.g., Python, Ruby, Go.
     • command: the command to run a script in the language. E.g., python, ruby, go run.
     • extension: the file extension for files written in the language. E.g., py, rb, go.
  2. Include the language-switcher.html include where you want the language switcher. Can be in more than one place.
  3. Wrap the language-specific sections. The sections should be wrapped in <div> elements with a class of the language name. E.g., <div class="python">, <div class="ruby">, <div class="go">, etc.