
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
Get It Running
-
Install Bundler (if you haven't already):
-
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
-
Start the development server:
-
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
- Find the content: Website pages are in Markdown format in language-specific folders (e.g.,
en/, ja/, es/)
- Create a branch:
git checkout -b fix-typo-in-getting-started
- Make your changes: Edit the Markdown files
- Test as you go: Run
bundle exec rake serve to preview your changes
- Run the test suite: Before submitting, ensure all tests pass (see Testing section below)
- 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:
-
Setup Heroku: Sign up at heroku.com and install Heroku CLI
-
Create preview app:
heroku login
heroku create --buildpack https://github.com/ruby/heroku-buildpack-www-ruby-lang.git
-
Deploy your branch:
git push heroku your-branch-name:master
heroku open
๐ฌ Getting Help
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! ๐