{"action":"created","comment":{"url":"https://api.github.com/repos/jekyll/jekyll/pulls/comments/94102388","pull_request_review_id":14632894,"id":94102388,"diff_hunk":"@@ -4,28 +4,41 @@ title: Themes\n permalink: /docs/themes/\n ---\n \n-Jekyll has an extensive theme system, which allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package layouts, includes, and stylesheets in a way that can be overridden by your site's content.\n+Jekyll has an extensive theme system that allows you to leverage community-maintained templates and styles to customize your site's presentation. Jekyll themes package up layouts, includes, and stylesheets in a way that can be overridden by your site's content.\n \n-## Installing a theme\n+## Understanding gem-based themes\n \n-1. To install a theme, first, add the theme to your site's `Gemfile`:\n+When you [create a new Jekyll site](/docs/quickstart) (by running the `jekyll new <PATH>` command), Jekyll installs a site that uses a gem-based theme called [Minima](https://github.com/jekyll/minima).\n \n-        gem 'my-awesome-jekyll-theme'\n+With gem-based themes, some of the site's directories (such as the `assets`, `_layouts`, `_includes`, and `_sass` directories) are stored in the theme-gem, hidden from your immediate view. Yet all of the necessary directories will be read and processed during Jekyll's build process.\n \n-2. Save the changes to your `Gemfile`\n-3. Run the command `bundle install` to install the theme\n-4. Finally, activate the theme by adding the following to your site's `_config.yml`:\n+In the case of Minima, you see only the following files in your Jekyll site directory:\n \n-        theme: my-awesome-jekyll-theme\n+```\n+├── Gemfile\n+├── Gemfile.lock\n+├── _config.yml\n+├── _posts\n+│   └── 2016-12-04-welcome-to-jekyll.markdown\n+├── about.md\n+└── index.md\n+```\n \n-You can have multiple themes listed in your site's Gemfile, but only one theme can be selected in your site's `_config.yml`.\n-{: .note .info }\n+The `Gemfile` and `Gemfile.lock` files are used by Bundler to keep track of the required gems and gem versions you need to build your Jekyll site.\n+\n+Gem-based themes make it easy for theme developers to make updates available to anyone who has the theme gem. When there's an update, theme developers push the update to RubyGems.\n+\n+If you have the theme gem, you can (if you desire) run `bundle update` to update all gems in your project. Or you can run `bundle update <theme>`, replacing `<theme>` with the theme name, such as `minima`, to just update the theme gem. Any new files or updates the theme developer has made (such as to stylesheets or includes) will be pulled into your project automatically.\n+\n+The goal of gem-based themes is to allow you to get all the benefits of a robust, continually updated theme without having all the theme's files getting in your way and over-complicating what might be your primary focus: creating content.\n \n ## Overriding theme defaults\n \n-Jekyll themes set default layouts, includes, and stylesheets, that can be overridden by your site's content. For example, if your selected theme has a `page` layout, you can override the theme's layout by creating your own `page` layout in the `_layouts` folder (e.g., `_layouts/page.html`).\n+Jekyll themes set default layouts, includes, and stylesheets. However, you can override any of the theme defaults with your own site content.\n \n-Jekyll will look first to your site's content, before looking to the theme's defaults, for any requested file in the following folders:\n+For example, if your selected theme has a `page` layout, you can override the theme's layout by creating your own `page` layout in the `_layouts` directory (for example, `_layouts/page.html`).","path":"docs/_docs/themes.md","position":48,"original_position":48,"commit_id":"c31716194277197accd8aa0798996af6f2318be8","original_commit_id":"c31716194277197accd8aa0798996af6f2318be8","user":{"login":"parkr","id":237985,"avatar_url":"https://avatars.githubusercontent.com/u/237985?v=3","gravatar_id":"","url":"https://api.github.com/users/parkr","html_url":"https://github.com/parkr","followers_url":"https://api.github.com/users/parkr/followers","following_url":"https://api.github.com/users/parkr/following{/other_user}","gists_url":"https://api.github.com/users/parkr/gists{/gist_id}","starred_url":"https://api.github.com/users/parkr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/parkr/subscriptions","organizations_url":"https://api.github.com/users/parkr/orgs","repos_url":"https://api.github.com/users/parkr/repos","events_url":"https://api.github.com/users/parkr/events{/privacy}","received_events_url":"https://api.github.com/users/parkr/received_events","type":"User","site_admin":true},"body":"> (for example, `_layouts/page.html`)\r\n\r\nThis is a tricky case of \"e.g.\" vs \"i.e.\" and I think it's \"i.e.\" here, because you're elaborating and giving specific information about a pre-existing example. This would read better to me:\r\n\r\n> by creating your own `page` layout in the `_layouts` directory, i.e. `_layouts/page.html`.\r\n\r\nFeel free to replace \"i.e.\" with something less Latin if you would prefer.","created_at":"2016-12-29T05:28:14Z","updated_at":"2016-12-29T05:52:14Z","html_url":"https://github.com/jekyll/jekyll/pull/5690#discussion_r94102388","pull_request_url":"https://api.github.com/repos/jekyll/jekyll/pulls/5690","_links":{"self":{"href":"https://api.github.com/repos/jekyll/jekyll/pulls/comments/94102388"},"html":{"href":"https://github.com/jekyll/jekyll/pull/5690#discussion_r94102388"},"pull_request":{"href":"https://api.github.com/repos/jekyll/jekyll/pulls/5690"}}},"pull_request":{"url":"https://api.github.com/repos/jekyll/jekyll/pulls/5690","id":99339074,"html_url":"https://github.com/jekyll/jekyll/pull/5690","diff_url":"https://github.com/jekyll/jekyll/pull/5690.diff","patch_url":"https://github.com/jekyll/jekyll/pull/5690.patch","issue_url":"https://api.github.com/repos/jekyll/jekyll/issues/5690","number":5690,"state":"open","locked":false,"title":"Improve theme docs","user":{"login":"tomjohnson1492","id":6385062,"avatar_url":"https://avatars.githubusercontent.com/u/6385062?v=3","gravatar_id":"","url":"https://api.github.com/users/tomjohnson1492","html_url":"https://github.com/tomjohnson1492","followers_url":"https://api.github.com/users/tomjohnson1492/followers","following_url":"https://api.github.com/users/tomjohnson1492/following{/other_user}","gists_url":"https://api.github.com/users/tomjohnson1492/gists{/gist_id}","starred_url":"https://api.github.com/users/tomjohnson1492/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tomjohnson1492/subscriptions","organizations_url":"https://api.github.com/users/tomjohnson1492/orgs","repos_url":"https://api.github.com/users/tomjohnson1492/repos","events_url":"https://api.github.com/users/tomjohnson1492/events{/privacy}","received_events_url":"https://api.github.com/users/tomjohnson1492/received_events","type":"User","site_admin":false},"body":"See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. \r\n\r\n@jekyll/documentation","created_at":"2016-12-26T04:33:17Z","updated_at":"2016-12-29T05:52:14Z","closed_at":null,"merged_at":null,"merge_commit_sha":"757ecea1db9f3650bcfb08e88a5f327e1ab50521","assignee":{"login":"DirtyF","id":103008,"avatar_url":"https://avatars.githubusercontent.com/u/103008?v=3","gravatar_id":"","url":"https://api.github.com/users/DirtyF","html_url":"https://github.com/DirtyF","followers_url":"https://api.github.com/users/DirtyF/followers","following_url":"https://api.github.com/users/DirtyF/following{/other_user}","gists_url":"https://api.github.com/users/DirtyF/gists{/gist_id}","starred_url":"https://api.github.com/users/DirtyF/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/DirtyF/subscriptions","organizations_url":"https://api.github.com/users/DirtyF/orgs","repos_url":"https://api.github.com/users/DirtyF/repos","events_url":"https://api.github.com/users/DirtyF/events{/privacy}","received_events_url":"https://api.github.com/users/DirtyF/received_events","type":"User","site_admin":false},"assignees":[{"login":"DirtyF","id":103008,"avatar_url":"https://avatars.githubusercontent.com/u/103008?v=3","gravatar_id":"","url":"https://api.github.com/users/DirtyF","html_url":"https://github.com/DirtyF","followers_url":"https://api.github.com/users/DirtyF/followers","following_url":"https://api.github.com/users/DirtyF/following{/other_user}","gists_url":"https://api.github.com/users/DirtyF/gists{/gist_id}","starred_url":"https://api.github.com/users/DirtyF/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/DirtyF/subscriptions","organizations_url":"https://api.github.com/users/DirtyF/orgs","repos_url":"https://api.github.com/users/DirtyF/repos","events_url":"https://api.github.com/users/DirtyF/events{/privacy}","received_events_url":"https://api.github.com/users/DirtyF/received_events","type":"User","site_admin":false},{"login":"parkr","id":237985,"avatar_url":"https://avatars.githubusercontent.com/u/237985?v=3","gravatar_id":"","url":"https://api.github.com/users/parkr","html_url":"https://github.com/parkr","followers_url":"https://api.github.com/users/parkr/followers","following_url":"https://api.github.com/users/parkr/following{/other_user}","gists_url":"https://api.github.com/users/parkr/gists{/gist_id}","starred_url":"https://api.github.com/users/parkr/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/parkr/subscriptions","organizations_url":"https://api.github.com/users/parkr/orgs","repos_url":"https://api.github.com/users/parkr/repos","events_url":"https://api.github.com/users/parkr/events{/privacy}","received_events_url":"https://api.github.com/users/parkr/received_events","type":"User","site_admin":true}],"milestone":null,"commits_url":"https://api.github.com/repos/jekyll/jekyll/pulls/5690/commits","review_comments_url":"https://api.github.com/repos/jekyll/jekyll/pulls/5690/comments","review_comment_url":"https://api.github.com/repos/jekyll/jekyll/pulls/comments{/number}","comments_url":"https://api.github.com/repos/jekyll/jekyll/issues/5690/comments","statuses_url":"https://api.github.com/repos/jekyll/jekyll/statuses/c31716194277197accd8aa0798996af6f2318be8","head":{"label":"tomjohnson1492:patch-4","ref":"patch-4","sha":"c31716194277197accd8aa0798996af6f2318be8","user":{"login":"tomjohnson1492","id":6385062,"avatar_url":"https://avatars.githubusercontent.com/u/6385062?v=3","gravatar_id":"","url":"https://api.github.com/users/tomjohnson1492","html_url":"https://github.com/tomjohnson1492","followers_url":"https://api.github.com/users/tomjohnson1492/followers","following_url":"https://api.github.com/users/tomjohnson1492/following{/other_user}","gists_url":"https://api.github.com/users/tomjohnson1492/gists{/gist_id}","starred_url":"https://api.github.com/users/tomjohnson1492/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tomjohnson1492/subscriptions","organizations_url":"https://api.github.com/users/tomjohnson1492/orgs","repos_url":"https://api.github.com/users/tomjohnson1492/repos","events_url":"https://api.github.com/users/tomjohnson1492/events{/privacy}","received_events_url":"https://api.github.com/users/tomjohnson1492/received_events","type":"User","site_admin":false},"repo":{"id":75111136,"name":"jekyll","full_name":"tomjohnson1492/jekyll","owner":{"login":"tomjohnson1492","id":6385062,"avatar_url":"https://avatars.githubusercontent.com/u/6385062?v=3","gravatar_id":"","url":"https://api.github.com/users/tomjohnson1492","html_url":"https://github.com/tomjohnson1492","followers_url":"https://api.github.com/users/tomjohnson1492/followers","following_url":"https://api.github.com/users/tomjohnson1492/following{/other_user}","gists_url":"https://api.github.com/users/tomjohnson1492/gists{/gist_id}","starred_url":"https://api.github.com/users/tomjohnson1492/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tomjohnson1492/subscriptions","organizations_url":"https://api.github.com/users/tomjohnson1492/orgs","repos_url":"https://api.github.com/users/tomjohnson1492/repos","events_url":"https://api.github.com/users/tomjohnson1492/events{/privacy}","received_events_url":"https://api.github.com/users/tomjohnson1492/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/tomjohnson1492/jekyll","description":":globe_with_meridians: Jekyll is a blog-aware, static site generator in Ruby","fork":true,"url":"https://api.github.com/repos/tomjohnson1492/jekyll","forks_url":"https://api.github.com/repos/tomjohnson1492/jekyll/forks","keys_url":"https://api.github.com/repos/tomjohnson1492/jekyll/keys{/key_id}","collaborators_url":"https://api.github.com/repos/tomjohnson1492/jekyll/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/tomjohnson1492/jekyll/teams","hooks_url":"https://api.github.com/repos/tomjohnson1492/jekyll/hooks","issue_events_url":"https://api.github.com/repos/tomjohnson1492/jekyll/issues/events{/number}","events_url":"https://api.github.com/repos/tomjohnson1492/jekyll/events","assignees_url":"https://api.github.com/repos/tomjohnson1492/jekyll/assignees{/user}","branches_url":"https://api.github.com/repos/tomjohnson1492/jekyll/branches{/branch}","tags_url":"https://api.github.com/repos/tomjohnson1492/jekyll/tags","blobs_url":"https://api.github.com/repos/tomjohnson1492/jekyll/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/tomjohnson1492/jekyll/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/tomjohnson1492/jekyll/git/refs{/sha}","trees_url":"https://api.github.com/repos/tomjohnson1492/jekyll/git/trees{/sha}","statuses_url":"https://api.github.com/repos/tomjohnson1492/jekyll/statuses/{sha}","languages_url":"https://api.github.com/repos/tomjohnson1492/jekyll/languages","stargazers_url":"https://api.github.com/repos/tomjohnson1492/jekyll/stargazers","contributors_url":"https://api.github.com/repos/tomjohnson1492/jekyll/contributors","subscribers_url":"https://api.github.com/repos/tomjohnson1492/jekyll/subscribers","subscription_url":"https://api.github.com/repos/tomjohnson1492/jekyll/subscription","commits_url":"https://api.github.com/repos/tomjohnson1492/jekyll/commits{/sha}","git_commits_url":"https://api.github.com/repos/tomjohnson1492/jekyll/git/commits{/sha}","comments_url":"https://api.github.com/repos/tomjohnson1492/jekyll/comments{/number}","issue_comment_url":"https://api.github.com/repos/tomjohnson1492/jekyll/issues/comments{/number}","contents_url":"https://api.github.com/repos/tomjohnson1492/jekyll/contents/{+path}","compare_url":"https://api.github.com/repos/tomjohnson1492/jekyll/compare/{base}...{head}","merges_url":"https://api.github.com/repos/tomjohnson1492/jekyll/merges","archive_url":"https://api.github.com/repos/tomjohnson1492/jekyll/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/tomjohnson1492/jekyll/downloads","issues_url":"https://api.github.com/repos/tomjohnson1492/jekyll/issues{/number}","pulls_url":"https://api.github.com/repos/tomjohnson1492/jekyll/pulls{/number}","milestones_url":"https://api.github.com/repos/tomjohnson1492/jekyll/milestones{/number}","notifications_url":"https://api.github.com/repos/tomjohnson1492/jekyll/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/tomjohnson1492/jekyll/labels{/name}","releases_url":"https://api.github.com/repos/tomjohnson1492/jekyll/releases{/id}","deployments_url":"https://api.github.com/repos/tomjohnson1492/jekyll/deployments","created_at":"2016-11-29T18:44:19Z","updated_at":"2016-11-29T18:44:24Z","pushed_at":"2016-12-28T23:21:58Z","git_url":"git://github.com/tomjohnson1492/jekyll.git","ssh_url":"git@github.com:tomjohnson1492/jekyll.git","clone_url":"https://github.com/tomjohnson1492/jekyll.git","svn_url":"https://github.com/tomjohnson1492/jekyll","homepage":"https://jekyllrb.com","size":11726,"stargazers_count":0,"watchers_count":0,"language":"Ruby","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"jekyll:master","ref":"master","sha":"52c2645abb871dbde190651e8e2396dacb3b60dc","user":{"login":"jekyll","id":3083652,"avatar_url":"https://avatars.githubusercontent.com/u/3083652?v=3","gravatar_id":"","url":"https://api.github.com/users/jekyll","html_url":"https://github.com/jekyll","followers_url":"https://api.github.com/users/jekyll/followers","following_url":"https://api.github.com/users/jekyll/following{/other_user}","gists_url":"https://api.github.com/users/jekyll/gists{/gist_id}","starred_url":"https://api.github.com/users/jekyll/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jekyll/subscriptions","organizations_url":"https://api.github.com/users/jekyll/orgs","repos_url":"https://api.github.com/users/jekyll/repos","events_url":"https://api.github.com/users/jekyll/events{/privacy}","received_events_url":"https://api.github.com/users/jekyll/received_events","type":"Organization","site_admin":false},"repo":{"id":65252,"name":"jekyll","full_name":"jekyll/jekyll","owner":{"login":"jekyll","id":3083652,"avatar_url":"https://avatars.githubusercontent.com/u/3083652?v=3","gravatar_id":"","url":"https://api.github.com/users/jekyll","html_url":"https://github.com/jekyll","followers_url":"https://api.github.com/users/jekyll/followers","following_url":"https://api.github.com/users/jekyll/following{/other_user}","gists_url":"https://api.github.com/users/jekyll/gists{/gist_id}","starred_url":"https://api.github.com/users/jekyll/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jekyll/subscriptions","organizations_url":"https://api.github.com/users/jekyll/orgs","repos_url":"https://api.github.com/users/jekyll/repos","events_url":"https://api.github.com/users/jekyll/events{/privacy}","received_events_url":"https://api.github.com/users/jekyll/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/jekyll/jekyll","description":":globe_with_meridians: Jekyll is a blog-aware, static site generator in Ruby","fork":false,"url":"https://api.github.com/repos/jekyll/jekyll","forks_url":"https://api.github.com/repos/jekyll/jekyll/forks","keys_url":"https://api.github.com/repos/jekyll/jekyll/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jekyll/jekyll/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jekyll/jekyll/teams","hooks_url":"https://api.github.com/repos/jekyll/jekyll/hooks","issue_events_url":"https://api.github.com/repos/jekyll/jekyll/issues/events{/number}","events_url":"https://api.github.com/repos/jekyll/jekyll/events","assignees_url":"https://api.github.com/repos/jekyll/jekyll/assignees{/user}","branches_url":"https://api.github.com/repos/jekyll/jekyll/branches{/branch}","tags_url":"https://api.github.com/repos/jekyll/jekyll/tags","blobs_url":"https://api.github.com/repos/jekyll/jekyll/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jekyll/jekyll/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jekyll/jekyll/git/refs{/sha}","trees_url":"https://api.github.com/repos/jekyll/jekyll/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jekyll/jekyll/statuses/{sha}","languages_url":"https://api.github.com/repos/jekyll/jekyll/languages","stargazers_url":"https://api.github.com/repos/jekyll/jekyll/stargazers","contributors_url":"https://api.github.com/repos/jekyll/jekyll/contributors","subscribers_url":"https://api.github.com/repos/jekyll/jekyll/subscribers","subscription_url":"https://api.github.com/repos/jekyll/jekyll/subscription","commits_url":"https://api.github.com/repos/jekyll/jekyll/commits{/sha}","git_commits_url":"https://api.github.com/repos/jekyll/jekyll/git/commits{/sha}","comments_url":"https://api.github.com/repos/jekyll/jekyll/comments{/number}","issue_comment_url":"https://api.github.com/repos/jekyll/jekyll/issues/comments{/number}","contents_url":"https://api.github.com/repos/jekyll/jekyll/contents/{+path}","compare_url":"https://api.github.com/repos/jekyll/jekyll/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jekyll/jekyll/merges","archive_url":"https://api.github.com/repos/jekyll/jekyll/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jekyll/jekyll/downloads","issues_url":"https://api.github.com/repos/jekyll/jekyll/issues{/number}","pulls_url":"https://api.github.com/repos/jekyll/jekyll/pulls{/number}","milestones_url":"https://api.github.com/repos/jekyll/jekyll/milestones{/number}","notifications_url":"https://api.github.com/repos/jekyll/jekyll/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jekyll/jekyll/labels{/name}","releases_url":"https://api.github.com/repos/jekyll/jekyll/releases{/id}","deployments_url":"https://api.github.com/repos/jekyll/jekyll/deployments","created_at":"2008-10-20T06:29:03Z","updated_at":"2016-12-29T05:38:07Z","pushed_at":"2016-12-28T23:22:06Z","git_url":"git://github.com/jekyll/jekyll.git","ssh_url":"git@github.com:jekyll/jekyll.git","clone_url":"https://github.com/jekyll/jekyll.git","svn_url":"https://github.com/jekyll/jekyll","homepage":"https://jekyllrb.com","size":11658,"stargazers_count":28053,"watchers_count":28053,"language":"Ruby","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":6208,"mirror_url":null,"open_issues_count":151,"forks":6208,"open_issues":151,"watchers":28053,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/jekyll/jekyll/pulls/5690"},"html":{"href":"https://github.com/jekyll/jekyll/pull/5690"},"issue":{"href":"https://api.github.com/repos/jekyll/jekyll/issues/5690"},"comments":{"href":"https://api.github.com/repos/jekyll/jekyll/issues/5690/comments"},"review_comments":{"href":"https://api.github.com/repos/jekyll/jekyll/pulls/5690/comments"},"review_comment":{"href":"https://api.github.com/repos/jekyll/jekyll/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/jekyll/jekyll/pulls/5690/commits"},"statuses":{"href":"https://api.github.com/repos/jekyll/jekyll/statuses/c31716194277197accd8aa0798996af6f2318be8"}}}}
{"actor":{"display_login":"parkr"}}