Merge pull request #5693 from tomjohnson1492/patch-7
Merge pull request 5693
This commit is contained in:
jekyllbot
GitHub
commit
da2899198d
|
|
@ -4,27 +4,54 @@ title: Permalinks
|
|||
permalink: /docs/permalinks/
|
||||
---
|
||||
|
||||
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`.
|
||||
Permalinks refer to the URLs (excluding the domain name or directory folder) for your pages, posts, or collections.
|
||||
Jekyll supports a flexible way to build permalinks, allowing you to leverage various template variables or choose built-in permalink styles (such as `date`) that automatically use a template-variable pattern.
|
||||
|
||||
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`.
|
||||
You construct permalinks by creating a template URL where dynamic elements are represented by colon-prefixed keywords. The default template permalink is `/:categories/:year/:month/:day/:title.html`. Each of the colon-prefixed keywords is a template variable.
|
||||
|
||||
<div class="note info">
|
||||
<h5>Specifying permalinks through the YAML Front Matter</h5>
|
||||
<p>
|
||||
Built-in permalink styles are not recognized in YAML Front Matter. So
|
||||
<code>permalink: pretty</code> will not work, but the equivalent
|
||||
<code>/:categories/:year/:month/:day/:title/</code>
|
||||
using template variables will.
|
||||
</p>
|
||||
</div>
|
||||
## Where to configure permalinks
|
||||
|
||||
## Template variables
|
||||
You can configure your site's permalinks through the [Configuration]({% link _docs/configuration.md %}) file or in the [Front Matter]({% link _docs/frontmatter.md %}) for each post, page, or collection.
|
||||
|
||||
Setting permalink styles in your configuration file applies the setting globally in your project. You configure permalinks in your `_config.yml` file like this:
|
||||
|
||||
```yaml
|
||||
permalink: /:categories/:year/:month/:day/:title.html
|
||||
```
|
||||
|
||||
If you don't specify any permalink setting, Jekyll uses the above pattern as the default.
|
||||
|
||||
The permalink can also be set using a built-in permalink style:
|
||||
|
||||
```yaml
|
||||
permalink: date
|
||||
```
|
||||
|
||||
`date` is the same as `:categories/:year/:month/:day/:title.html`, the default. See [Built-in Permalink Styles](#builtinpermalinkstyles) below for more options.
|
||||
|
||||
Setting the permalink in your post, page, or collection's front matter overrides any global settings. Here's an example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: My page title
|
||||
permalink: /mypageurl/
|
||||
---
|
||||
```
|
||||
|
||||
Even if your configuration file specifies the `date` style, the URL for this page would be `http://somedomain.com/mypageurl/`.
|
||||
|
||||
When you use permalinks that omit the `.html` file extension (called "pretty URLs") Jekyll builds the file as index.html placed inside a folder with the page's name. For example:
|
||||
|
||||
```
|
||||
├── mypageurl
|
||||
│ └── index.html
|
||||
```
|
||||
|
||||
With a URL such as `/mypageurl/`, servers automatically load the index.html file inside the folder, so users can simply navigate to `http://somedomain.com/mypageurl/` to get to `mypageurl/index.html`.
|
||||
|
||||
## Template variables for permalinks {#template-variables}
|
||||
|
||||
The following table lists the template variables available for permalinks. You can use these variables in the `permalink` property in your config file.
|
||||
|
||||
<div class="mobile-side-scroller">
|
||||
<table>
|
||||
|
|
@ -40,7 +67,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
<p><code>year</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Year from the Post’s filename</p>
|
||||
<p>Year from the post's filename</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -48,7 +75,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
<p><code>month</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Month from the Post’s filename</p>
|
||||
<p>Month from the post's filename</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -56,7 +83,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
<p><code>i_month</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Month from the Post’s filename without leading zeros.</p>
|
||||
<p>Month from the post's filename without leading zeros.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -64,7 +91,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
<p><code>day</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Day from the Post’s filename</p>
|
||||
<p>Day from the post's filename</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -72,7 +99,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
<p><code>i_day</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Day from the Post’s filename without leading zeros.</p>
|
||||
<p>Day from the post's filename without leading zeros.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -80,7 +107,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
<p><code>short_year</code></p>
|
||||
</td>
|
||||
<td>
|
||||
<p>Year from the Post’s filename without the century.</p>
|
||||
<p>Year from the post's filename without the century.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
|
|
@ -89,7 +116,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Hour of the day, 24-hour clock, zero-padded from the post’s <code>date</code> front matter. (00..23)
|
||||
Hour of the day, 24-hour clock, zero-padded from the post's <code>date</code> front matter. (00..23)
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
|
|
@ -99,7 +126,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Minute of the hour from the post’s <code>date</code> front matter. (00..59)
|
||||
Minute of the hour from the post's <code>date</code> front matter. (00..59)
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
|
|
@ -109,7 +136,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Second of the minute from the post’s <code>date</code> front matter. (00..59)
|
||||
Second of the minute from the post's <code>date</code> front matter. (00..59)
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
|
|
@ -130,8 +157,8 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
</td>
|
||||
<td>
|
||||
<p>
|
||||
Slugified title from the document’s filename ( any character
|
||||
except numbers and letters is replaced as hyphen ). May be
|
||||
Slugified title from the document’s filename (any character
|
||||
except numbers and letters is replaced as hyphen). May be
|
||||
overridden via the document’s <code>slug</code> YAML front matter.
|
||||
</p>
|
||||
</td>
|
||||
|
|
@ -142,7 +169,7 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
</td>
|
||||
<td>
|
||||
<p>
|
||||
The specified categories for this Post. If a post has multiple
|
||||
The specified categories for this post. If a post has multiple
|
||||
categories, Jekyll will create a hierarchy (e.g. <code>/category1/category2</code>).
|
||||
Also Jekyll automatically parses out double slashes in the URLs,
|
||||
so if no categories are present, it will ignore this.
|
||||
|
|
@ -153,10 +180,11 @@ permalink is defined according to the format `/:categories/:year/:month/:day/:ti
|
|||
</table>
|
||||
</div>
|
||||
|
||||
## Built-in permalink styles
|
||||
Note that all template variables relating to time or categories are available to posts only.
|
||||
|
||||
While you can specify a custom permalink style using [template variables](#template-variables),
|
||||
Jekyll also provides the following built-in styles for convenience.
|
||||
## Built-in permalink styles {#builtinpermalinkstyles}
|
||||
|
||||
Although you can specify a custom permalink pattern using [template variables](#template-variables), Jekyll also provides the following built-in styles for convenience.
|
||||
|
||||
<div class="mobile-side-scroller">
|
||||
<table>
|
||||
|
|
@ -203,26 +231,16 @@ Jekyll also provides the following built-in styles for convenience.
|
|||
</table>
|
||||
</div>
|
||||
|
||||
## Pages and collections
|
||||
Rather than typing `permalink: /:categories/:year/:month/:day/:title/`, you can just type `permalink: date`.
|
||||
|
||||
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`.
|
||||
<div class="note info">
|
||||
<h5>Specifying permalinks through the YAML Front Matter</h5>
|
||||
<p>Built-in permalink styles are not recognized in YAML Front Matter. As a result, <code>permalink: pretty</code> will not work.</p>
|
||||
</div>
|
||||
|
||||
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.
|
||||
## Permalink style examples with posts {#permalink-style-examples}
|
||||
|
||||
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/).
|
||||
|
||||
## Permalink style examples
|
||||
Here are a few examples to clarify how permalink styles get applied with posts.
|
||||
|
||||
Given a post named: `/2009-04-29-slap-chop.md`
|
||||
|
||||
|
|
@ -270,7 +288,7 @@ Given a post named: `/2009-04-29-slap-chop.md`
|
|||
<tr>
|
||||
<td>
|
||||
<p><code>/:year/:month/:title</code></p>
|
||||
<p>See <a href="#extensionless-permalinks">extensionless permalinks</a> for details.</p>
|
||||
<p>See <a href="#extensionless-permalinks">Extensionless permalinks with no trailing slashes</a> for details.</p>
|
||||
</td>
|
||||
<td>
|
||||
<p><code>/2009/04/slap-chop</code></p>
|
||||
|
|
@ -280,24 +298,58 @@ Given a post named: `/2009-04-29-slap-chop.md`
|
|||
</table>
|
||||
</div>
|
||||
|
||||
## Extensionless permalinks
|
||||
## Permalink settings for pages and collections {#pages-and-collections}
|
||||
|
||||
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.
|
||||
The permalink setting in your configuration file specifies the permalink style used for posts, pages, and collections. However, because pages and collections don't have time or categories, these aspects of the permalink style are ignored with pages and collections.
|
||||
|
||||
Both [GitHub Pages](../github-pages/) and the Jekyll's built-in WEBrick server
|
||||
handle these requests properly without any additional work.
|
||||
For example:
|
||||
|
||||
* A permalink style of `/:categories/:year/:month/:day/:title.html` for posts becomes `/:title.html` for pages and collections.
|
||||
* A permalink style of `pretty` (or `/:categories/:year/:month/:day/:title/`), which omits the file extension and contains a trailing slash, will update page and collection permalinks to also omit the file extension and contain a trailing slash: `/:title/`.
|
||||
* A permalink style of `date`, which contains a trailing file extension, will update page permalinks to also contain a trailing file extension: `/:title.html`. But no time or category information will be included.
|
||||
|
||||
## Permalinks and default paths
|
||||
|
||||
The path to the post or page in the built site differs for posts, pages, and collections:
|
||||
|
||||
### Posts
|
||||
|
||||
The subfolders into which you may have organized your posts inside the `_posts` directory will not be part of the permalink.
|
||||
|
||||
If you use a permalink style that omits the `.html` file extension, each post is rendered as an `index.html` file inside a folder with the post's name (for example, `categoryname/2016/12/01/mypostname/index.html`).
|
||||
|
||||
### Pages
|
||||
|
||||
Unlike posts, pages by default mimic the source directory structure exactly. (The only exception is if your page has a `permalink` declared its front matter — in that case, the structure honors the permalink setting instead of the source folder structure.)
|
||||
|
||||
As with posts, if you use a permalink style that omits the `.html` file extension, each page is rendered as an `index.html` file inserted inside a folder with the page's name (for example, `mypage/index.html`).
|
||||
|
||||
### Collections
|
||||
|
||||
By default, collections follow a similar structure in the `_site` folder as pages, except that the path is prefaced by the collection name. For example: `collectionname/mypage.html`. For permalink settings that omit the file extension, the path would be `collection_name/mypage/index.html`.
|
||||
|
||||
Collections have their own way of setting permalinks. Additionally, collections have unique template variables available available (such as `path` and `output_ext`). See the [Configuring permalinks for collections]( ../collections#permalinks ) in Collections for more information.
|
||||
|
||||
## Flattening pages in \_site on build
|
||||
|
||||
If you want to flatten your pages (pull them out of subfolders) in the `_site` directory when your site builds (similar to posts), add the `permalink` property to the front matter of each page, with no path specified:
|
||||
|
||||
```
|
||||
---
|
||||
title: My page
|
||||
permalink: mypageurl.html
|
||||
---
|
||||
```
|
||||
|
||||
## Extensionless permalinks with no trailing slashes {#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 these types of 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
|
||||
The Apache web server has extensive support for content negotiation and can handle extensionless URLs by setting the [multiviews](https://httpd.apache.org/docs/current/content-negotiation.html#multiviews) option in your `httpd.conf` or `.htaccess` file:
|
||||
|
||||
{% highlight apache %}
|
||||
Options +MultiViews
|
||||
|
|
@ -305,13 +357,12 @@ Options +MultiViews
|
|||
|
||||
### 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
|
||||
The [try_files](http://nginx.org/en/docs/http/ngx_http_core_module.html#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.
|
||||
|
||||
{% highlight nginx %}
|
||||
try_files $uri $uri.html $uri/ =404;
|
||||
{% endhighlight %}
|
||||
|
||||
## Linking without regard to permalink styles
|
||||
|
||||
You can create links in your topics to other posts, pages, or collection items in a way that is valid no matter what permalink configuration you choose. By using the `link` tag, if you change your permalinks, your links won't break. See [Linking to pages](../templates#link) in Templates for more details.
|
||||
|
|
|
|||
Loading…
Reference in New Issue