ruby/www.ruby-lang.org

www.ruby-lang.org

This is the Jekyll source code for the official Ruby programming language website.

🚀 Quick Start

First time contributing? Welcome! This guide will help you get the website running locally in just a few steps.

Prerequisites

• Ruby (latest stable version recommended) - Install Ruby
• Node.js (for Tailwind CSS) - Install Node.js
• Git - Install Git

Get It Running

1. Install Bundler (if you haven't already):

   gem install bundler
   

2. Clone and setup the project:

   git clone https://github.com/ruby/www.ruby-lang.org.git
   cd www.ruby-lang.org/
   bundle config set --local without production
   bundle install
   npm install
   

3. Start the development server:

   bundle exec rake serve
   

4. View the website: Open http://localhost:4000/ in your browser

   ⏱️ Note: The initial build takes several minutes. Make some tea! 🍵

🤝 How to Contribute

Quick Fixes

• Found a typo? Just edit the Markdown file and submit a pull request!
• Broken link? Open an issue and we'll fix it quickly
• Translation error? Check our translation guidelines

Making Changes

1. Find the content: Website pages are in Markdown format in language-specific folders (e.g., en/, ja/, es/)
2. Create a branch: git checkout -b fix-typo-in-getting-started
3. Make your changes: Edit the Markdown files
4. Test as you go: Run bundle exec rake serve to preview your changes
5. Run the test suite: Before submitting, ensure all tests pass (see Testing section below)
6. Submit: Open a pull request with a clear description

New to open source? Check out First Contributions for a beginner-friendly guide.

🛠️ Development

Local Development

# Quick development server (faster rebuilds)
bundle exec jekyll serve --watch --future --incremental

# Full build (for testing)
bundle exec rake build

Testing Your Changes

Important: Always run the full test suite before submitting a pull request:

bundle exec rake lint          # Check markdown formatting
bundle exec rake check:markup  # Validate HTML output
bundle exec rake check:links   # Check for broken links (requires local server)

You can run these tests while developing to catch issues early.

🌐 Translations

This project supports multiple languages! Each language has its own folder:

• en/ - English (base language)
• ja/ - Japanese
• es/ - Spanish
• fr/ - French
• And many more...

Want to help translate? See our translation guide for detailed instructions.

📝 Content Guidelines

• Keep it simple: Write for a global audience of developers with varying English proficiency
• Be clear: Use straightforward language that's easy to understand
• Stay current: Update version numbers and examples regularly
• Test your changes: Always preview locally before submitting

🔧 Heroku Preview (Advanced)

If you can't build locally or want to test under production conditions:

1. Setup Heroku: Sign up at heroku.com and install Heroku CLI

2. Create preview app:

   heroku login
   heroku create --buildpack https://github.com/ruby/heroku-buildpack-www-ruby-lang.git
   

3. Deploy your branch:

   git push heroku your-branch-name:master
   heroku open
   

💬 Getting Help

• Questions? Join our Gitter chat
• Found a bug? Open an issue
• Need more info? Check the project wiki

Styling with Tailwind CSS

This site uses Tailwind CSS for styling. After making changes to HTML/Markdown files or Tailwind configuration:

npm run build-css   # build CSS
npm run watch-css   # watch and rebuild CSS automatically

Note: You need to have Node.js installed to run these commands.

Search

Search is Pagefind, which indexes the HTML Jekyll produced rather than the Markdown behind it, so it needs no server of its own. _plugins/search_index.rb runs it whenever Jekyll finishes writing the site, which means rake build and rake serve both leave you with a search index matching the site they just produced. Nothing extra to run.

Indexing adds a few seconds to a build and needs Node, so run npm install first. Without it bundle exec jekyll build still finishes and only reports that the index was skipped, which is enough for editing content. The rake tasks stop earlier than that, since they build the CSS with Tailwind first.

Pagefind builds one index per language and picks one by the lang attribute of the page the visitor is on, so each translation searches its own pages and reads its own interface labels. Bulgarian is the exception: Pagefind has neither word stemming nor interface translations for it, so search.unsupported in _config.yml keeps its pages out of the index and its search runs against English instead. Adding a language there is all it takes to do the same for another one.

Testing

Besides generating and previewing the site you can perform additional tests with these tasks:

bundle exec rake lint          # run linter on markdown files
bundle exec rake check:markup  # check markup for all generated pages
bundle exec rake check:links   # check for 404's (needs a running local server)

📚 More Information

For detailed contribution guidelines, coding standards, and project structure, see our wiki.

Thank you for helping make Ruby's website better for everyone! 🎉