Rails Girls Guides

Rails Girls Guides is an open-source Jekyll template for publishing workshop guides and coaching materials that teach women how to build web applications with Ruby on Rails.

What is Rails Girls Guides?

Rails Girls Guides is a collection of tutorial documents stored in a GitHub repository and rendered as a static website at guides.railsgirls.com. It takes Markdown-authored guides and a custom Liquid tag for coach notes as input, and produces a browsable site of step-by-step instructions for organizing Rails Girls workshops. The project was founded by Karri Saarinen, Linda Liukas, Vesa Vänskä, and other contributors, and emerged from the first Rails Girls event in Helsinki in 2010.

Key Features

• Jekyll static site — Guides are written in Markdown and built into static HTML by Jekyll, so the site can be hosted on any static file server without a database.
• Pygments code highlighting — Code snippets inside guides are highlighted using the Pygments syntax highlighter, with a note that it must be installed for highlighting to appear.
• Coach note tag — A custom Liquid tag renders coach-specific guidance with consistent visual styling, so instructors know exactly what to explain.
• Keyboard shortcut conventions — Shortcuts are wrapped in kbd HTML tags to keep formatting consistent, with a style rule to use Ctrl+C over other variants.
• Local development workflow — bundle install followed by bundle exec jekyll server --watch gives a live preview server for editing guides locally.
• Contributing guide — The repository links to guides.railsgirls.com/contributing for anyone who wants to add or modify workshop material.
• CC BY-SA licensed — The entire content is released under Creative Commons Attribution-ShareAlike 3.0, allowing reuse with attribution.

Who is it for?

• Women new to coding — Participants who attend Rails Girls workshops and follow the tutorials to create a web app, gaining a first positive experience with building on the internet.
• Workshop organizers — People who want to run a Rails Girls event in their city, workplace, or even at home, using the ready-made curriculum and instructions to structure the day.
• Coaches and mentors — Developers who volunteer at events and rely on the embedded coach notes to know what underlying concepts to explain at each step.

What can you do with Rails Girls Guides?

• Self-learners: Walk through the published guides on your own schedule to practice Ruby on Rails fundamentals and deploy a small application.
• Event leaders: Clone the repository to fork the workshop material, adapt it to your local community, and host a free introductory web development workshop.
• Open source contributors: Improve existing guides or translate them by editing the Markdown files and opening pull requests, helped by the repository's hacktoberfest tag.

How does Rails Girls Guides work?

Organizers clone the repository and install dependencies using bundle install to get Jekyll set up. They write or edit Markdown guides, add coach sections using the custom Liquid tag, and rebuild the site with bundle exec jekyll server --watch to preview changes. The built static files can then be published to any hosting service, and the live version is publicly available at guides.railsgirls.com.

FAQ

Is Rails Girls Guides free?

Yes, the guides are open source under a Creative Commons Attribution-ShareAlike 3.0 license, so you can freely use, modify, and redistribute them as long as you credit the original work and share derivative works under the same license.

How do I run the guides locally?

Clone the repository, run bundle install to install Jekyll and its dependencies, then start a local server with bundle exec jekyll server --watch, which serves the site on your local machine.

Can I add coach notes to a guide?

Yes, the template includes a custom Liquid tag for coach notes. Wrap any explanatory text intended for instructors inside a coach block, and it will render with a consistent visual style across all guides.

What is the license for the guides?

The content is licensed under CC BY-SA 3.0, as shown by the license badge in the repository. This permits educational reuse with proper attribution and share-alike conditions.