Tom Johnson
GitHub
parent
adc619ca6c
commit
391bf5d33c
|
|
@ -1,317 +1,45 @@
|
||||||
---
|
---
|
||||||
layout: docs
|
layout: docs
|
||||||
title: Permalinks
|
title: Quick-start guide
|
||||||
permalink: /docs/permalinks/
|
permalink: /docs/quickstart/
|
||||||
---
|
---
|
||||||
|
|
||||||
Jekyll supports a flexible way to build your site’s URLs. You can specify the
|
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 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 are constructed by creating a template URL where dynamic elements
|
```sh
|
||||||
are represented by colon-prefixed keywords. For example, the default `date`
|
# Install Jekyll and Bundler gems through RubyGems
|
||||||
permalink is defined according to the format `/:categories/:year/:month/:day/:title.html`.
|
~ $ gem install jekyll bundler
|
||||||
|
|
||||||
<div class="note info">
|
# Create a new Jekyll site at ./myblog
|
||||||
<h5>Specifying permalinks through the YAML Front Matter</h5>
|
~ $ jekyll new myblog
|
||||||
<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>
|
|
||||||
|
|
||||||
## Template variables
|
# Change into your new directory
|
||||||
|
~ $ cd myblog
|
||||||
|
|
||||||
<div class="mobile-side-scroller">
|
# Build the site on the preview server
|
||||||
<table>
|
~/myblog $ bundle exec jekyll serve
|
||||||
<thead>
|
|
||||||
<tr>
|
|
||||||
<th>Variable</th>
|
|
||||||
<th>Description</th>
|
|
||||||
</tr>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>year</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>Year from the Post’s filename</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>month</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>Month from the Post’s filename</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>i_month</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>Month from the Post’s filename without leading zeros.</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>day</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>Day from the Post’s filename</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>i_day</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>Day from the Post’s filename without leading zeros.</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>short_year</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>Year from the Post’s filename without the century.</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>hour</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>
|
|
||||||
Hour of the day, 24-hour clock, zero-padded from the post’s <code>date</code> front matter. (00..23)
|
|
||||||
</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>minute</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>
|
|
||||||
Minute of the hour from the post’s <code>date</code> front matter. (00..59)
|
|
||||||
</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>second</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>
|
|
||||||
Second of the minute from the post’s <code>date</code> front matter. (00..59)
|
|
||||||
</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>title</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>
|
|
||||||
Title from the document’s filename. May be overridden via
|
|
||||||
the document’s <code>slug</code> YAML front matter.
|
|
||||||
</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>slug</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>
|
|
||||||
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>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>categories</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
## Built-in permalink styles
|
# Now browse to http://localhost:4000
|
||||||
|
```
|
||||||
|
|
||||||
While you can specify a custom permalink style using [template variables](#template-variables),
|
## About Bundler
|
||||||
Jekyll also provides the following built-in styles for convenience.
|
|
||||||
|
|
||||||
<div class="mobile-side-scroller">
|
`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:
|
||||||
<table>
|
|
||||||
<thead>
|
|
||||||
<tr>
|
|
||||||
<th>Permalink Style</th>
|
|
||||||
<th>URL Template</th>
|
|
||||||
</tr>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>date</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/:categories/:year/:month/:day/:title.html</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>pretty</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/:categories/:year/:month/:day/:title/</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>ordinal</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/:categories/:year/:y_day/:title.html</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>none</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/:categories/:title.html</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
## 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
|
* 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.
|
||||||
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`.
|
|
||||||
|
|
||||||
These styles are modified to match the suffix style specified in the post
|
## Options for creating a new site with Jekyll
|
||||||
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.
|
|
||||||
|
|
||||||
The permalink for an individual page or collection document can always be
|
`jekyll new <PATH>` 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:
|
||||||
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
|
* 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
|
||||||
|
|
||||||
<div class="mobile-side-scroller">
|
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.
|
||||||
<table>
|
|
||||||
<thead>
|
|
||||||
<tr>
|
|
||||||
<th>URL Template</th>
|
|
||||||
<th>Resulting Permalink URL</th>
|
|
||||||
</tr>
|
|
||||||
</thead>
|
|
||||||
<tbody>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p>None specified, or <code>permalink: date</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/2009/04/29/slap-chop.html</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>pretty</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/2009/04/29/slap-chop/</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>/:month-:day-:year/:title.html</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/04-29-2009/slap-chop.html</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>/blog/:year/:month/:day/:title/</code></p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/blog/2009/04/29/slap-chop/</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>
|
|
||||||
<p><code>/:year/:month/:title</code></p>
|
|
||||||
<p>See <a href="#extensionless-permalinks">extensionless permalinks</a> for details.</p>
|
|
||||||
</td>
|
|
||||||
<td>
|
|
||||||
<p><code>/2009/04/slap-chop</code></p>
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</tbody>
|
|
||||||
</table>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
## 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 %}
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue