Improve quickstart docs #5689

tomjoht · 2016-12-26T04:32:04Z

See #5630 for more details on the update.

@jekyll/documentation

@DirtyF

See #5630 for more details on the update. @jekyll/documentation @DirtyF

DirtyF · 2016-12-26T10:04:35Z

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.


Building a Jekyll site with the default theme…

DirtyF · 2016-12-26T10:27:45Z

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 &mdash; 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 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

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.

DirtyF · 2016-12-26T10:34:30Z

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).


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

- * 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.

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 requested updates.

tomjoht · 2016-12-27T04:40:23Z

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

ashmaroli · 2016-12-27T05:50:12Z

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.



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

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.

ashmaroli · 2016-12-27T05:52:15Z

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


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

or Options for creating a new site with Jekyll?

DirtyF

Great!

ashmaroli

👍

parkr

Great! Thanks for this. Just one comment. 📝

parkr · 2016-12-29T05:11:33Z

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 &mdash; 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`.


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 · 2016-12-29T05:19:20Z

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`.


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.

made requested fixes

tomjoht · 2016-12-29T07:46:40Z

Made fixes from review.

parkr

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

I must have just updated the wrong doc or branch in the last commit. i hope this fixes it.

ashmaroli · 2016-12-29T16:29:38Z

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

ashmaroli · 2016-12-29T16:38:58Z

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

…t seem to remove it from the previous commit.

tomjoht · 2016-12-29T17:04:43Z

@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 · 2016-12-29T17:16:27Z

The following is for command-line console:

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

ashmaroli · 2016-12-29T17:25:33Z

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

parkr · 2016-12-29T19:31:02Z

@jekyllbot: merge +site

parkr · 2016-12-29T19:55:17Z

/cc parkr/auto-reply#20

parkr · 2016-12-30T03:02:52Z

@jekyllbot: merge +site

Improve quickstart docs

317eae5

See #5630 for more details on the update. @jekyll/documentation @DirtyF

jekyllbot assigned DirtyF and parkr Dec 26, 2016

DirtyF added the documentation label Dec 26, 2016

DirtyF reviewed Dec 26, 2016

View reviewed changes

Made updates as requested by reviewers

190ea16

Made requested updates.

ashmaroli requested changes Dec 27, 2016

View reviewed changes

added info about jekyll new --help

adc619c

DirtyF approved these changes Dec 28, 2016

View reviewed changes

ashmaroli approved these changes Dec 29, 2016

View reviewed changes

parkr requested changes Dec 29, 2016

View reviewed changes

parkr reviewed Dec 29, 2016

View reviewed changes

made fixes

391bf5d

made requested fixes

parkr approved these changes Dec 29, 2016

View reviewed changes

parkr requested changes Dec 29, 2016

View reviewed changes

update quickstart.md

57d6d59

I must have just updated the wrong doc or branch in the last commit. i hope this fixes it.

DirtyF approved these changes Dec 29, 2016

View reviewed changes

reset permalinks to same state it was in in patch-3 branch. i couldn'…

192e79e

…t seem to remove it from the previous commit.

parkr approved these changes Dec 29, 2016

View reviewed changes

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

jekyllbot added the documentation label Dec 30, 2016

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

Update history to reflect merge of #5689 [ci skip]

0014b1d

jekyll locked and limited conversation to collaborators Jul 11, 2019

jekyllbot added the frozen-due-to-age label Jul 11, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve quickstart docs #5689

Improve quickstart docs #5689

tomjoht commented Dec 26, 2016 •

edited by DirtyF

Loading

DirtyF Dec 26, 2016

tomjoht Dec 27, 2016

DirtyF Dec 26, 2016 •

edited

Loading

tomjoht Dec 27, 2016

DirtyF left a comment

DirtyF Dec 26, 2016

ashmaroli Dec 26, 2016

tomjoht Dec 27, 2016

tomjoht commented Dec 27, 2016

ashmaroli Dec 27, 2016

tomjoht Dec 28, 2016

ashmaroli Dec 27, 2016 •

edited

Loading

DirtyF Dec 28, 2016 •

edited

Loading

tomjoht Dec 28, 2016

DirtyF left a comment

ashmaroli left a comment

parkr left a comment

parkr Dec 29, 2016

tomjoht Dec 29, 2016

parkr Dec 29, 2016

tomjoht Dec 29, 2016

tomjoht commented Dec 29, 2016

parkr left a comment

ashmaroli commented Dec 29, 2016

ashmaroli commented Dec 29, 2016 •

edited

Loading

tomjoht commented Dec 29, 2016

ashmaroli commented Dec 29, 2016

ashmaroli commented Dec 29, 2016

parkr commented Dec 29, 2016

parkr commented Dec 29, 2016

parkr commented Dec 30, 2016


		[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.


		* 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

Improve quickstart docs #5689

Improve quickstart docs #5689

Conversation

tomjoht commented Dec 26, 2016 • edited by DirtyF Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DirtyF Dec 26, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DirtyF left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomjoht commented Dec 27, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ashmaroli Dec 27, 2016 • edited Loading

Choose a reason for hiding this comment

DirtyF Dec 28, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DirtyF left a comment

Choose a reason for hiding this comment

ashmaroli left a comment

Choose a reason for hiding this comment

parkr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomjoht commented Dec 29, 2016

parkr left a comment

Choose a reason for hiding this comment

ashmaroli commented Dec 29, 2016

ashmaroli commented Dec 29, 2016 • edited Loading

tomjoht commented Dec 29, 2016

ashmaroli commented Dec 29, 2016

ashmaroli commented Dec 29, 2016

parkr commented Dec 29, 2016

parkr commented Dec 29, 2016

parkr commented Dec 30, 2016

tomjoht commented Dec 26, 2016 •

edited by DirtyF

Loading

DirtyF Dec 26, 2016 •

edited

Loading

ashmaroli Dec 27, 2016 •

edited

Loading

DirtyF Dec 28, 2016 •

edited

Loading

ashmaroli commented Dec 29, 2016 •

edited

Loading