From 704910b297a833cb2e03c433d800d4eaf7e29c7a Mon Sep 17 00:00:00 2001 From: Nursen Date: Fri, 23 Dec 2016 14:08:54 -0800 Subject: [PATCH 01/19] Update windows.md Added an update to installation instructions, as a cert authority change in Ruby causes problems with the prior recommended version of Ruby. --- docs/_docs/windows.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/_docs/windows.md b/docs/_docs/windows.md index ab536382..0426a4de 100644 --- a/docs/_docs/windows.md +++ b/docs/_docs/windows.md @@ -20,6 +20,9 @@ For a more conventional way of installing Jekyll you can follow this [complete g [windows-installjekyll3]: https://labs.sverrirs.com/jekyll/ +\[Update 12/23/2016\]: Updates in the infrastructure of Ruby may cause SLL errors when attemptying to use gem install on a version of ruby older than 2.6. (The ruby package installed via the Chocolatey tool is version 2.3) If you have installed an older version, you can update ruby using the directions [here.][ssl-certificate-update] +[ssl-certificate-update]: http://guides.rubygems.org/ssl-certificate-update/#installing-using-update-packages + ## Encoding If you use UTF-8 encoding, make sure that no `BOM` header From 467f0a13714e68153161366d4c5fcd27c868fd85 Mon Sep 17 00:00:00 2001 From: Nursen Date: Sat, 24 Dec 2016 01:22:55 -0800 Subject: [PATCH 02/19] Update windows.md revising terminology to avoid ambiguity and moving in relation to alternative install instructions. --- docs/_docs/windows.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/_docs/windows.md b/docs/_docs/windows.md index 0426a4de..7d6db10c 100644 --- a/docs/_docs/windows.md +++ b/docs/_docs/windows.md @@ -16,13 +16,13 @@ A quick way to install Jekyll is to follow the [installation instructions by Dav 2. Install Ruby via Chocolatey: `choco install ruby -y` 3. Reopen a command prompt and install Jekyll: `gem install jekyll` +Updates in the infrastructure of Ruby may cause SLL errors when attempting to use `gem install` on a version of the RubyGems package older than 2.6. (The RubyGems package installed via the Chocolatey tool is version 2.3) If you have installed an older version, you can update the RubyGems package using the directions [here.][ssl-certificate-update] +[ssl-certificate-update]: http://guides.rubygems.org/ssl-certificate-update/#installing-using-update-packages + For a more conventional way of installing Jekyll you can follow this [complete guide to install Jekyll 3 on Windows by Sverrir Sigmundarson][windows-installjekyll3]. [windows-installjekyll3]: https://labs.sverrirs.com/jekyll/ -\[Update 12/23/2016\]: Updates in the infrastructure of Ruby may cause SLL errors when attemptying to use gem install on a version of ruby older than 2.6. (The ruby package installed via the Chocolatey tool is version 2.3) If you have installed an older version, you can update ruby using the directions [here.][ssl-certificate-update] -[ssl-certificate-update]: http://guides.rubygems.org/ssl-certificate-update/#installing-using-update-packages - ## Encoding If you use UTF-8 encoding, make sure that no `BOM` header From 80d3c7a20495b59dc1cd598065ba337ce6b274d9 Mon Sep 17 00:00:00 2001 From: Nursen Date: Sat, 24 Dec 2016 01:25:03 -0800 Subject: [PATCH 03/19] Update windows.md fixing typo --- docs/_docs/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/windows.md b/docs/_docs/windows.md index 7d6db10c..514730eb 100644 --- a/docs/_docs/windows.md +++ b/docs/_docs/windows.md @@ -16,7 +16,7 @@ A quick way to install Jekyll is to follow the [installation instructions by Dav 2. Install Ruby via Chocolatey: `choco install ruby -y` 3. Reopen a command prompt and install Jekyll: `gem install jekyll` -Updates in the infrastructure of Ruby may cause SLL errors when attempting to use `gem install` on a version of the RubyGems package older than 2.6. (The RubyGems package installed via the Chocolatey tool is version 2.3) If you have installed an older version, you can update the RubyGems package using the directions [here.][ssl-certificate-update] +Updates in the infrastructure of Ruby may cause SSL errors when attempting to use `gem install` on a version of the RubyGems package older than 2.6. (The RubyGems package installed via the Chocolatey tool is version 2.3) If you have installed an older version, you can update the RubyGems package using the directions [here.][ssl-certificate-update] [ssl-certificate-update]: http://guides.rubygems.org/ssl-certificate-update/#installing-using-update-packages For a more conventional way of installing Jekyll you can follow this [complete guide to install Jekyll 3 on Windows by Sverrir Sigmundarson][windows-installjekyll3]. From d442c4fe137a217f838ce3fde7aabce398b2c245 Mon Sep 17 00:00:00 2001 From: Nursen Date: Sat, 24 Dec 2016 02:16:20 -0800 Subject: [PATCH 04/19] Update windows.md --- docs/_docs/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/windows.md b/docs/_docs/windows.md index 514730eb..8d7bb8bc 100644 --- a/docs/_docs/windows.md +++ b/docs/_docs/windows.md @@ -16,7 +16,7 @@ A quick way to install Jekyll is to follow the [installation instructions by Dav 2. Install Ruby via Chocolatey: `choco install ruby -y` 3. Reopen a command prompt and install Jekyll: `gem install jekyll` -Updates in the infrastructure of Ruby may cause SSL errors when attempting to use `gem install` on a version of the RubyGems package older than 2.6. (The RubyGems package installed via the Chocolatey tool is version 2.3) If you have installed an older version, you can update the RubyGems package using the directions [here.][ssl-certificate-update] +Updates in the infrastructure of Ruby may cause SSL errors when attempting to use `gem install` with versions of the RubyGems package older than 2.6. (The RubyGems package installed via the Chocolatey tool is version 2.3) If you have installed an older version, you can update the RubyGems package using the directions [here.][ssl-certificate-update] [ssl-certificate-update]: http://guides.rubygems.org/ssl-certificate-update/#installing-using-update-packages For a more conventional way of installing Jekyll you can follow this [complete guide to install Jekyll 3 on Windows by Sverrir Sigmundarson][windows-installjekyll3]. From 317eae55802e637663bc880b72961a2aff68cd3e Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 25 Dec 2016 20:31:32 -0800 Subject: [PATCH 05/19] Improve quickstart docs See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. @jekyll/documentation @DirtyF --- docs/_docs/quickstart.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/docs/_docs/quickstart.md b/docs/_docs/quickstart.md index 969b5384..c2d0e79d 100644 --- a/docs/_docs/quickstart.md +++ b/docs/_docs/quickstart.md @@ -4,25 +4,37 @@ title: Quick-start guide 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 +# Install Jekyll and Bundler gems through RubyGems ~ $ gem install jekyll bundler + +# Create a new Jekyll site at ./myblog ~ $ jekyll new myblog + +# Change into your new directory ~ $ cd myblog + +# Build the site on the preview server ~/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 -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. -If you're running into problems, ensure you have all the [requirements -installed][Installation]. +`jekyll new ` 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: -[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. From 190ea160e50b0e6427212795bc5d38ee7c53075e Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 20:40:07 -0800 Subject: [PATCH 06/19] Made updates as requested by reviewers Made requested updates. --- docs/_docs/quickstart.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/_docs/quickstart.md b/docs/_docs/quickstart.md index c2d0e79d..3a57ef87 100644 --- a/docs/_docs/quickstart.md +++ b/docs/_docs/quickstart.md @@ -22,6 +22,8 @@ If you already have [Ruby](https://www.ruby-lang.org/en/downloads/) and [RubyGem # Now browse to http://localhost:4000 ``` +## About bundler + `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. @@ -29,12 +31,14 @@ If you already have [Ruby](https://www.ruby-lang.org/en/downloads/) and [RubyGem * 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 ` 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: * 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). +* 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. ## 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. +Building a Jekyll site with 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. From adc619ca6c418fe90b0d242309db39224bd1a94a Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Wed, 28 Dec 2016 15:21:57 -0800 Subject: [PATCH 07/19] added info about jekyll new --help --- docs/_docs/quickstart.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/_docs/quickstart.md b/docs/_docs/quickstart.md index 3a57ef87..8c509fab 100644 --- a/docs/_docs/quickstart.md +++ b/docs/_docs/quickstart.md @@ -22,7 +22,7 @@ If you already have [Ruby](https://www.ruby-lang.org/en/downloads/) and [RubyGem # Now browse to http://localhost:4000 ``` -## About bundler +## About Bundler `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: @@ -31,13 +31,14 @@ If you already have [Ruby](https://www.ruby-lang.org/en/downloads/) and [RubyGem * 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 +## Options for creating a new site with Jekyll `jekyll new ` 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: * 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`. ## Next steps From 1bc82b9c8a28e2170e3ac256dde01b4cf265e016 Mon Sep 17 00:00:00 2001 From: Parker Moore Date: Wed, 28 Dec 2016 22:54:37 -0700 Subject: [PATCH 08/19] Fix script/stackprof & add some GC stats. When running 'script/stackprof object', I noticed that it would be helpful to see GC information. It appears we create a lot of junk -- a source of optimization if we decide to go down that path. An average Jekyll build doesn't run a GC, but auto-regeneration likely would eventually require a GC run and it would be interesting to see if we can reduce how much we throw away with each call to 'site.process'. --- script/stackprof | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/script/stackprof b/script/stackprof index 1c833142..f78f11aa 100755 --- a/script/stackprof +++ b/script/stackprof @@ -10,13 +10,17 @@ esac export BENCHMARK=true command -v stackprof > /dev/null || script/bootstrap -TEST_SCRIPT="Jekyll::Commands::Build.process({'source' => 'site'})" +TEST_SCRIPT="Jekyll::Commands::Build.process({'source' => 'docs'})" PROF_OUTPUT_FILE=tmp/stackprof-${STACKPROF_MODE}-$(date +%Y%m%d%H%M).dump +GC_BEFORE="puts 'GC Stats:'; puts JSON.pretty_generate(GC.stat); GC.disable" +GC_AFTER="puts 'GC Stats:'; GC.start(full_mark: true, immediate_sweep: false); puts JSON.pretty_generate(GC.stat);" + echo Stackprof Mode: $STACKPROF_MODE test -f "$PROF_OUTPUT_FILE" || { - bundle exec ruby -r./lib/jekyll -rstackprof \ - -e "StackProf.run(mode: :${STACKPROF_MODE}, interval: 100, out: '${PROF_OUTPUT_FILE}') { ${TEST_SCRIPT} }" + bundle exec ruby -r./lib/jekyll -rstackprof -rjson \ + -e "StackProf.run(mode: :${STACKPROF_MODE}, interval: 100, out: '${PROF_OUTPUT_FILE}') { ${GC_BEFORE}; ${TEST_SCRIPT}; ${GC_AFTER}; }" } -bundle exec stackprof $PROF_OUTPUT_FILE $@ +set -x +bundle exec stackprof $PROF_OUTPUT_FILE $@ --sort-total From 391bf5d33c09c6f7584b9bc470877e26bda29ab4 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Wed, 28 Dec 2016 23:46:25 -0800 Subject: [PATCH 09/19] made fixes made requested fixes --- docs/_docs/permalinks.md | 326 ++++----------------------------------- 1 file changed, 27 insertions(+), 299 deletions(-) diff --git a/docs/_docs/permalinks.md b/docs/_docs/permalinks.md index 31eeb30b..d15a9eb1 100644 --- a/docs/_docs/permalinks.md +++ b/docs/_docs/permalinks.md @@ -1,317 +1,45 @@ --- layout: docs -title: Permalinks -permalink: /docs/permalinks/ +title: Quick-start guide +permalink: /docs/quickstart/ --- -Jekyll supports a flexible way to build your site’s URLs. You can specify the -permalinks for your site through the [Configuration](../configuration/) or in -the [YAML Front Matter](../frontmatter/) for each post. You’re free to choose -one of the built-in styles to create your links or craft your own. The default -style is `date`. +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: -Permalinks are constructed by creating a template URL where dynamic elements -are represented by colon-prefixed keywords. For example, the default `date` -permalink is defined according to the format `/:categories/:year/:month/:day/:title.html`. +```sh +# Install Jekyll and Bundler gems through RubyGems +~ $ gem install jekyll bundler -
-
Specifying permalinks through the YAML Front Matter
-

- Built-in permalink styles are not recognized in YAML Front Matter. So - permalink: pretty will not work, but the equivalent - /:categories/:year/:month/:day/:title/ - using template variables will. -

-
+# Create a new Jekyll site at ./myblog +~ $ jekyll new myblog -## Template variables +# Change into your new directory +~ $ cd myblog -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
VariableDescription
-

year

- 		-

Year from the Post’s filename

-
-

month

- 		-

Month from the Post’s filename

-
-

i_month

- 		-

Month from the Post’s filename without leading zeros.

-
-

day

- 		-

Day from the Post’s filename

-
-

i_day

- 		-

Day from the Post’s filename without leading zeros.

-
-

short_year

- 		-

Year from the Post’s filename without the century.

-
-

hour

- 		-

- Hour of the day, 24-hour clock, zero-padded from the post’s date front matter. (00..23) -

-
-

minute

- 		-

- Minute of the hour from the post’s date front matter. (00..59) -

-
-

second

- 		-

- Second of the minute from the post’s date front matter. (00..59) -

-
-

title

- 		-

- Title from the document’s filename. May be overridden via - the document’s slug YAML front matter. -

-
-

slug

- 		-

- Slugified title from the document’s filename ( any character - except numbers and letters is replaced as hyphen ). May be - overridden via the document’s slug YAML front matter. -

-
-

categories

- 		-

- The specified categories for this Post. If a post has multiple - categories, Jekyll will create a hierarchy (e.g. /category1/category2). - Also Jekyll automatically parses out double slashes in the URLs, - so if no categories are present, it will ignore this. -

-
-
+# Build the site on the preview server +~/myblog $ bundle exec jekyll serve -## Built-in permalink styles +# Now browse to http://localhost:4000 +``` -While you can specify a custom permalink style using [template variables](#template-variables), -Jekyll also provides the following built-in styles for convenience. +## About Bundler -
- - - - - - - - - - - - - - - - - - - - - - - - - -
Permalink StyleURL Template
-

date

- 		-

/:categories/:year/:month/:day/:title.html

-
-

pretty

- 		-

/:categories/:year/:month/:day/:title/

-
-

ordinal

- 		-

/:categories/:year/:y_day/:title.html

-
-

none

- 		-

/:categories/:title.html

-
-
+`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: -## Pages and collections +* `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 site. If your site doesn't have these Gemfiles, you can omit `bundle exec` and just run `jekyll serve`. -The `permalink` configuration setting specifies the permalink style used for -posts. Pages and collections each have their own default permalink style; the -default style for pages is `/:path/:basename` and the default for collections is -`/:collection/:path`. +* 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. -These styles are modified to match the suffix style specified in the post -permalink setting. For example, a permalink style of `pretty`, which contains a -trailing slash, will update page permalinks to also contain a trailing slash: -`/:path/:basename/`. A permalink style of `date`, which contains a trailing -file extension, will update page permalinks to also contain a file extension: -`/:path/:basename:output_ext`. The same is true for any custom permalink style. +## Options for creating a new site with Jekyll -The permalink for an individual page or collection document can always be -overridden in the [YAML Front Matter](../frontmatter/) for the page or document. -Additionally, permalinks for a given collection can be customized [in the -collections configuration](../collections/). +`jekyll new ` 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: -## Permalink style examples +* 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`. -Given a post named: `/2009-04-29-slap-chop.md` +## Next steps -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
URL TemplateResulting Permalink URL
-

None specified, or permalink: date

- 		-

/2009/04/29/slap-chop.html

-
-

pretty

- 		-

/2009/04/29/slap-chop/

-
-

/:month-:day-:year/:title.html

- 		-

/04-29-2009/slap-chop.html

-
-

/blog/:year/:month/:day/:title/

- 		-

/blog/2009/04/29/slap-chop/

-
-

/:year/:month/:title

-

See extensionless permalinks for details.

- 		-

/2009/04/slap-chop

-
-
- -## Extensionless permalinks - -Jekyll supports permalinks that contain neither a trailing slash nor a file -extension, but this requires additional support from the web server to properly -serve. When using extensionless permalinks, output files written to disk will -still have the proper file extension (typically `.html`), so the web server -must be able to map requests without file extensions to these files. - -Both [GitHub Pages](../github-pages/) and the Jekyll's built-in WEBrick server -handle these requests properly without any additional work. - -### Apache - -The Apache web server has very extensive support for content negotiation and can -handle extensionless URLs by setting the [multiviews][] option in your -`httpd.conf` or `.htaccess` file: - -[multiviews]: https://httpd.apache.org/docs/current/content-negotiation.html#multiviews - -{% highlight apache %} -Options +MultiViews -{% endhighlight %} - -### Nginx - -The [try_files][] directive allows you to specify a list of files to search for -to process a request. The following configuration will instruct nginx to search -for a file with an `.html` extension if an exact match for the requested URI is -not found. - -[try_files]: http://nginx.org/en/docs/http/ngx_http_core_module.html#try_files - -{% highlight nginx %} -try_files $uri $uri.html $uri/ =404; -{% endhighlight %} +Building a Jekyll site with 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. From 6a2c7f271821af449ee3de4eb16ea72c47f949b0 Mon Sep 17 00:00:00 2001 From: Rob Crocombe Date: Thu, 29 Dec 2016 10:20:15 +0000 Subject: [PATCH 10/19] Add Jekyll-Post to plugins.md --- docs/_docs/plugins.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_docs/plugins.md b/docs/_docs/plugins.md index cc1995ad..775dabbf 100644 --- a/docs/_docs/plugins.md +++ b/docs/_docs/plugins.md @@ -918,6 +918,7 @@ LESS.js files during generation. - [jekyll-data](https://github.com/ashmaroli/jekyll-data): Read data files within Jekyll Theme Gems. - [jekyll-pinboard](https://github.com/snaptortoise/jekyll-pinboard-plugin): Access your Pinboard bookmarks within your Jekyll theme. - [jekyll-migrate-permalink](https://github.com/mpchadwick/jekyll-migrate-permalink): Adds a `migrate-permalink` sub-command to help deal with side effects of changing your permalink. +- [Jekyll-Post](https://github.com/robcrocombe/jekyll-post): A CLI tool to easily draft, edit, and publish Jekyll posts. #### Editors From 57d6d5986feb912fd4c4241a29d9a86980a9d91f Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Thu, 29 Dec 2016 08:27:42 -0800 Subject: [PATCH 11/19] update quickstart.md I must have just updated the wrong doc or branch in the last commit. i hope this fixes it. --- docs/_docs/quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_docs/quickstart.md b/docs/_docs/quickstart.md index 8c509fab..d15a9eb1 100644 --- a/docs/_docs/quickstart.md +++ b/docs/_docs/quickstart.md @@ -27,7 +27,7 @@ If you already have [Ruby](https://www.ruby-lang.org/en/downloads/) and [RubyGem `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`. +* The `Gemfile` and `Gemfile.lock` files inform Bundler about the gem requirements in your site. If your site doesn't have these Gemfiles, you can omit `bundle exec` and just run `jekyll serve`. * 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. @@ -38,7 +38,7 @@ If you already have [Ruby](https://www.ruby-lang.org/en/downloads/) and [RubyGem * 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`. +* To learn about other parameters you can include with `jekyll new`, type `jekyll new --help`. ## Next steps From 192e79ed1e84298ffc07c3ce4ca4ffa2e6bd0534 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Thu, 29 Dec 2016 08:57:39 -0800 Subject: [PATCH 12/19] reset permalinks to same state it was in in patch-3 branch. i couldn't seem to remove it from the previous commit. --- docs/_docs/permalinks.md | 326 +++++++++++++++++++++++++++++++++++---- 1 file changed, 299 insertions(+), 27 deletions(-) diff --git a/docs/_docs/permalinks.md b/docs/_docs/permalinks.md index d15a9eb1..557a53f9 100644 --- a/docs/_docs/permalinks.md +++ b/docs/_docs/permalinks.md @@ -1,45 +1,317 @@ --- layout: docs -title: Quick-start guide -permalink: /docs/quickstart/ +title: Permalinks +permalink: /docs/permalinks/ --- -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: +Jekyll supports a flexible way to build your site’s URLs. You can specify the +permalinks for your site through the [Configuration](../configuration/) or in +the [YAML Front Matter](../frontmatter/) for each post. You’re free to choose +one of the built-in styles to create your links or craft your own. The default +style is `date`. -```sh -# Install Jekyll and Bundler gems through RubyGems -~ $ gem install jekyll bundler +Permalinks are constructed by creating a template URL where dynamic elements +are represented by colon-prefixed keywords. For example, the default `date` +permalink is defined according to the format `/:categories/:year/:month/:day/:title.html`. -# Create a new Jekyll site at ./myblog -~ $ jekyll new myblog +
+
Specifying permalinks through the YAML Front Matter
+

+ Built-in permalink styles are not recognized in YAML Front Matter. So + permalink: pretty will not work, but the equivalent + /:categories/:year/:month/:day/:title/ + using template variables will. +

+
-# Change into your new directory -~ $ cd myblog +## Template variables -# Build the site on the preview server -~/myblog $ bundle exec jekyll serve +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDescription
+

year

+ 		+

Year from the Post’s filename

+
+

month

+ 		+

Month from the Post’s filename

+
+

i_month

+ 		+

Month from the Post’s filename without leading zeros.

+
+

day

+ 		+

Day from the Post’s filename

+
+

i_day

+ 		+

Day from the Post’s filename without leading zeros.

+
+

short_year

+ 		+

Year from the Post’s filename without the century.

+
+

hour

+ 		+

+ Hour of the day, 24-hour clock, zero-padded from the post’s date front matter. (00..23) +

+
+

minute

+ 		+

+ Minute of the hour from the post’s date front matter. (00..59) +

+
+

second

+ 		+

+ Second of the minute from the post’s date front matter. (00..59) +

+
+

title

+ 		+

+ Title from the document’s filename. May be overridden via + the document’s slug YAML front matter. +

+
+

slug

+ 		+

+ Slugified title from the document’s filename ( any character + except numbers and letters is replaced as hyphen ). May be + overridden via the document’s slug YAML front matter. +

+
+

categories

+ 		+

+ The specified categories for this Post. If a post has multiple + categories, Jekyll will create a hierarchy (e.g. /category1/category2). + Also Jekyll automatically parses out double slashes in the URLs, + so if no categories are present, it will ignore this. +

+
+
-# Now browse to http://localhost:4000 -``` +## Built-in permalink styles -## About Bundler +While you can specify a custom permalink style using [template variables](#template-variables), +Jekyll also provides the following built-in styles for convenience. -`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: +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Permalink StyleURL Template
+

date

+ 		+

/:categories/:year/:month/:day/:title.html

+
+

pretty

+ 		+

/:categories/:year/:month/:day/:title/

+
+

ordinal

+ 		+

/:categories/:year/:y_day/:title.html

+
+

none

+ 		+

/:categories/:title.html

+
+
-* `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 site. If your site doesn't have these Gemfiles, you can omit `bundle exec` and just run `jekyll serve`. +## Pages and collections -* 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. +The `permalink` configuration setting specifies the permalink style used for +posts. Pages and collections each have their own default permalink style; the +default style for pages is `/:path/:basename` and the default for collections is +`/:collection/:path`. -## Options for creating a new site with Jekyll +These styles are modified to match the suffix style specified in the post +permalink setting. For example, a permalink style of `pretty`, which contains a +trailing slash, will update page permalinks to also contain a trailing slash: +`/:path/:basename/`. A permalink style of `date`, which contains a trailing +file extension, will update page permalinks to also contain a file extension: +`/:path/:basename:output_ext`. The same is true for any custom permalink style. -`jekyll new ` 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: +The permalink for an individual page or collection document can always be +overridden in the [YAML Front Matter](../frontmatter/) for the page or document. +Additionally, permalinks for a given collection can be customized [in the +collections configuration](../collections/). -* 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`. +## Permalink style examples -## Next steps +Given a post named: `/2009-04-29-slap-chop.md` -Building a Jekyll site with 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. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
URL TemplateResulting Permalink URL
+

None specified, or permalink: date

+ 		+

/2009/04/29/slap-chop.html

+
+

pretty

+ 		+

/2009/04/29/slap-chop/

+
+

/:month-:day-:year/:title.html

+ 		+

/04-29-2009/slap-chop.html

+
+

/blog/:year/:month/:day/:title/

+ 		+

/blog/2009/04/29/slap-chop/

+
+

/:year/:month/:title

+

See extensionless permalinks for details.

+ 		+

/2009/04/slap-chop

+
+
+ +## Extensionless permalinks + +Jekyll supports permalinks that contain neither a trailing slash nor a file +extension, but this requires additional support from the web server to properly +serve. When using extensionless permalinks, output files written to disk will +still have the proper file extension (typically `.html`), so the web server +must be able to map requests without file extensions to these files. + +Both [GitHub Pages](../github-pages/) and the Jekyll's built-in WEBrick server +handle these requests properly without any additional work. + +### Apache + +The Apache web server has very extensive support for content negotiation and can +handle extensionless URLs by setting the [multiviews][] option in your +`httpd.conf` or `.htaccess` file: + +[multiviews]: https://httpd.apache.org/docs/current/content-negotiation.html#multiviews + +{% highlight apache %} +Options +MultiViews +{% endhighlight %} + +### Nginx + +The [try_files][] directive allows you to specify a list of files to search for +to process a request. The following configuration will instruct nginx to search +for a file with an `.html` extension if an exact match for the requested URI is +not found. + +[try_files]: http://nginx.org/en/docs/http/ngx_http_core_module.html#try_files + +{% highlight nginx %} +try_files $uri $uri.html $uri/ =404; +{% endhighlight %} From 0014b1d9f07bc802de4adbc7b462b958c66451eb Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Thu, 29 Dec 2016 19:02:54 -0800 Subject: [PATCH 13/19] Update history to reflect merge of #5689 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index 3bd4af8e..fde5160e 100644 --- a/History.markdown +++ b/History.markdown @@ -12,6 +12,7 @@ * Switch to `https` when possible. (#5611) * Update `_font-awesome.scss` to move .woff file before .ttf (#5614) * Update documentation on updating FontAwesome Iconset (#5655) + * Improve quickstart docs (#5689) ### Minor Enhancements From 0197b65e711fc8cab22170b43db06414d764a33e Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Sat, 31 Dec 2016 13:44:17 -0800 Subject: [PATCH 14/19] Update history to reflect merge of #5705 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index fde5160e..834ddf9c 100644 --- a/History.markdown +++ b/History.markdown @@ -13,6 +13,7 @@ * Update `_font-awesome.scss` to move .woff file before .ttf (#5614) * Update documentation on updating FontAwesome Iconset (#5655) * Improve quickstart docs (#5689) + * Add Jekyll-Post to list of plugins (#5705) ### Minor Enhancements From b704df0245ef467017ac945d73f77dc278b1c3a4 Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Sun, 1 Jan 2017 06:51:40 -0800 Subject: [PATCH 15/19] Update history to reflect merge of #5683 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index 834ddf9c..f06792cd 100644 --- a/History.markdown +++ b/History.markdown @@ -44,6 +44,7 @@ * Improve Permalinks documentation. (#5653) * Fix typo in Variables doc page (#5657) * Fix a couple of typos in the docs (#5658) + * Update windows.md (#5683) ## 3.3.1 / 2016-11-14 From da1a36eff9b310c86b6295a1a6257e0d82c45acd Mon Sep 17 00:00:00 2001 From: Chase Date: Sun, 1 Jan 2017 18:20:45 -0500 Subject: [PATCH 16/19] update Classifier-Reborn to 2.1.0 --- Gemfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile b/Gemfile index fa254dff..eda95e5e 100644 --- a/Gemfile +++ b/Gemfile @@ -73,7 +73,7 @@ group :jekyll_optional_dependencies do gem "toml", "~> 0.1.0" platform :ruby, :mswin, :mingw, :x64_mingw do - gem "classifier-reborn", "~> 2.0" + gem "classifier-reborn", "~> 2.1.0" gem "liquid-c", "~> 3.0" gem "pygments.rb", "~> 0.6.0" gem "rdiscount", "~> 2.0" From 6ab6de7093e5319d164fed2ed068dd517583f185 Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Sun, 1 Jan 2017 21:24:28 -0800 Subject: [PATCH 17/19] Update history to reflect merge of #5711 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index f06792cd..b6366cdb 100644 --- a/History.markdown +++ b/History.markdown @@ -35,6 +35,7 @@ * Rubocop -a on lib/jekyll (#5666) * Bump to rake 12.0 (#5670) * Rubocop Gemfile (#5671) + * update Classifier-Reborn to 2.1.0 (#5711) ### Documentation From de6d62b2e36ee110ab4e5807e9c78c1d99aa7d65 Mon Sep 17 00:00:00 2001 From: Chayoung You Date: Mon, 2 Jan 2017 22:07:03 +0900 Subject: [PATCH 18/19] Use the current year for the LICENSE of theme --- lib/theme_template/LICENSE.txt.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/theme_template/LICENSE.txt.erb b/lib/theme_template/LICENSE.txt.erb index df803135..38a0eb4e 100644 --- a/lib/theme_template/LICENSE.txt.erb +++ b/lib/theme_template/LICENSE.txt.erb @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016 <%= user_name %> +Copyright (c) <%= Time.now.year %> <%= user_name %> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal From 7dce4e427036bc7f3a4c0d5d859adc85dfd68620 Mon Sep 17 00:00:00 2001 From: jekyllbot Date: Mon, 2 Jan 2017 08:17:08 -0800 Subject: [PATCH 19/19] Update history to reflect merge of #5712 [ci skip] --- History.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/History.markdown b/History.markdown index b6366cdb..b294d518 100644 --- a/History.markdown +++ b/History.markdown @@ -19,6 +19,7 @@ * Add connector param to array_to_sentence_string filter (#5597) * Adds group_by_exp filter (#5513) + * Use the current year for the LICENSE of theme (#5712) ### Bug Fixes