Fix format, corrections
This commit is contained in:
Frank Taillandier
parent
90da02b1fc
commit
234ed44db6
|
|
@ -10,7 +10,7 @@ Jekyll has an extensive theme system that allows you to leverage community-maint
|
|||
|
||||
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).
|
||||
|
||||
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.
|
||||
With gem-based themes, some of the site's directories (such as the `assets`, `_layouts`, `_includes`, and `_sass` directories) are stored in the theme's gem, hidden from your immediate view. Yet all of the necessary directories will be read and processed during Jekyll's build process.
|
||||
|
||||
In the case of Minima, you see only the following files in your Jekyll site directory:
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ In the case of Minima, you see only the following files in your Jekyll site dire
|
|||
├── Gemfile.lock
|
||||
├── _config.yml
|
||||
├── _posts
|
||||
│ └── 2016-12-04-welcome-to-jekyll.markdown
|
||||
│ └── 2016-12-04-welcome-to-jekyll.markdown
|
||||
├── about.md
|
||||
└── index.md
|
||||
```
|
||||
|
|
@ -28,7 +28,7 @@ The `Gemfile` and `Gemfile.lock` files are used by Bundler to keep track of the
|
|||
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -40,10 +40,10 @@ For example, if your selected theme has a `page` layout, you can override the th
|
|||
|
||||
Jekyll will look first to your site's content before looking to the theme's defaults for any requested file in the following folders:
|
||||
|
||||
* `/assets`
|
||||
* `/_layouts`
|
||||
* `/_includes`
|
||||
* `/_sass`
|
||||
- `/assets`
|
||||
- `/_layouts`
|
||||
- `/_includes`
|
||||
- `/_sass`
|
||||
|
||||
Refer to your selected theme's documentation and source repository for more information on what files you can override.
|
||||
{: .note .info}
|
||||
|
|
@ -52,14 +52,15 @@ To locate theme's files on your computer:
|
|||
|
||||
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` when using the system Ruby installation on a Mac.
|
||||
This returns the location of the gem-based theme files. For example, Minima theme's files are located in `/usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0` on macOS.
|
||||
|
||||
2. Change to the directory's location and open the directory in Finder or Explorer:
|
||||
2. Open the theme's directory in Finder or Explorer:
|
||||
|
||||
```
|
||||
cd /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0
|
||||
open .
|
||||
# for Windows, use "explorer ."
|
||||
```shell
|
||||
# On MacOS
|
||||
open $(bundle show minima)
|
||||
# On Windows
|
||||
explorer /usr/local/lib/ruby/gems/2.3.0/gems/minima-2.1.0
|
||||
```
|
||||
|
||||
A Finder or Explorer window opens showing the theme's files and directories. The Minima theme gem contains these files:
|
||||
|
|
@ -102,9 +103,10 @@ Suppose you want to get rid of the gem-based theme and convert it to a regular t
|
|||
|
||||
To do this, 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`. See the previous section for details.)
|
||||
|
||||
Then modify the Gemfile and configuration to remove references to the theme gem. For example, to remove Minima:
|
||||
* Open `Gemfile` and remove `gem "minima", "~> 2.0"`.
|
||||
* Open `_config.yml` and remove `theme: minima`.
|
||||
Then remove references to the theme gem in `Gemfile` and configuration. For example, to remove `minima`:
|
||||
|
||||
- Open `Gemfile` and remove `gem "minima", "~> 2.0"`.
|
||||
- Open `_config.yml` and remove `theme: minima`.
|
||||
|
||||
Now `bundle update` will no longer get updates for the theme gem.
|
||||
|
||||
|
|
@ -119,7 +121,7 @@ To install a gem-based theme:
|
|||
1. Add the theme to your site's `Gemfile`:
|
||||
|
||||
```sh
|
||||
gem 'my-awesome-jekyll-theme'
|
||||
gem "jekyll-theme-awesome"
|
||||
```
|
||||
|
||||
2. Install the theme:
|
||||
|
|
@ -131,7 +133,7 @@ To install a gem-based theme:
|
|||
3. Add the following to your site's `_config.yml` to activate the theme:
|
||||
|
||||
```sh
|
||||
theme: my-awesome-jekyll-theme
|
||||
theme: jekyll-theme-awesome
|
||||
```
|
||||
|
||||
4. Build your site:
|
||||
|
|
@ -140,8 +142,7 @@ To install a gem-based theme:
|
|||
bundle exec jekyll serve
|
||||
```
|
||||
|
||||
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 }
|
||||
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.
|
||||
|
||||
|
|
@ -149,24 +150,26 @@ If you're publishing your Jekyll site on [GitHub Pages](https://pages.github.com
|
|||
|
||||
If you're a Jekyll theme developer (rather than just a consumer of themes), you can package up your theme in RubyGems and allow users to install it through Bundler.
|
||||
|
||||
If you're unfamiliar with creating 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 creating Ruby gems, don't worry. Jekyll will help you scaffold a new theme with the `new-theme` command. Run `jekyll new-theme` with the theme name as an argument.
|
||||
|
||||
Here is an example:
|
||||
|
||||
```sh
|
||||
jekyll new-theme my-awesome-theme
|
||||
create /path/to/my-awesome-theme/_layouts
|
||||
create /path/to/my-awesome-theme/_includes
|
||||
create /path/to/my-awesome-theme/_sass
|
||||
create /path/to/my-awesome-theme/_layouts/page.html
|
||||
create /path/to/my-awesome-theme/_layouts/post.html
|
||||
create /path/to/my-awesome-theme/_layouts/default.html
|
||||
create /path/to/my-awesome-theme/Gemfile
|
||||
create /path/to/my-awesome-theme/my-awesome-theme.gemspec
|
||||
create /path/to/my-awesome-theme/README.md
|
||||
create /path/to/my-awesome-theme/LICENSE.txt
|
||||
initialize /path/to/my-awesome-theme/.git
|
||||
create /path/to/my-awesome-theme/.gitignore
|
||||
Your new Jekyll theme, my-awesome-theme, is ready for you in /path/to/my-awesome-theme!
|
||||
For help getting started, read /path/to/my-awesome-theme/README.md.
|
||||
jekyll new-theme jekyll-theme-awesome
|
||||
create /path/to/jekyll-theme-awesome/_layouts
|
||||
create /path/to/jekyll-theme-awesome/_includes
|
||||
create /path/to/jekyll-theme-awesome/_sass
|
||||
create /path/to/jekyll-theme-awesome/_layouts/page.html
|
||||
create /path/to/jekyll-theme-awesome/_layouts/post.html
|
||||
create /path/to/jekyll-theme-awesome/_layouts/default.html
|
||||
create /path/to/jekyll-theme-awesome/Gemfile
|
||||
create /path/to/jekyll-theme-awesome/jekyll-theme-awesome.gemspec
|
||||
create /path/to/jekyll-theme-awesome/README.md
|
||||
create /path/to/jekyll-theme-awesome/LICENSE.txt
|
||||
initialize /path/to/jekyll-theme-awesome/.git
|
||||
create /path/to/jekyll-theme-awesome/.gitignore
|
||||
Your new Jekyll theme, jekyll-theme-awesome, is ready for you in /path/to/jekyll-theme-awesome!
|
||||
For help getting started, read /path/to/jekyll-theme-awesome/README.md.
|
||||
```
|
||||
|
||||
Add your template files in the corresponding folders. Then complete the `.gemspec` and the README files according to your needs.
|
||||
|
|
@ -179,10 +182,10 @@ 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 can ship any kind of asset here: SCSS, an image, a webfont, etc. These files behave just like pages and static files in Jekyll:
|
||||
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 like pages and static files in Jekyll:
|
||||
|
||||
* If the file has [YAML front matter](../docs/frontmatter/) at the top, it will be rendered.
|
||||
* If the file does not have YAML front matter, it will simply be copied over into the resulting site.
|
||||
- If the file has [YAML front matter](../docs/frontmatter/) at the top, it will be rendered.
|
||||
- If the file 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`.
|
||||
|
||||
|
|
@ -193,8 +196,8 @@ All files in `/assets` will be output into the compiled site in the `/assets` fo
|
|||
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.scss
|
||||
_sass
|
||||
├── jekyll-theme-awesome.scss
|
||||
```
|
||||
|
||||
Your theme's styles can be included in the user's stylesheet using the `@import` directive.
|
||||
|
|
@ -215,20 +218,22 @@ Themes are visual. Show users what your theme looks like by including a screensh
|
|||
|
||||
To preview your theme as you're authoring it, it may be helpful to add dummy content in, for example, `/index.html` and `/page.html` files. This will allow you to use the `jekyll build` and `jekyll serve` commands to preview your theme, just as you'd preview a Jekyll site.
|
||||
|
||||
If you do preview your theme locally, be sure to add `/_site` to your theme's `.gitignore` file to prevent the compiled site from also being included when you distribute your theme.
|
||||
{: .info .note}
|
||||
If you do preview your theme locally, be sure to add `/_site` to your theme's `.gitignore` file to prevent the compiled site from also being included when you distribute your theme. {: .info .note}
|
||||
|
||||
### Publishing your theme
|
||||
|
||||
Themes are published via [RubyGems.org](https://rubygems.org). You'll need a RubyGems account, which you can [create for free](https://rubygems.org/sign_up).
|
||||
Themes are published via [RubyGems.org](https://rubygems.org). You will need a RubyGems account, which you can [create for free](https://rubygems.org/sign_up).
|
||||
|
||||
1. First, package your theme, by running the following command, replacing `my-awesome-jekyll-theme` with the name of your theme:
|
||||
1. First, package your theme, by running the following command, replacing `jekyll-theme-awesome` with the name of your theme:
|
||||
|
||||
gem build my-awesome-jekyll-theme.gemspec
|
||||
```sh
|
||||
gem build jekyll-theme-awesome.gemspec
|
||||
```
|
||||
|
||||
2. Next, push your packaged theme up to the RubyGems service, by running the following command, again replacing `my-awesome-jekyll-theme` with the name of your theme:
|
||||
2. Next, push your packaged theme up to the RubyGems service, by running the following command, again replacing `jekyll-theme-awesome` with the name of your theme:
|
||||
|
||||
gem push my-awesome-jekyll-theme-*.gem
|
||||
```sh
|
||||
gem push jekyll-theme-awesome-*.gem
|
||||
```
|
||||
|
||||
3. To release a new version of your theme, simply update the version number in the gemspec file, ( `my-awesome-jekyll-theme.gemspec` in this example ), and then repeat Steps 1 & 2 above.
|
||||
We recommend that you follow [Semantic Versioning](http://semver.org/) while bumping your theme-version.
|
||||
3. To release a new version of your theme, update the version number in the gemspec file, ( `jekyll-theme-awesome.gemspec` in this example ), and then repeat Steps 1 & 2 above. We recommend that you follow [Semantic Versioning](http://semver.org/) while bumping your theme-version.
|
||||
|
|
|
|||
Loading…
Reference in New Issue