dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve quickstart docs 

See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. 

@jekyll/documentation
@DirtyF
This commit is contained in:
Tom Johnson 2016-12-25 20:31:32 -08:00 committed by GitHub
parent 52c2645abb
commit 317eae5580
1 changed files with 22 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/_docs/quickstart.md
View File

@ -4,25 +4,37 @@ title: Quick-start guide
permalink: /docs/quickstart/ permalink: /docs/quickstart/
--- ---
For the impatient, here's how to get a boilerplate Jekyll site up and running. If you already have [Ruby](https://www.ruby-lang.org/en/downloads/) and [RubyGems](https://rubygems.org/pages/download) installed (see Jekyll's [requirements](/docs/installation/#requirements/)), you can create a new Jekyll site by doing the following:
```sh ```sh
# Install Jekyll and Bundler gems through RubyGems
~ $ gem install jekyll bundler ~ $ gem install jekyll bundler
# Create a new Jekyll site at ./myblog
~ $ jekyll new myblog ~ $ jekyll new myblog
# Change into your new directory
~ $ cd myblog ~ $ cd myblog
# Build the site on the preview server
~/myblog $ bundle exec jekyll serve ~/myblog $ bundle exec jekyll serve
# => Now browse to http://localhost:4000
# Now browse to http://localhost:4000
``` ```
The `jekyll new` command now automatically initiates `bundle install` and installs the dependencies required. To skip this, pass `--skip-bundle` option like so `jekyll new myblog --skip-bundle`. `gem install jekyll bundler` installs the [jekyll](https://rubygems.org/gems/jekyll/) and [bundler](https://rubygems.org/gems/bundler) gems through [RubyGems](https://rubygems.org/). You need only to install the gems one time — not every time you create a new Jekyll project. Here are some additional details:
If you wish to install jekyll into an existing directory, you can do so by running `jekyll new .` from within the directory instead of creating a new one. If the existing directory isn't empty, you'll also have to pass the `--force` option like so `jekyll new . --force`. * `bundler` is a gem that manages other Ruby gems. It makes sure your gems and gem versions are compatible, and that you have all necessary dependencies each gem requires.
* The `Gemfile` and `Gemfile.lock` files inform Bundler about the gem requirements in your theme. If your theme doesn't have these Gemfiles, you can omit `bundle exec` and just run `jekyll serve`.
That's nothing, though. The real magic happens when you start creating blog * When you run `bundle exec jekyll serve`, Bundler uses the gems and versions as specified in `Gemfile.lock` to ensure your Jekyll site builds with no compatibility or dependency conflicts.
posts, using the front matter to control templates and layouts, and taking
advantage of all the awesome configuration options Jekyll makes available.
If you're running into problems, ensure you have all the [requirements `jekyll new <PATH>` installs a new Jekyll site at the path specified (relative to current directory). In this case, Jekyll will be installed in a directory called `myblog`. Here are some additional details:
installed][Installation].
[Installation]: /docs/installation/ * To install the Jekyll site into the directory you're currently in, run `jekyll new .` If the existing directory isn't empty, you can pass the `--force` option with `jekyll new . --force`.
* `jekyll new` automatically initiates `bundle install` to install the dependencies required. (If you don't want Bundler to install the gems, use `jekyll new myblog --skip-bundle`.)
* By default, Jekyll installs a gem-based theme called [Minima](https://github.com/jekyll/minima). With gem-based themes, some of the theme directories and files are stored in the gem, hidden from view in your Jekyll project. To better understand themes, see [Themes](../themes).
## Next steps
Building the default theme is just the first step. The real magic happens when you start creating blog posts, using the front matter to control templates and layouts, and taking advantage of all the awesome configuration options Jekyll makes available.