<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v3.9.0">
<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.6.1 -->
<title>Upgrading from 0.x to 2.x | Jekyll • Simple, blog-aware, static sites</title>
<meta name="generator" content="Jekyll v3.9.0" />
<meta property="og:title" content="Upgrading from 0.x to 2.x" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="Upgrading from an older version of Jekyll? A few things have changed in 1.0 and 2.0 that you’ll want to know about." />
<meta property="og:description" content="Upgrading from an older version of Jekyll? A few things have changed in 1.0 and 2.0 that you’ll want to know about." />
<link rel="canonical" href="https://jekyllrb.com/docs/upgrading/0-to-2/" />
<meta property="og:url" content="https://jekyllrb.com/docs/upgrading/0-to-2/" />
<meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2020-08-05T11:55:36-07:00" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Upgrading from 0.x to 2.x" />
<meta name="twitter:site" content="@jekyllrb" />
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY" />
<script type="application/ld+json">
{"url":"https://jekyllrb.com/docs/upgrading/0-to-2/","headline":"Upgrading from 0.x to 2.x","dateModified":"2020-08-05T11:55:36-07:00","datePublished":"2020-08-05T11:55:36-07:00","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://jekyllrb.com/img/logo-2x.png"}},"description":"Upgrading from an older version of Jekyll? A few things have changed in 1.0 and 2.0 that you’ll want to know about.","mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/upgrading/0-to-2/"},"@type":"BlogPosting","@context":"https://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.9.0">v3.9.0</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/upgrading/0-to-2.md"><i class="fa fa-pencil"></i> Improve this page</a>
</div>
<h1>Upgrading from 0.x to 2.x</h1>
<p>Upgrading from an older version of Jekyll? A few things have changed in 1.0
and 2.0 that you’ll want to know about.</p>
<p>Before we dive in, go ahead and fetch the latest version of Jekyll:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem update jekyll
</code></pre></div></div>
<div class="note feature">
<h5>Diving in</h5>
<p>Want to get a new Jekyll site up and running quickly? Simply
run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
Jekyll site.</p>
</div>
<h3 id="the-jekyll-command">The Jekyll Command</h3>
<p>For better clarity, Jekyll now accepts the commands <code class="language-plaintext highlighter-rouge">build</code> and <code class="language-plaintext highlighter-rouge">serve</code>.
Whereas before you might simply run the command <code class="language-plaintext highlighter-rouge">jekyll</code> to generate a site
and <code class="language-plaintext highlighter-rouge">jekyll --server</code> to view it locally, in v2.0 (and later) you should
use the subcommands <code class="language-plaintext highlighter-rouge">jekyll build</code> and <code class="language-plaintext highlighter-rouge">jekyll serve</code> to build and preview
your site.</p>
<div class="note info">
<h5>Watching and Serving</h5>
<p>With the new subcommands, the way sites are previewed locally
changed a bit. Instead of specifying <code class="language-plaintext highlighter-rouge">server: true</code> in the site’s
configuration file, use <code class="language-plaintext highlighter-rouge">jekyll serve</code>. The same holds true for
<code class="language-plaintext highlighter-rouge">watch: true</code>. Instead, use the <code class="language-plaintext highlighter-rouge">--watch</code> flag with either <code class="language-plaintext highlighter-rouge">jekyll serve</code>
or <code class="language-plaintext highlighter-rouge">jekyll build</code>.</p>
</div>
<h3 id="absolute-permalinks">Absolute Permalinks</h3>
<p>In Jekyll v1.0, we introduced absolute permalinks for pages in
subdirectories. Starting with v2.0, absolute permalinks are opt-out,
meaning Jekyll will default to using absolute permalinks instead of
relative permalinks. Relative permalink backwards-compatibility was removed in v3.0.</p>
<div class="note warning" id="absolute-permalinks-warning">
<h5>Absolute permalinks will be required in v3.0 and on</h5>
<p>
Starting with Jekyll v3.0, relative permalinks functionality will be removed and thus unavailable for use.
</p>
</div>
<h3 id="draft-posts">Draft Posts</h3>
<p>Jekyll now lets you write draft posts, and allows you to easily preview how
they will look prior to publishing. To start a draft, simply create a folder
called <code class="language-plaintext highlighter-rouge">_drafts</code> in your site’s source directory (e.g., alongside <code class="language-plaintext highlighter-rouge">_posts</code>),
and add a new markdown file to it. To preview your new post, simply run the
<code class="language-plaintext highlighter-rouge">jekyll serve</code> command with the <code class="language-plaintext highlighter-rouge">--drafts</code> flag.</p>
<div class="note info">
<h5>Drafts don’t have dates</h5>
<p>
Unlike posts, drafts don’t have a date, since they haven’t
been published yet. Rather than naming your draft something like
<code class="language-plaintext highlighter-rouge">2013-07-01-my-draft-post.md</code>, simply name the file what you’d like your
post to eventually be titled, here <code class="language-plaintext highlighter-rouge">my-draft-post.md</code>.</p>
</div>
<h3 id="custom-config-file">Custom Config File</h3>
<p>Rather than passing individual flags via the command line, you can now pass
an entire custom Jekyll config file. This helps to distinguish between
environments, or lets you programmatically override user-specified
defaults. Simply add the <code class="language-plaintext highlighter-rouge">--config</code> flag to the <code class="language-plaintext highlighter-rouge">jekyll</code> command, followed
by the path to one or more config files (comma-delimited, no spaces).</p>
<h4 id="as-a-result-the-following-command-line-flags-are-now-deprecated">As a result, the following command line flags are now deprecated:</h4>
<ul>
<li><code class="language-plaintext highlighter-rouge">--no-server</code></li>
<li><code class="language-plaintext highlighter-rouge">--no-auto</code> (now <code class="language-plaintext highlighter-rouge">--no-watch</code>)</li>
<li><code class="language-plaintext highlighter-rouge">--auto</code> (now <code class="language-plaintext highlighter-rouge">--watch</code>)</li>
<li><code class="language-plaintext highlighter-rouge">--server</code></li>
<li><code class="language-plaintext highlighter-rouge">--url=</code></li>
<li><code class="language-plaintext highlighter-rouge">--maruku</code>, <code class="language-plaintext highlighter-rouge">--rdiscount</code>, and <code class="language-plaintext highlighter-rouge">--redcarpet</code></li>
<li><code class="language-plaintext highlighter-rouge">--pygments</code></li>
<li><code class="language-plaintext highlighter-rouge">--permalink=</code></li>
<li><code class="language-plaintext highlighter-rouge">--paginate</code></li>
</ul>
<div class="note info">
<h5>The config flag explicitly specifies your configuration file(s)</h5>
<p>If you use the <code class="language-plaintext highlighter-rouge">--config</code> flag, Jekyll will ignore your
<code class="language-plaintext highlighter-rouge">_config.yml</code> file. Want to merge a custom configuration with the normal
configuration? No problem. Jekyll will accept more than one custom config
file via the command line. Config files cascade from right to left, such
that if I run <code class="language-plaintext highlighter-rouge">jekyll serve --config _config.yml,_config-dev.yml</code>,
the values in the config files on the right (<code class="language-plaintext highlighter-rouge">_config-dev.yml</code>) overwrite
those on the left (<code class="language-plaintext highlighter-rouge">_config.yml</code>) when both contain the same key.</p>
</div>
<h3 id="new-config-file-options">New Config File Options</h3>
<p>Jekyll 1.0 introduced several new config file options. Before you upgrade,
you should check to see if any of these are present in your pre-1.0 config
file, and if so, make sure that you’re using them properly:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">excerpt_separator</code></li>
<li><code class="language-plaintext highlighter-rouge">host</code></li>
<li><code class="language-plaintext highlighter-rouge">include</code></li>
<li><code class="language-plaintext highlighter-rouge">keep_files</code></li>
<li><code class="language-plaintext highlighter-rouge">layouts</code></li>
<li><code class="language-plaintext highlighter-rouge">show_drafts</code></li>
<li><code class="language-plaintext highlighter-rouge">timezone</code></li>
<li><code class="language-plaintext highlighter-rouge">url</code></li>
</ul>
<h3 id="baseurl">Baseurl</h3>
<p>Often, you’ll want the ability to run a Jekyll site in multiple places,
such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes
that easier with the new <code class="language-plaintext highlighter-rouge">--baseurl</code> flag. To take advantage of this
feature, first add the production <code class="language-plaintext highlighter-rouge">baseurl</code> to your site’s <code class="language-plaintext highlighter-rouge">_config.yml</code>
file. Then, throughout the site, simply prefix relative URLs
with <code class="language-plaintext highlighter-rouge">{{ site.baseurl }}</code>.
When you’re ready to preview your site locally, pass along the <code class="language-plaintext highlighter-rouge">--baseurl</code>
flag with your local baseurl (most likely <code class="language-plaintext highlighter-rouge">/</code>) to <code class="language-plaintext highlighter-rouge">jekyll serve</code> and Jekyll
will swap in whatever you’ve passed along, ensuring all your links work as
you’d expect in both environments.</p>
<div class="note warning">
<h5>All page and post URLs contain leading slashes</h5>
<p>If you use the method described above, please remember
that the URLs for all posts and pages contain a leading slash. Therefore,
concatenating the site baseurl and the post/page url where
<code class="language-plaintext highlighter-rouge">site.baseurl = /</code> and <code class="language-plaintext highlighter-rouge">post.url = /2013/06/05/my-fun-post/</code> will
result in two leading slashes, which will break links. It is thus
suggested that prefixing with <code class="language-plaintext highlighter-rouge">site.baseurl</code> only be used when the
<code class="language-plaintext highlighter-rouge">baseurl</code> is something other than the default of <code class="language-plaintext highlighter-rouge">/</code>.</p>
</div>
<div class="section-nav">
<div class="left align-right">
<a href="/docs/resources/" class="prev">Back</a>
</div>
<div class="right align-left">
<a href="/docs/upgrading/2-to-3/" 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="current"><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=""><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 />© 2020 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>