Improve theme docs #5690
Improve theme docs #5690
Conversation
See #5630 for more details on the update. @jekyll/documentation @DirtyF
| title: Themes | ||
| permalink: /docs/themes/ | ||
| title: Templates | ||
| permalink: /docs/templates/ |
There was a problem hiding this comment.
Woah. Let's not break all existing links.
There was a problem hiding this comment.
I had actually pasted in the wrong page here. Thanks for catching this.
I previously had pasted in the wrong page here. Now it's fixed.
|
|
||
| ## Using themes other than the default {#installing-a-theme} | ||
|
|
||
| The `jekyll new <PATH>` command isn't the only way to create a new Jekyll site with a gem-based theme. You can also find gem-based themes online and incorporate them into your Jekyll project. To install a gem-based theme: |
There was a problem hiding this comment.
We could link to https://rubygems.org/search?utf8=%E2%9C%93&query=jekyll-theme to show other themes packaged as gems.
There was a problem hiding this comment.
But note that not all gem-based jekyll themes are named using that convention..
There was a problem hiding this comment.
Until we get the theme registry setup, we could link to the page showing all the themes whitelisted for GitHub Pages
There was a problem hiding this comment.
The idea was to show people that there were some gem-based themes outside of the limited number whitelisted by GitHub 😕
There was a problem hiding this comment.
i added a link in parentheses. i was unaware of the "jekyll-theme" naming style in RubyGems. Even if it's not comprehensive, it's better than nothing.
|
|
||
| If you're publishing your Jekyll site on [Github Pages](https://pages.github.com/), note that Github Pages supports only some gem-based themes. See [Supported Themes](https://pages.github.com/themes/) in Github's documentation to see which themes are supported. | ||
|
|
||
| ## Creating your own gem-based theme |
|
|
||
| Now `bundle update` will no longer get updates for the theme gem. | ||
|
|
||
| ## Using themes other than the default {#installing-a-theme} |
|
|
||
| ### Stylesheets | ||
|
|
||
| Your theme's stylesheets should be placed in your theme's `/_sass` folder, again, just as you would when authoring a Jekyll site. Your theme's styles can be included in the user's stylesheet using the `@import` directive. |
There was a problem hiding this comment.
Shouldn't we show an example here? Should we imply a convention like prefixing the gem with jekyll-theme-?
Your theme's stylesheets should be placed in your theme's /_sass folder, again, just as you would when authoring a Jekyll site.
_sass
├── jekyll-theme-my-awesome-theme.scssYour theme's styles can be included in the user's stylesheet using the @import directive.
@import "{{ site.theme }}";
There was a problem hiding this comment.
i made the update. (Note, however, that I didn't actually make any updates to that section. It was there previously.) I did just make the long paragraph a little more readable.
| @@ -71,7 +137,7 @@ For example, if your theme has a `/_layouts/page.html` file, and a page has `lay | |||
|
|
|||
| ### Assets | |||
|
|
|||
| Any file in `/assets` will be copied over to the user's site upon build unless they have a file with the same relative path. You may ship any kind of asset here: SCSS, an image, a webfont, etc. These files behave just like pages and static files in Jekyll: if the file has [YAML front matter]({{ site.baseurl }}/docs/frontmatter/) at the top, then it will be rendered. If it does not have YAML front matter, it will simply be copied over into the resulting site. This allows theme creators to ship a default `/assets/styles.scss` file which their layouts can depend on as `/assets/styles.css`. | |||
| Any file in `/assets` will be copied over to the user's site upon build unless they have a file with the same relative path. You can ship any kind of asset here: SCSS, an image, a webfont, etc. These files behave just like pages and static files in Jekyll: if the file has [YAML front matter](../docs/frontmatter/) at the top, then it will be rendered. If it does not have YAML front matter, it will simply be copied over into the resulting site. This allows theme creators to ship a default `/assets/styles.scss` file which their layouts can depend on as `/assets/styles.css`. | |||
There was a problem hiding this comment.
The correct internal link is [YAML front matter](../frontmatter/)
|
|
||
| 1. To install a theme, first, add the theme to your site's `Gemfile`: | ||
| When you [create a new Jekyll site](/docs/quickstart) (by running the `jekyll new <PATH>` command), Jekyll installs a gem-based theme called [Minima](https://github.com/jekyll/minima). | ||
|
|
There was a problem hiding this comment.
- Jekyll installs a gem-based theme called [Minima](https://github.com/jekyll/minima).
+ Jekyll installs a Site that uses a gem-based theme called [Minima](https://github.com/jekyll/minima).There was a problem hiding this comment.
updated, but why capitalize "site" here?
There was a problem hiding this comment.
no particular reason. site is just as valid as Site in this context
|
|
||
| gem 'my-awesome-jekyll-theme' | ||
| With gem-based themes, some of the theme directories and files are stored in the gem, hidden from view in your Jekyll project. As a result, the files and directories shown for your site are only part of all the theme's files. In the case of Minima, you see only the following: |
There was a problem hiding this comment.
- With gem-based themes, some of the theme directories and files are stored in the gem, hidden from view in your Jekyll project. As a result, the files and directories shown for your site are only part of all the theme's files.
+ With gem-based themes, some of the site's directories and files 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.There was a problem hiding this comment.
updated. (but had to fix the flow given the addition.)
|
|
||
| With a clear understanding of the theme's files, you can now override any theme file by creating a similarly named file in your Jekyll site directory. | ||
|
|
||
| If you want to get rid of the theme gem altogether, copy the files from the theme gem's directory into your Jekyll site directory (for example, copy them to `/myblog` if you created your Jekyll site at `/myblog`). |
There was a problem hiding this comment.
Think it would be better to have this and following paras under a sub-heading: Stop using Gem-based themes
|
|
||
| ## Using themes other than the default {#installing-a-theme} | ||
|
|
||
| The `jekyll new <PATH>` command isn't the only way to create a new Jekyll site with a gem-based theme. You can also find gem-based themes online and incorporate them into your Jekyll project. To install a gem-based theme: |
There was a problem hiding this comment.
But note that not all gem-based jekyll themes are named using that convention..
| The `jekyll new <PATH>` command isn't the only way to create a new Jekyll site with a gem-based theme. You can also find gem-based themes online and incorporate them into your Jekyll project. To install a gem-based theme: | ||
|
|
||
| 1. Add the theme to your site's `Gemfile`: | ||
|
|
There was a problem hiding this comment.
this clear line before the start of a fenced-code block is not needed actually..
There was a problem hiding this comment.
i see. i thought it was needed. however, without it, the spacing seems too smushed together.
| gem 'my-awesome-jekyll-theme' | ||
| ``` | ||
|
|
||
| 3. Install the theme: |
There was a problem hiding this comment.
continuity-error: 1 is followed by 3, then again by 3, then a 5...
|
|
||
| Jekyll themes are distributed as Ruby gems. Don't worry, Jekyll will help you scaffold a new theme with the `new-theme` command. Just run `jekyll new-theme` with the theme name as an argument: | ||
| If you're unfamiliar with distributing ruby gems, don't worry. Jekyll will help you scaffold a new theme with the `new-theme` command. Just run `jekyll new-theme` with the theme name as an argument: | ||
|
|
There was a problem hiding this comment.
This section had some changes requested in the previous PR..
There was a problem hiding this comment.
Pathawkes had said:
Scaffolding a new theme is unrelated to distributing Ruby gems. This is not one sentence
Also, you wrote:
you can package up your theme as ruby gems
Actually, I don't really mean to make controversial changes here. My main changes were in another part of this file. But I made an update to this paragraph just now to change "distributing" to "creating" and also capitalized "Ruby." Isn't Ruby capitalized, just as Java, Python, or other programming languages?
Also, the phrase "don't worry" is short enough to stand on its own.
There was a problem hiding this comment.
yes Ruby should be capitalized 👍
I made various updates as requested by the reviewers.
|
I made all the requested updates to this topic. Submitting for re-review. |
| Your theme's styles can be included in the user's stylesheet using the `@import` directive. | ||
|
|
||
| ```css | ||
| {% raw %}@import "{{ site.theme }}";{% endraw %} |
There was a problem hiding this comment.
while I'm 👍 on the use of @import "{{ site.theme }}";, lets hope it doesn't create confusion or an extra step of customization for people opting to not using gem-based themes or in the rare situation that the theme-gem doesn't name their main sass file the same as their theme-name..
| bundle install | ||
| ``` | ||
|
|
||
| 3. Add the following to your site's `_config.yml` to activate the theme: |
There was a problem hiding this comment.
Missing space at the beginning of the third list item.
|
|
||
| Jekyll will look first to your site's content, before looking to the theme's defaults, for any requested file in the following folders: | ||
| 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`). |
There was a problem hiding this comment.
(for example,
_layouts/page.html)
This 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:
by creating your own
pagelayout in the_layoutsdirectory, i.e._layouts/page.html.
Feel free to replace "i.e." with something less Latin if you would prefer.
|
|
||
| 1. Run `bundle show` followed by the name of the theme's gem, e.g., `bundle show minima` for default Jekyll's theme. | ||
|
|
||
| The location of the theme gem is returned. For example, minima is located in `/usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0` on a Mac. |
There was a problem hiding this comment.
This path is not always the path on a Mac, so I'd love to see some specificity here for our users:
is located in
/usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0when using the system Ruby installation on a Mac.
| ``` | ||
| cd /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0 | ||
| open . | ||
| # for Windows, use "explorer ." |
There was a problem hiding this comment.
Why not open /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0?
There was a problem hiding this comment.
"open" doesn't work on the Windows command terminal (at least not mine, and I have a Windows 10 PC. "explorer" does work, though.
There was a problem hiding this comment.
added examples for each OS.
On MacOS you can simply open $(bundle show minima), I leaved the full path with explorer command as I have no clue if that works under Windows.
|
|
||
| A Finder or Explorer window opens showing the theme's files and directories. | ||
|
|
||
| With a clear understanding of the theme's files, you can now override any theme file by creating a similarly named file in your Jekyll site directory. |
There was a problem hiding this comment.
Perhaps an example here would be useful. The user may still be wondering what the full path is they need to create in their site.
There was a problem hiding this comment.
good call. updated.
|
|
||
| The `jekyll new <PATH>` command isn't the only way to create a new Jekyll site with a gem-based theme. You can also find gem-based themes online and incorporate them into your Jekyll project. | ||
|
|
||
| For example, search for [jekyll-theme on RubyGems](https://rubygems.org/search?utf8=%E2%9C%93&query=jekyll-theme) to find other gem-based themes. (Note that not all themes are using `jekyll-theme` as a convention in the theme name.) |
There was a problem hiding this comment.
I would remove the hyphen and simply use "jekyll theme".
There was a problem hiding this comment.
@parkr Frank suggested querying for jekyll-theme to display the new themes supported by GitHub Pages gem
There was a problem hiding this comment.
searches for "jekyll theme" return the same as for "jekyll-theme". removing hyphen.
| You can have multiple themes listed in your site's `Gemfile`, but only one theme can be selected in your site's `_config.yml`. | ||
| {: .note .info } | ||
|
|
||
| If you're publishing your Jekyll site on [Github Pages](https://pages.github.com/), note that Github Pages supports only some gem-based themes. See [Supported Themes](https://pages.github.com/themes/) in Github's documentation to see which themes are supported. |
- most prominent update is example of how to override minima default
|
I made the updates from Parkr's review. |
|
I saw this issue: https://talk.jekyllrb.com/t/i-want-to-change-the-style-of-my-jekyll-website/3202/11. Should I add this note into the themes doc update here?
or is this a bug that we'll soon be fixing? it seems like overriding styles would be very common. |
|
@tomjohnson1492 Let's deal with later, let's merge this first. Small steps. |
@tomjohnson1492 I had also opened a dedicated issue ticket for it at #5704 You may subscribe to it and create a PR to update our documentation if that is the stance Jekyll Core takes.. |
|
If someone from @jekyll/documentation would kindly review this, it would be much appreciated ❤️ |
|
@jekyllbot: merge +doc |
* master: (39 commits) Update history to reflect merge of #5798 [ci skip] Update history to reflect merge of #5822 [ci skip] use logger.info run codeclimate after success Update history to reflect merge of #5819 [ci skip] Fixed inaccuracy in "Built-in permalink styles" docs [skip ci] Update history to reflect merge of #5802 [ci skip] Update history to reflect merge of #5811 [ci skip] Update history to reflect merge of #5690 [ci skip] Update history to reflect merge of #5815 [ci skip] Review CI pages Rework CI doc to include multiple providers. Update history to reflect merge of #5812 [ci skip] Add jekyll-ga plug-in Update configuration.md Add mention of classifier-reborn for LSI Update history to reflect merge of #5810 [ci skip] Got that diaper money? Added note about --blank flag Update history to reflect merge of #5797 [ci skip] ...
See #5630 for more details on the update.
@jekyll/documentation