Improve quickstart docs #5689

Merged
merged 6 commits into from Dec 30, 2016

Conversation

Projects
None yet
6 participants
@tomjoht
Contributor

tomjoht commented Dec 26, 2016

See #5630 for more details on the update.

@jekyll/documentation

Improve quickstart docs
See #5630 for more details on the update. 

@jekyll/documentation
@DirtyF
docs/_docs/quickstart.md
-[Installation]: /docs/installation/
+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.

This comment has been minimized.

@DirtyF

DirtyF Dec 26, 2016

Member

Building a Jekyll site with the default theme…

@DirtyF

DirtyF Dec 26, 2016

Member

Building a Jekyll site with the default theme…

This comment has been minimized.

@tomjoht

tomjoht Dec 27, 2016

Contributor

updated

@tomjoht

tomjoht Dec 27, 2016

Contributor

updated

docs/_docs/quickstart.md
-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:
+
+* `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.

This comment has been minimized.

@DirtyF

DirtyF Dec 26, 2016

Member

This page aims to give a few instructions to get going. Detailed explanations are fine, we could split this in small sections:

## For the impatient
...
## For the curious

or

## About bundler
...
## Jekyll new options
@DirtyF

DirtyF Dec 26, 2016

Member

This page aims to give a few instructions to get going. Detailed explanations are fine, we could split this in small sections:

## For the impatient
...
## For the curious

or

## About bundler
...
## Jekyll new options

This comment has been minimized.

@tomjoht

tomjoht Dec 27, 2016

Contributor

good call. i made the updates (using the latter headings).

@tomjoht

tomjoht Dec 27, 2016

Contributor

good call. i made the updates (using the latter headings).

@DirtyF

Useful additions for the first-timers indeed, but let's keep this page easily scannable.

docs/_docs/quickstart.md
-advantage of all the awesome configuration options Jekyll makes available.
+* 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).

This comment has been minimized.

@DirtyF

DirtyF Dec 26, 2016

Member

We could make the link to themes docmentation on gem-based themes and avoid the last sentence.

@DirtyF

DirtyF Dec 26, 2016

Member

We could make the link to themes docmentation on gem-based themes and avoid the last sentence.

This comment has been minimized.

@ashmaroli

ashmaroli Dec 26, 2016

Member
- * 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).
+ * By default, the Jekyll site installed by `jekyll new` uses a gem-based theme called [Minima](https://github.com/jekyll/minima).  
+   With [gem-based themes](../themes), some of the directories and files are stored in the theme-gem, hidden from your immediate view.
@ashmaroli

ashmaroli Dec 26, 2016

Member
- * 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).
+ * By default, the Jekyll site installed by `jekyll new` uses a gem-based theme called [Minima](https://github.com/jekyll/minima).  
+   With [gem-based themes](../themes), some of the directories and files are stored in the theme-gem, hidden from your immediate view.

This comment has been minimized.

@tomjoht

tomjoht Dec 27, 2016

Contributor

updated. i think the subheadings and bullets facilitate scanning enough. the code sample is at the top, so users don't have to read beyond that code sample to get things running. but i wouldn't recommend reducing explanations of the code in the goal of making it seem simpler. we run the risk of making the code too cryptic.

if anything, i'd cut the bullets about skipping bundler or forcing jekyll to install in a folder that already has content in it. i don't see much use for those two options, but i think it's okay to have them there.

@tomjoht

tomjoht Dec 27, 2016

Contributor

updated. i think the subheadings and bullets facilitate scanning enough. the code sample is at the top, so users don't have to read beyond that code sample to get things running. but i wouldn't recommend reducing explanations of the code in the goal of making it seem simpler. we run the risk of making the code too cryptic.

if anything, i'd cut the bullets about skipping bundler or forcing jekyll to install in a folder that already has content in it. i don't see much use for those two options, but i think it's okay to have them there.

Made updates as requested by reviewers
Made requested updates.
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Dec 27, 2016

Contributor

I made the requested updates. Submitting for re-review.

Contributor

tomjoht commented Dec 27, 2016

I made the requested updates. Submitting for re-review.

docs/_docs/quickstart.md
-advantage of all the awesome configuration options Jekyll makes available.
+* 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, the Jekyll site installed by `jekyll new` uses a gem-based theme called [Minima](https://github.com/jekyll/minima). With [gem-based themes](../themes), some of the directories and files are stored in the theme-gem, hidden from your immediate view.

This comment has been minimized.

@ashmaroli

ashmaroli Dec 27, 2016

Member

might as well include a point on jekyll new [PATH] --blank since we've a section just for options with jekyll new.. 😉

@ashmaroli

ashmaroli Dec 27, 2016

Member

might as well include a point on jekyll new [PATH] --blank since we've a section just for options with jekyll new.. 😉

This comment has been minimized.

@tomjoht

tomjoht Dec 28, 2016

Contributor

I added info about jekyll new -- help, but I don't think adding info about the --blank parameter is useful here. This is a quickstart for newbies. The --blank parameter is for advanced users who wouldn't be using this documentation in the first place. The --blank parameter doesn't even create a _config.yml file. I don't really see how --blank is all that useful.

@tomjoht

tomjoht Dec 28, 2016

Contributor

I added info about jekyll new -- help, but I don't think adding info about the --blank parameter is useful here. This is a quickstart for newbies. The --blank parameter is for advanced users who wouldn't be using this documentation in the first place. The --blank parameter doesn't even create a _config.yml file. I don't really see how --blank is all that useful.

docs/_docs/quickstart.md
+
+* 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.
+
+## Jekyll new options

This comment has been minimized.

@ashmaroli

ashmaroli Dec 27, 2016

Member
- ## Jekyll new options
+ ## Jekyll-new options
@ashmaroli

ashmaroli Dec 27, 2016

Member
- ## Jekyll new options
+ ## Jekyll-new options

This comment has been minimized.

@DirtyF

DirtyF Dec 28, 2016

Member

or Options for creating a new site with Jekyll?

@DirtyF

DirtyF Dec 28, 2016

Member

or Options for creating a new site with Jekyll?

This comment has been minimized.

@tomjoht

tomjoht Dec 28, 2016

Contributor

updated

@tomjoht

tomjoht Dec 28, 2016

Contributor

updated

@DirtyF

DirtyF approved these changes Dec 28, 2016

Great!

@ashmaroli

👍

@parkr

Great! Thanks for this. Just one comment. 📝

docs/_docs/quickstart.md
+`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:
+
+* `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`.

This comment has been minimized.

@parkr

parkr Dec 29, 2016

Member

the gem requirements in your theme. If your theme doesn't have these Gemfiles, you can omit bundle exec and just run jekyll serve.

I believe this should be site not theme, as we're creating a site in the example above.

@parkr

parkr Dec 29, 2016

Member

the gem requirements in your theme. If your theme doesn't have these Gemfiles, you can omit bundle exec and just run jekyll serve.

I believe this should be site not theme, as we're creating a site in the example above.

This comment has been minimized.

@tomjoht

tomjoht Dec 29, 2016

Contributor

updated

@tomjoht

tomjoht Dec 29, 2016

Contributor

updated

docs/_docs/quickstart.md
+* 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, the Jekyll site installed by `jekyll new` uses a gem-based theme called [Minima](https://github.com/jekyll/minima). With [gem-based themes](../themes), some of the directories and files are stored in the theme-gem, hidden from your immediate view.
+* To learn about other parameters you can include with `jekyll new`, type ` jekyll new --help`.

This comment has been minimized.

@parkr

parkr Dec 29, 2016

Member

Please remove the extra space before "jekyll new --help". It causes the backticks to go in plain instead of causing this to become a <code> segment.

@parkr

parkr Dec 29, 2016

Member

Please remove the extra space before "jekyll new --help". It causes the backticks to go in plain instead of causing this to become a <code> segment.

This comment has been minimized.

@tomjoht

tomjoht Dec 29, 2016

Contributor

fixed

@tomjoht

tomjoht Dec 29, 2016

Contributor

fixed

made fixes
made requested fixes
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Dec 29, 2016

Contributor

Made fixes from review.

Contributor

tomjoht commented Dec 29, 2016

Made fixes from review.

@parkr

parkr approved these changes Dec 29, 2016

@parkr

Please update quickstart.md instead of permalinks.md. Thanks!

update quickstart.md
I must have just updated the wrong doc or branch in the last commit. i hope this fixes it.
@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Dec 29, 2016

Member

i would suggest using git reset --hard adc619c and reapplying the latest fixes to quickstart.md instead of adding another commit to undo the mistake

Member

ashmaroli commented Dec 29, 2016

i would suggest using git reset --hard adc619c and reapplying the latest fixes to quickstart.md instead of adding another commit to undo the mistake

@DirtyF

DirtyF approved these changes Dec 29, 2016

@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Dec 29, 2016

Member

@DirtyF Tom has mistakenly copied contents of quickstart.md to permalinks.md

Member

ashmaroli commented Dec 29, 2016

@DirtyF Tom has mistakenly copied contents of quickstart.md to permalinks.md

reset permalinks to same state it was in in patch-3 branch. i couldn'…
…t seem to remove it from the previous commit.
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Dec 29, 2016

Contributor

@ashmaroli Sorry about this. I tried using git reset --hard adc619c but I got this error msg:

hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.

I'd been just using the Github GUI to switch branches and paste in the changes for a specific page. On my local, I have a running build with comprehensive changes for all branches. I should really probably just be switching around branches on my local and committing that way, but I was trying to simplify things and got into using the GUI.

I reverted the permalinks doc to the patch-3 state, which should be unmodified. However, now if this PR gets merged after the permalinks PR, it will screw up the permalinks PR. Any advice?

Contributor

tomjoht commented Dec 29, 2016

@ashmaroli Sorry about this. I tried using git reset --hard adc619c but I got this error msg:

hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.

I'd been just using the Github GUI to switch branches and paste in the changes for a specific page. On my local, I have a running build with comprehensive changes for all branches. I should really probably just be switching around branches on my local and committing that way, but I was trying to simplify things and got into using the GUI.

I reverted the permalinks doc to the patch-3 state, which should be unmodified. However, now if this PR gets merged after the permalinks PR, it will screw up the permalinks PR. Any advice?

@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Dec 29, 2016

Member

The following is for command-line console:

  1. git reset --hard adc619c
  2. Apply fixes
  3. git add docs/_docs/quickstart.md
  4. git commit
  5. git push -f origin patch-3
Member

ashmaroli commented Dec 29, 2016

The following is for command-line console:

  1. git reset --hard adc619c
  2. Apply fixes
  3. git add docs/_docs/quickstart.md
  4. git commit
  5. git push -f origin patch-3
@ashmaroli

This comment has been minimized.

Show comment
Hide comment
@ashmaroli

ashmaroli Dec 29, 2016

Member

on second-thought, leave things as they are.. It looks good to merge now..

Member

ashmaroli commented Dec 29, 2016

on second-thought, leave things as they are.. It looks good to merge now..

@parkr

parkr approved these changes Dec 29, 2016

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Dec 29, 2016

Member

@jekyllbot: merge +site

Member

parkr commented Dec 29, 2016

@jekyllbot: merge +site

@parkr

This comment has been minimized.

Show comment
Hide comment
Member

parkr commented Dec 29, 2016

@parkr

This comment has been minimized.

Show comment
Hide comment
@parkr

parkr Dec 30, 2016

Member

@jekyllbot: merge +site

Member

parkr commented Dec 30, 2016

@jekyllbot: merge +site

@jekyllbot jekyllbot merged commit 817c9f6 into jekyll:master Dec 30, 2016

0 of 2 checks passed

continuous-integration/appveyor/pr AppVeyor build failed
Details
continuous-integration/travis-ci/pr The Travis CI build failed
Details

jekyllbot added a commit that referenced this pull request Dec 30, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment