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 %}