From 317eae55802e637663bc880b72961a2aff68cd3e Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 25 Dec 2016 20:31:32 -0800 Subject: [PATCH 1/6] 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 2/6] 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 3/6] 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 391bf5d33c09c6f7584b9bc470877e26bda29ab4 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Wed, 28 Dec 2016 23:46:25 -0800 Subject: [PATCH 4/6] 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 57d6d5986feb912fd4c4241a29d9a86980a9d91f Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Thu, 29 Dec 2016 08:27:42 -0800 Subject: [PATCH 5/6] 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 6/6] 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 %}