<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v3.8.3">
<link type="application/atom+xml" rel="alternate" href="https://jekyllrb.com/feed.xml" title="Jekyll • Simple, blog-aware, static sites">
<link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="https://github.com/jekyll/jekyll/commits/master.atom">
<link rel="preconnect" href="https://fonts.gstatic.com/" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css">
<link rel="stylesheet" href="/css/screen.css">
<link rel="icon" type="image/x-icon" href="/favicon.ico">
<!-- Begin Jekyll SEO tag v2.4.0 -->
<title>Contributing | Jekyll • Simple, blog-aware, static sites</title>
<meta name="generator" content="Jekyll v3.8.3">
<meta property="og:title" content="Contributing">
<meta property="og:locale" content="en_US">
<meta name="description" content="Hi there! Interested in contributing to Jekyll? We’d love your help. Jekyll is an open source project, built one contribution at a time by users like you.">
<meta property="og:description" content="Hi there! Interested in contributing to Jekyll? We’d love your help. Jekyll is an open source project, built one contribution at a time by users like you.">
<link rel="canonical" href="https://jekyllrb.com/docs/contributing/">
<meta property="og:url" content="https://jekyllrb.com/docs/contributing/">
<meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
<meta property="og:type" content="article">
<meta property="article:published_time" content="2018-06-08T11:29:03-07:00">
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@jekyllrb">
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
<script type="application/ld+json">
{"description":"Hi there! Interested in contributing to Jekyll? We’d love your help. Jekyll is an open source project, built one contribution at a time by users like you.","@type":"BlogPosting","url":"https://jekyllrb.com/docs/contributing/","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://jekyllrb.com/img/logo-2x.png"}},"headline":"Contributing","dateModified":"2018-06-08T11:29:03-07:00","datePublished":"2018-06-08T11:29:03-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/contributing/"},"@context":"http://schema.org"}</script>
<!-- End Jekyll SEO tag -->
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
<![endif]-->
</head>
<body class="wrap">
<header>
<div class="flexbox">
<div class="center-on-mobiles">
<h1>
<a href="/" class="logo">
<span class="sr-only">Jekyll</span>
<img src="/img/logo-2x.png" width="140" height="65" alt="Jekyll Logo">
</a>
</h1>
</div>
<nav class="main-nav hide-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/home/">Docs</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
</ul>
</nav>
<div class="search hide-on-mobiles">
<input type="text" id="docsearch-input" placeholder="Search the docs…">
</div>
<div class="meta hide-on-mobiles">
<ul>
<li>
<a href="https://github.com/jekyll/jekyll/releases/tag/v3.8.3">v3.8.3</a>
</li>
<li>
<a href="https://github.com/jekyll/jekyll">GitHub</a>
</li>
</ul>
</div>
</div>
<nav class="mobile-nav show-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/home/">Docs</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
<li>
<a href="https://github.com/jekyll/jekyll">GitHub</a>
</li>
</ul>
</nav>
</header>
<section class="docs">
<div class="grid">
<div class="docs-nav-mobile unit whole show-on-mobiles">
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="Getting Started">
<option value="/docs/home/">Welcome</option>
<option value="/docs/quickstart/">Quick-start guide</option>
<option value="/docs/installation/">Installation</option>
<option value="/docs/windows/">Jekyll on Windows</option>
<option value="/docs/usage/">Basic Usage</option>
<option value="/docs/structure/">Directory structure</option>
<option value="/docs/configuration/">Configuration</option>
</optgroup>
<optgroup label="Your Content">
<option value="/docs/frontmatter/">Front Matter</option>
<option value="/docs/posts/">Writing posts</option>
<option value="/docs/drafts/">Working with drafts</option>
<option value="/docs/pages/">Creating pages</option>
<option value="/docs/static-files/">Static Files</option>
<option value="/docs/variables/">Variables</option>
<option value="/docs/collections/">Collections</option>
<option value="/docs/datafiles/">Data Files</option>
<option value="/docs/assets/">Assets</option>
<option value="/docs/migrations/">Blog migrations</option>
</optgroup>
<optgroup label="Customization">
<option value="/docs/templates/">Templates</option>
<option value="/docs/includes/">Includes</option>
<option value="/docs/permalinks/">Permalinks</option>
<option value="/docs/pagination/">Pagination</option>
<option value="/docs/plugins/">Plugins</option>
<option value="/docs/themes/">Themes</option>
<option value="/docs/extras/">Extras</option>
</optgroup>
<optgroup label="Deployment">
<option value="/docs/github-pages/">GitHub Pages</option>
<option value="/docs/deployment-methods/">Deployment methods</option>
<option value="/docs/continuous-integration/">Continuous Integration</option>
</optgroup>
<optgroup label="Miscellaneous">
<option value="/docs/troubleshooting/">Troubleshooting</option>
<option value="/docs/sites/">Sites using Jekyll</option>
<option value="/docs/resources/">Resources</option>
<option value="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</option>
<option value="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</option>
</optgroup>
<optgroup label="Meta">
<option value="/docs/contributing/">Contributing</option>
<option value="/docs/maintaining/">Maintaining Jekyll</option>
<option value="/docs/conduct/">Code of Conduct</option>
<option value="/docs/history/">History</option>
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<div class="improve right hide-on-mobiles">
<a href="https://github.com/jekyll/jekyll/edit/master/docs/_docs/contributing.md"><i class="fa fa-pencil"></i> Improve this page</a>
</div>
<h1>Contributing</h1>
<p>Hi there! Interested in contributing to Jekyll? We’d love your help. Jekyll is an open source project, built one contribution at a time by users like you.</p>
<h2 id="where-to-get-help-or-report-a-problem">Where to get help or report a problem</h2>
<p>See <a href="https://jekyllrb.com/docs/support/">the support guidelines</a></p>
<h2 id="ways-to-contribute">Ways to contribute</h2>
<p>Whether you’re a developer, a designer, or just a Jekyll devotee, there are lots of ways to contribute. Here’s a few ideas:</p>
<ul>
<li>
<a href="https://jekyllrb.com/docs/installation/">Install Jekyll on your computer</a> and kick the tires. Does it work? Does it do what you’d expect? If not, <a href="https://github.com/jekyll/jekyll/issues/new">open an issue</a> and let us know.</li>
<li>Comment on some of the project’s <a href="https://github.com/jekyll/jekyll/issues">open issues</a>. Have you experienced the same problem? Know a work around? Do you have a suggestion for how the feature could be better?</li>
<li>Read through <a href="https://jekyllrb.com/docs/home/">the documentation</a>, and click the “improve this page” button, any time you see something confusing, or have a suggestion for something that could be improved.</li>
<li>Browse through <a href="https://talk.jekyllrb.com/">the Jekyll discussion forum</a>, and lend a hand answering questions. There’s a good chance you’ve already experienced what another user is experiencing.</li>
<li>Find <a href="https://github.com/jekyll/jekyll/issues">an open issue</a> (especially <a href="https://github.com/jekyll/jekyll/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted">those labeled <code class="highlighter-rouge">help-wanted</code></a>), and submit a proposed fix. If it’s your first pull request, we promise we won’t bite, and are glad to answer any questions.</li>
<li>Help evaluate <a href="https://github.com/jekyll/jekyll/pulls">open pull requests</a>, by testing the changes locally and reviewing what’s proposed.</li>
</ul>
<h2 id="submitting-a-pull-request">Submitting a pull request</h2>
<h3 id="pull-requests-generally">Pull requests generally</h3>
<ul>
<li>
<p>The smaller the proposed change, the better. If you’d like to propose two unrelated changes, submit two pull requests.</p>
</li>
<li>
<p>The more information, the better. Make judicious use of the pull request body. Describe what changes were made, why you made them, and what impact they will have for users.</p>
</li>
<li>
<p>Pull requests are easy and fun. If this is your first pull request, it may help to <a href="https://guides.github.com/introduction/flow/">understand GitHub Flow</a>.</p>
</li>
<li>
<p>If you’re submitting a code contribution, be sure to read the <a href="#code-contributions">code contributions</a> section below.</p>
</li>
</ul>
<h3 id="submitting-a-pull-request-via-githubcom">Submitting a pull request via github.com</h3>
<p>Many small changes can be made entirely through the github.com web interface.</p>
<ol>
<li>Navigate to the file within <a href="https://github.com/jekyll/jekyll"><code class="highlighter-rouge">jekyll/jekyll</code></a> that you’d like to edit.</li>
<li>Click the pencil icon in the top right corner to edit the file</li>
<li>Make your proposed changes</li>
<li>Click “Propose file change”</li>
<li>Click “Create pull request”</li>
<li>Add a descriptive title and detailed description for your proposed change. The more information the better.</li>
<li>Click “Create pull request”</li>
</ol>
<p>That’s it! You’ll be automatically subscribed to receive updates as others review your proposed change and provide feedback.</p>
<h3 id="submitting-a-pull-request-via-git-command-line">Submitting a pull request via Git command line</h3>
<ol>
<li>Fork the project by clicking “Fork” in the top right corner of <a href="https://github.com/jekyll/jekyll"><code class="highlighter-rouge">jekyll/jekyll</code></a>.</li>
<li>Clone the repository locally <code class="highlighter-rouge">git clone https://github.com/<you-username>/jekyll</code>.</li>
<li>Create a new, descriptively named branch to contain your change ( <code class="highlighter-rouge">git checkout -b my-awesome-feature</code> ).</li>
<li>Hack away, add tests. Not necessarily in that order.</li>
<li>Make sure everything still passes by running <code class="highlighter-rouge">script/cibuild</code> (see <a href="#running-tests-locally">the tests section</a> below)</li>
<li>Push the branch up ( <code class="highlighter-rouge">git push origin my-awesome-feature</code> ).</li>
<li>Create a pull request by visiting <code class="highlighter-rouge">https://github.com/<your-username>/jekyll</code> and following the instructions at the top of the screen.</li>
</ol>
<h2 id="proposing-updates-to-the-documentation">Proposing updates to the documentation</h2>
<p>We want the Jekyll documentation to be the best it can be. We’ve open-sourced our docs and we welcome any pull requests if you find it lacking.</p>
<h3 id="how-to-submit-changes">How to submit changes</h3>
<p>You can find the documentation for jekyllrb.com in the <a href="https://github.com/jekyll/jekyll/tree/master/docs">docs</a> directory. See the section above, <a href="#submitting-a-pull-request">submitting a pull request</a> for information on how to propose a change.</p>
<p>One gotcha, all pull requests should be directed at the <code class="highlighter-rouge">master</code> branch (the default branch).</p>
<h3 id="updating-fontawesome-iconset-for-jekyllrbcom">Updating FontAwesome iconset for jekyllrb.com</h3>
<p>We use a custom version of FontAwesome which contains just the icons we use.</p>
<p>If you ever need to update our documentation with an icon that is not already available in our custom iconset, you’ll have to regenerate the iconset using Icomoon’s Generator:</p>
<ol>
<li>Go to <a href="https://icomoon.io/app/">https://icomoon.io/app/</a>.</li>
<li>Click <code class="highlighter-rouge">Import Icons</code> on the top-horizontal-bar and upload the existing <code class="highlighter-rouge"><jekyll>/docs/icomoon-selection.json</code>.</li>
<li>Click <code class="highlighter-rouge">Add Icons from Library..</code> further down on the page, and add ‘Font Awesome’.</li>
<li>Select the required icon(s) from the Library (make sure its the ‘FontAwesome’ library instead of ‘IcoMoon-Free’ library).</li>
<li>Click <code class="highlighter-rouge">Generate Font</code> on the bottom-horizontal-bar.</li>
<li>Inspect the included icons and proceed by clicking <code class="highlighter-rouge">Download</code>.</li>
<li>Extract the font files and adapt the CSS to the paths we use in Jekyll:
<ul>
<li>Copy the entire <code class="highlighter-rouge">fonts</code> directory over and overwrite existing ones at <code class="highlighter-rouge"><jekyll>/docs/</code>.</li>
<li>Copy the contents of <code class="highlighter-rouge">selection.json</code> and overwrite existing content inside <code class="highlighter-rouge"><jekyll>/docs/icomoon-selection.json</code>.</li>
<li>Copy the entire <code class="highlighter-rouge">@font-face {}</code> declaration and only the <strong>new-icon(s)’ css declarations</strong> further below, to update the
<code class="highlighter-rouge"><jekyll>/docs/_sass/_font-awesome.scss</code> sass partial.</li>
<li>Fix paths in the <code class="highlighter-rouge">@font-face {}</code> declaration by adding <code class="highlighter-rouge">../</code> before <code class="highlighter-rouge">fonts/FontAwesome.*</code> like so:
<code class="highlighter-rouge">('../fonts/Fontawesome.woff?9h6hxj')</code>.</li>
</ul>
</li>
</ol>
<h3 id="adding-plugins">Adding plugins</h3>
<p>If you want to add your plugin to the <a href="https://jekyllrb.com/docs/plugins/#available-plugins">list of plugins</a>, please submit a pull request modifying the <a href="https://github.com/jekyll/jekyll/blob/master/docs/_docs/plugins.md">plugins page source file</a> by adding a link to your plugin under the proper subheading depending upon its type.</p>
<h2 id="code-contributions">Code Contributions</h2>
<p>Interesting in submitting a pull request? Awesome. Read on. There’s a few common gotchas that we’d love to help you avoid.</p>
<h3 id="tests-and-documentation">Tests and documentation</h3>
<p>Any time you propose a code change, you should also include updates to the documentation and tests within the same pull request.</p>
<h4 id="documentation">Documentation</h4>
<p>If your contribution changes any Jekyll behavior, make sure to update the documentation. Documentation lives in the <code class="highlighter-rouge">docs/_docs</code> folder (spoiler alert: it’s a Jekyll site!). If the docs are missing information, please feel free to add it in. Great docs make a great project. Include changes to the documentation within your pull request, and once merged, <code class="highlighter-rouge">jekyllrb.com</code> will be updated.</p>
<h4 id="tests">Tests</h4>
<ul>
<li>
<p>If you’re creating a small fix or patch to an existing feature, a simple test is more than enough. You can usually copy/paste from an existing example in the <code class="highlighter-rouge">tests</code> folder, but if you need you can find out about our tests suites <a href="https://github.com/thoughtbot/shoulda/tree/master">Shoulda</a> and <a href="https://github.com/rspec/rspec-mocks">RSpec-Mocks</a>.</p>
</li>
<li>
<p>If it’s a brand new feature, create a new <a href="https://github.com/cucumber/cucumber/">Cucumber</a> feature, reusing existing steps where appropriate.</p>
</li>
</ul>
<h3 id="code-contributions-generally">Code contributions generally</h3>
<ul>
<li>
<p>Jekyll uses the <a href="https://github.com/bbatsov/rubocop">Rubocop</a> static analyzer to ensure that contributions follow the <a href="https://github.com/styleguide/ruby">GitHub Ruby Styleguide</a>. Please check your code using <code class="highlighter-rouge">script/fmt</code> and resolve any errors before pushing your branch.</p>
</li>
<li>
<p>Don’t bump the Gem version in your pull request (if you don’t know what that means, you probably didn’t).</p>
</li>
<li>
<p>You can use the command <code class="highlighter-rouge">script/console</code> to start a REPL to explore the result of
Jekyll’s methods. It also provides you with helpful methods to quickly create a
site or configuration. <a href="https://github.com/jekyll/jekyll/blob/master/script/console">Feel free to check it out!</a></p>
</li>
</ul>
<h2 id="running-tests-locally">Running tests locally</h2>
<h3 id="test-dependencies">Test Dependencies</h3>
<p>To run the test suite and build the gem you’ll need to install Jekyll’s dependencies by running the following command:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>script/bootstrap
</code></pre></div></div>
<p>Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly):</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>script/cibuild
</code></pre></div></div>
<p>If you are only updating a file in <code class="highlighter-rouge">test/</code>, you can use the command:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>script/test <span class="nb">test</span>/blah_test.rb
</code></pre></div></div>
<p>If you are only updating a <code class="highlighter-rouge">.feature</code> file, you can use the command:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>script/cucumber features/blah.feature
</code></pre></div></div>
<p>Both <code class="highlighter-rouge">script/test</code> and <code class="highlighter-rouge">script/cucumber</code> can be run without arguments to
run its entire respective suite.</p>
<h2 id="a-thank-you">A thank you</h2>
<p>Thanks! Hacking on Jekyll should be fun. If you find any of this hard to figure out, let us know so we can improve our process or documentation!</p>
<div class="section-nav">
<div class="left align-right">
<a href="/docs/upgrading/2-to-3/" class="prev">Back</a>
</div>
<div class="right align-left">
<a href="/docs/maintaining/" class="next">Next</a>
</div>
</div>
<div class="clear"></div>
</article>
</div>
<div class="unit one-fifth hide-on-mobiles">
<aside>
<h4>Getting Started</h4>
<ul>
<li class=""><a href="/docs/home/">Welcome</a></li>
<li class=""><a href="/docs/quickstart/">Quick-start guide</a></li>
<li class=""><a href="/docs/installation/">Installation</a></li>
<li class=""><a href="/docs/windows/">Jekyll on Windows</a></li>
<li class=""><a href="/docs/usage/">Basic Usage</a></li>
<li class=""><a href="/docs/structure/">Directory structure</a></li>
<li class=""><a href="/docs/configuration/">Configuration</a></li>
</ul>
<h4>Your Content</h4>
<ul>
<li class=""><a href="/docs/frontmatter/">Front Matter</a></li>
<li class=""><a href="/docs/posts/">Writing posts</a></li>
<li class=""><a href="/docs/drafts/">Working with drafts</a></li>
<li class=""><a href="/docs/pages/">Creating pages</a></li>
<li class=""><a href="/docs/static-files/">Static Files</a></li>
<li class=""><a href="/docs/variables/">Variables</a></li>
<li class=""><a href="/docs/collections/">Collections</a></li>
<li class=""><a href="/docs/datafiles/">Data Files</a></li>
<li class=""><a href="/docs/assets/">Assets</a></li>
<li class=""><a href="/docs/migrations/">Blog migrations</a></li>
</ul>
<h4>Customization</h4>
<ul>
<li class=""><a href="/docs/templates/">Templates</a></li>
<li class=""><a href="/docs/includes/">Includes</a></li>
<li class=""><a href="/docs/permalinks/">Permalinks</a></li>
<li class=""><a href="/docs/pagination/">Pagination</a></li>
<li class=""><a href="/docs/plugins/">Plugins</a></li>
<li class=""><a href="/docs/themes/">Themes</a></li>
<li class=""><a href="/docs/extras/">Extras</a></li>
</ul>
<h4>Deployment</h4>
<ul>
<li class=""><a href="/docs/github-pages/">GitHub Pages</a></li>
<li class=""><a href="/docs/deployment-methods/">Deployment methods</a></li>
<li class=""><a href="/docs/continuous-integration/">Continuous Integration</a></li>
</ul>
<h4>Miscellaneous</h4>
<ul>
<li class=""><a href="/docs/troubleshooting/">Troubleshooting</a></li>
<li class=""><a href="/docs/sites/">Sites using Jekyll</a></li>
<li class=""><a href="/docs/resources/">Resources</a></li>
<li class=""><a href="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</a></li>
<li class=""><a href="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</a></li>
</ul>
<h4>Meta</h4>
<ul>
<li class="current"><a href="/docs/contributing/">Contributing</a></li>
<li class=""><a href="/docs/maintaining/">Maintaining Jekyll</a></li>
<li class=""><a href="/docs/conduct/">Code of Conduct</a></li>
<li class=""><a href="/docs/history/">History</a></li>
</ul>
</aside>
</div>
<div class="clear"></div>
</div>
</section>
<footer>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<p>The contents of this website are <br>© 2018 under the terms of the <a href="https://github.com/jekyll/jekyll/blob/master/LICENSE">MIT License</a>.</p>
</div>
<div class="unit two-thirds align-right center-on-mobiles">
<p>
Proudly hosted by
<a href="https://github.com">
<img src="/img/footer-logo.png" width="100" height="30" alt="GitHub • Social coding">
</a>
</p>
</div>
</div>
</footer>
<script>
var anchorForId = function (id) {
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + id;
anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
anchor.title = "Permalink";
return anchor;
};
var linkifyAnchors = function (level, containingElement) {
var headers = containingElement.getElementsByTagName("h" + level);
for (var h = 0; h < headers.length; h++) {
var header = headers[h];
if (typeof header.id !== "undefined" && header.id !== "") {
header.appendChild(anchorForId(header.id));
}
}
};
document.onreadystatechange = function () {
if (this.readyState === "complete") {
var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
if (!contentBlock) {
return;
}
for (var level = 1; level <= 6; level++) {
linkifyAnchors(level, contentBlock);
}
}
};
</script>
<!-- Google Analytics (https://www.google.com/analytics) -->
<script>
!function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
(j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),
L=e.getElementsByTagName(k)[0],l.src='https://www.google-analytics.com/analytics.js',
L.parentNode.insertBefore(l,L)}(window,document,'script','ga');
ga('create', 'UA-50755011-1', 'jekyllrb.com');
ga('send', 'pageview');
</script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
apiKey: '50fe39c839958dfad797000f33e2ec17',
indexName: 'jekyllrb',
inputSelector: '#docsearch-input',
enhancedSearchInput: true,
debug: false // Set debug to true if you want to inspect the dropdown
});
</script>
</body>
</html>