Frank Taillandier
jekyllbot
parent
ac3e6b384f
commit
85aebe9b90
|
|
@ -121,19 +121,27 @@ site or configuration. [Feel free to check it out!](https://github.com/jekyll/je
|
|||
|
||||
To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command:
|
||||
|
||||
<pre class="highlight"><code>$ script/bootstrap</code></pre>
|
||||
```sh
|
||||
script/bootstrap
|
||||
```
|
||||
|
||||
Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly):
|
||||
|
||||
<pre class="highlight"><code>$ script/cibuild</code></pre>
|
||||
```sh
|
||||
script/cibuild
|
||||
```
|
||||
|
||||
If you are only updating a file in `test/`, you can use the command:
|
||||
|
||||
<pre class="highlight"><code>$ script/test test/blah_test.rb</code></pre>
|
||||
```sh
|
||||
script/test test/blah_test.rb
|
||||
```
|
||||
|
||||
If you are only updating a `.feature` file, you can use the command:
|
||||
|
||||
<pre class="highlight"><code>$ script/cucumber features/blah.feature</code></pre>
|
||||
```sh
|
||||
script/cucumber features/blah.feature
|
||||
```
|
||||
|
||||
Both `script/test` and `script/cucumber` can be run without arguments to
|
||||
run its entire respective suite.
|
||||
|
|
|
|||
|
|
@ -8,7 +8,6 @@ google_analytics_id: UA-50755011-1
|
|||
google_site_verification: onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY
|
||||
|
||||
repository: https://github.com/jekyll/jekyll
|
||||
help_url: https://github.com/jekyll/jekyll-help
|
||||
|
||||
timezone: America/Los_Angeles
|
||||
|
||||
|
|
|
|||
|
|
@ -454,7 +454,7 @@ works:
|
|||
|
||||
Every album in the collection could be listed on a single page with a template:
|
||||
|
||||
```html
|
||||
```liquid
|
||||
{% raw %}
|
||||
{% for album in site.albums %}
|
||||
<h2>{{ album.title }}</h2>
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ CircleCI detects when `Gemfile` is present is will automatically run `bundle ins
|
|||
|
||||
The most basic test that can be run is simply seeing if `jekyll build` actually works. This is a blocker, a dependency if you will, for other tests you might run on the generate site. So we'll run Jekyll, via Bundler, in the `dependencies` phase.
|
||||
|
||||
```
|
||||
```yaml
|
||||
dependencies:
|
||||
post:
|
||||
- bundle exec jekyll build
|
||||
|
|
@ -63,7 +63,7 @@ test:
|
|||
|
||||
When you put it all together, here's an example of what that `circle.yml` file could look like:
|
||||
|
||||
```
|
||||
```yaml
|
||||
machine:
|
||||
environment:
|
||||
NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up installation of html-proofer
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ Some options can be specified via command-line switches. Check out the
|
|||
For example to avoid testing external sites, use this command:
|
||||
|
||||
```sh
|
||||
$ bundle exec htmlproofer ./_site --disable-external
|
||||
bundle exec htmlproofer ./_site --disable-external
|
||||
```
|
||||
|
||||
### The HTML Proofer Library
|
||||
|
|
|
|||
|
|
@ -125,19 +125,27 @@ site or configuration. [Feel free to check it out!](https://github.com/jekyll/je
|
|||
|
||||
To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command:
|
||||
|
||||
<pre class="highlight"><code>$ script/bootstrap</code></pre>
|
||||
```sh
|
||||
script/bootstrap
|
||||
```
|
||||
|
||||
Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly):
|
||||
|
||||
<pre class="highlight"><code>$ script/cibuild</code></pre>
|
||||
```sh
|
||||
script/cibuild
|
||||
```
|
||||
|
||||
If you are only updating a file in `test/`, you can use the command:
|
||||
|
||||
<pre class="highlight"><code>$ script/test test/blah_test.rb</code></pre>
|
||||
```sh
|
||||
script/test test/blah_test.rb
|
||||
```
|
||||
|
||||
If you are only updating a `.feature` file, you can use the command:
|
||||
|
||||
<pre class="highlight"><code>$ script/cucumber features/blah.feature</code></pre>
|
||||
```sh
|
||||
script/cucumber features/blah.feature
|
||||
```
|
||||
|
||||
Both `script/test` and `script/cucumber` can be run without arguments to
|
||||
run its entire respective suite.
|
||||
|
|
|
|||
|
|
@ -56,8 +56,8 @@ determines the variable name).
|
|||
|
||||
You can now render the list of members in a template:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
```liquid
|
||||
<ul>
|
||||
{% for member in site.data.members %}
|
||||
<li>
|
||||
|
|
@ -67,8 +67,8 @@ You can now render the list of members in a template:
|
|||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{: .note .info }
|
||||
If your Jekyll site has a lot of pages, such as with documentation websites, see the detailed examples in [how to build robust navigation for your site]({% link _tutorials/navigation.md %}).
|
||||
|
|
@ -106,8 +106,8 @@ members:
|
|||
The organizations can then be accessed via `site.data.orgs`, followed by the
|
||||
file name:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
```liquid
|
||||
<ul>
|
||||
{% for org_hash in site.data.orgs %}
|
||||
{% assign org = org_hash[1] %}
|
||||
|
|
@ -119,8 +119,8 @@ file name:
|
|||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Example: Accessing a specific author
|
||||
|
||||
|
|
@ -136,8 +136,8 @@ dave:
|
|||
|
||||
The author can then be specified as a page variable in a post's frontmatter:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
title: sample post
|
||||
author: dave
|
||||
|
|
@ -149,8 +149,7 @@ author: dave
|
|||
title="{{ author.name }}">
|
||||
{{ author.name }}
|
||||
</a>
|
||||
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
For information on how to build robust navigation for your site (especially if you have a documentation website or another type of Jekyll site with a lot of pages to organize), see [Navigation](/tutorials/navigation).
|
||||
|
|
|
|||
|
|
@ -65,13 +65,13 @@ front matter of a page or post.
|
|||
|
||||
If set, this specifies the layout file to use. Use the layout file
|
||||
name without the file extension. Layout files must be placed in the
|
||||
<code>_layouts</code> directory.
|
||||
<code>_layouts</code> directory.
|
||||
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
Using <code>null</code> will produce a file without using a layout
|
||||
file. However this is overridden if the file is a post/document and has a
|
||||
Using <code>null</code> will produce a file without using a layout
|
||||
file. However this is overridden if the file is a post/document and has a
|
||||
layout defined in the <a href="../configuration/#front-matter-defaults">
|
||||
frontmatter defaults</a>.
|
||||
</li>
|
||||
|
|
@ -129,14 +129,14 @@ data that is sent to the Liquid templating engine during the conversion. For
|
|||
instance, if you set a title, you can use that in your layout to set the page
|
||||
title:
|
||||
|
||||
```html
|
||||
```liquid
|
||||
<!DOCTYPE HTML>
|
||||
<html>
|
||||
<head>
|
||||
<title>{% raw %}{{ page.title }}{% endraw %}</title>
|
||||
</head>
|
||||
<body>
|
||||
...
|
||||
…
|
||||
```
|
||||
|
||||
## Predefined Variables for Posts
|
||||
|
|
@ -167,7 +167,7 @@ These are available out-of-the-box to be used in the front matter for a post.
|
|||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p style="margin-bottom: 5px;"><code>category</code></p>
|
||||
<p><code>category</code></p>
|
||||
<p><code>categories</code></p>
|
||||
</td>
|
||||
<td>
|
||||
|
|
|
|||
|
|
@ -60,14 +60,14 @@ branch to GitHub. However, the subdirectory-like URL structure GitHub uses for
|
|||
Project Pages complicates the proper resolution of URLs. In order to assure your
|
||||
site builds properly, use the handy [URL filters](../templates/#filters):
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
```liquid
|
||||
<!-- For styles with static names... -->
|
||||
<link href="{{ "/assets/css/style.css" | relative_url }}" rel="stylesheet">
|
||||
<!-- For documents/pages whose URLs can change... -->
|
||||
[{{ page.title }}]("{{ page.url | relative_url }}")
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This way you can preview your site locally from the site root on localhost,
|
||||
but when GitHub generates your pages from the `gh-pages` branch all the URLs
|
||||
|
|
|
|||
|
|
@ -5,9 +5,11 @@ permalink: /docs/includes/
|
|||
|
||||
The `include` tag allows you to include the content from another file stored in the `_includes` folder:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include footer.html %}{% endraw %}
|
||||
{% include footer.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Jekyll will look for the referenced file (in this case, `footer.html`) in the `_includes` directory at the root of your source directory and insert its contents.
|
||||
|
||||
|
|
@ -15,9 +17,11 @@ Jekyll will look for the referenced file (in this case, `footer.html`) in the `_
|
|||
|
||||
You can choose to include file fragments relative to the current file by using the `include_relative` tag:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include_relative somedir/footer.html %}{% endraw %}
|
||||
{% include_relative somedir/footer.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You won't need to place your included content within the `_includes` directory. Instead,
|
||||
the inclusion is specifically relative to the file where the tag is being used. For example,
|
||||
|
|
@ -42,9 +46,11 @@ my_variable: footer_company_a.html
|
|||
|
||||
You could then reference that variable in your include:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include {{ page.my_variable }} %}{% endraw %}
|
||||
{% include {{ page.my_variable }} %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
In this example, the include would insert the file `footer_company_a.html` from the `_includes/footer_company_a.html` directory.
|
||||
|
||||
|
|
@ -52,18 +58,22 @@ In this example, the include would insert the file `footer_company_a.html` from
|
|||
|
||||
You can also pass parameters to an include. For example, suppose you have a file called `note.html` in your `_includes` folder that contains this formatting:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}<div markdown="span" class="alert alert-info" role="alert">
|
||||
<div markdown="span" class="alert alert-info" role="alert">
|
||||
<i class="fa fa-info-circle"></i> <b>Note:</b>
|
||||
{{ include.content }}
|
||||
</div>{% endraw %}
|
||||
</div>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The `{% raw %}{{ include.content }}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include note.html content="This is my sample note." %} {% endraw %}
|
||||
{% include note.html content="This is my sample note." %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The value of `content` (which is `This is my sample note`) will be inserted into the {% raw %}`{{ include.content }}`{% endraw %} parameter.
|
||||
|
||||
|
|
@ -82,14 +92,16 @@ For example, suppose you have a special image syntax with complex formatting, an
|
|||
|
||||
You could templatize this content in your include and make each value available as a parameter, like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}<figure>
|
||||
<figure>
|
||||
<a href="{{ include.url }}">
|
||||
<img src="{{ include.file }}" style="max-width: {{ include.max-width }};"
|
||||
alt="{{ include.alt }}"/>
|
||||
<figcaption>{{ include.caption }}</figcaption>
|
||||
</figure>{% endraw %}
|
||||
</figure>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This include contains 5 parameters:
|
||||
|
||||
|
|
@ -101,15 +113,17 @@ This include contains 5 parameters:
|
|||
|
||||
Here's an example that passes all the parameters to this include (the include file is named `image.html`):
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include image.html url="http://jekyllrb.com"
|
||||
{% include image.html url="http://jekyllrb.com"
|
||||
max-width="200px" file="logo.png" alt="Jekyll logo"
|
||||
caption="This is the Jekyll logo." %} {% endraw %}
|
||||
caption="This is the Jekyll logo." %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The result is the original HTML code shown earlier.
|
||||
|
||||
To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://help.shopify.com/themes/liquid/filters/additional-filters#default).
|
||||
To safeguard situations where users don't supply a value for the parameter, you can use [Liquid's default filter](https://shopify.github.io/liquid/filters/default/).
|
||||
|
||||
Overall, you can create includes that act as templates for a variety of uses — inserting audio or video clips, alerts, special formatting, and more. However, note that you should avoid using too many includes, as this will slow down the build time of your site. For example, don't use includes every time you insert an image. (The above technique shows a use case for special images.)
|
||||
|
||||
|
|
@ -121,16 +135,21 @@ The string you pass to your include parameter can't contain curly braces. For ex
|
|||
|
||||
If you want to include this variable in your parameter that you pass to an include, you need to store the entire parameter as a variable before passing it to the include. You can use `capture` tags to create the variable:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% capture download_note %}The latest version of
|
||||
{{ site.product_name }} is now available.{% endcapture %}{% endraw %}
|
||||
{% capture download_note %}
|
||||
The latest version of {{ site.product_name }} is now available.
|
||||
{% endcapture %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Then pass this captured variable into the parameter for the include. Omit the quotation marks around the parameter content because it's no longer a string (it's a variable):
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include note.html content=download_note %}{% endraw %}
|
||||
{% include note.html content=download_note %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Passing references to YAML files as parameter values
|
||||
|
||||
|
|
@ -150,18 +169,22 @@ Here's an example. In the `_data` folder, suppose you have a YAML file called `p
|
|||
|
||||
In the `_includes` folder, assume you have a file called `spotlight.html` with this code:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% for person in include.participants %}
|
||||
{% for person in include.participants %}
|
||||
{% if person.login_age == "new" %}
|
||||
{{ person.name }}
|
||||
{% endif %}
|
||||
{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Now when you insert the `spotlight.html` include file, you can submit the YAML file as a parameter:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% include spotlight.html participants=site.data.profiles %}
|
||||
```
|
||||
{% raw %}{% include spotlight.html participants=site.data.profiles %}{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
In this instance, `site.data.profiles` gets inserted in place of {% raw %}`include.participants`{% endraw %} in the include file, and the Liquid logic processes. The result will be `Jane Doe`.
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ development of Jekyll itself.
|
|||
Jekyll is a simple, blog-aware, static site generator. It takes a template
|
||||
directory containing raw text files in various formats, runs it through
|
||||
a converter (like [Markdown](https://daringfireball.net/projects/markdown/))
|
||||
and our [Liquid](https://github.com/Shopify/liquid/wiki) renderer, and
|
||||
and our [Liquid](https://shopify.github.io/liquid/) renderer, and
|
||||
spits out a complete, ready-to-publish static website suitable
|
||||
for serving with your favorite web server. Jekyll also happens to be the engine
|
||||
behind [GitHub Pages](https://pages.github.com), which means you can use Jekyll
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ your `_config.yml` under `plugins`. For Jekyll 2, this is standard.
|
|||
|
||||
## Enable pagination
|
||||
|
||||
To enable pagination for your blog, add a line to the `_config.yml` file that
|
||||
To enable pagination for posts on your blog, add a line to the `_config.yml` file that
|
||||
specifies how many items should be displayed per page:
|
||||
|
||||
```yaml
|
||||
|
|
@ -55,6 +55,14 @@ directory.
|
|||
</p>
|
||||
</div>
|
||||
|
||||
<div class="note info">
|
||||
<h5>Pagination for categories, tags and collections</h5>
|
||||
<p>
|
||||
The more recent <a href="https://github.com/sverrirs/jekyll-paginate-v2">jekyll-paginate-v2</a> plugin supports more features. See the <a href="https://github.com/sverrirs/jekyll-paginate-v2/tree/master/examples">pagination examples</a> in the repository.
|
||||
<strong>This plugin is not supported by GitHub Pages</strong>.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
## Liquid Attributes Available
|
||||
|
||||
The pagination plugin exposes the `paginator` liquid object with the following
|
||||
|
|
@ -145,8 +153,8 @@ the `paginator` variable that will now be available to you. You’ll probably
|
|||
want to do this in one of the main pages of your site. Here’s one example of a
|
||||
simple way of rendering paginated Posts in a HTML file:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
title: My Blog
|
||||
|
|
@ -177,8 +185,8 @@ title: My Blog
|
|||
<span class="next ">Next</span>
|
||||
{% endif %}
|
||||
</div>
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
<div class="note warning">
|
||||
<h5>Beware the page one edge-case</h5>
|
||||
|
|
@ -192,8 +200,8 @@ title: My Blog
|
|||
The following HTML snippet should handle page one, and render a list of each
|
||||
page with links to all but the current page.
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if paginator.total_pages > 1 %}
|
||||
<div class="pagination">
|
||||
{% if paginator.previous_page %}
|
||||
|
|
@ -219,5 +227,5 @@ page with links to all but the current page.
|
|||
{% endif %}
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
|
|
|||
|
|
@ -387,11 +387,11 @@ Liquid::Template.register_tag('render_time', Jekyll::RenderTimeTag)
|
|||
In the example above, we can place the following tag anywhere in one of our
|
||||
pages:
|
||||
|
||||
```ruby
|
||||
{% raw %}
|
||||
```ruby
|
||||
<p>{% render_time page rendered at: %}</p>
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
And we would get something like this on the page:
|
||||
|
||||
|
|
|
|||
|
|
@ -80,53 +80,52 @@ out where to store these files in your site is something everyone will face.
|
|||
|
||||
There are a number of ways to include digital assets in Jekyll.
|
||||
One common solution is to create a folder in the root of the project directory
|
||||
called something like `assets` or `downloads`, into which any images, downloads
|
||||
called something like `assets`, into which any images, files
|
||||
or other resources are placed. Then, from within any post, they can be linked
|
||||
to using the site’s root as the path for the asset to include. Again, this will
|
||||
depend on the way your site’s (sub)domain and path are configured, but here are
|
||||
some examples (in Markdown) of how you could do this using the `site.url`
|
||||
variable in a post.
|
||||
some examples in Markdown of how you could do this using the `absolute_url`
|
||||
filter in a post.
|
||||
|
||||
Including an image asset in a post:
|
||||
|
||||
```text
|
||||
{% raw %}
|
||||
```markdown
|
||||
... which is shown in the screenshot below:
|
||||
|
||||
![My helpful screenshot]({{ "/assets/screenshot.jpg" | absolute_url }})
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Linking to a PDF for readers to download:
|
||||
|
||||
```text
|
||||
... you can [get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf) directly.
|
||||
{% raw %}
|
||||
```markdown
|
||||
... you can [get the PDF]({{ "/assets/mydoc.pdf" | absolute_url }}) directly.
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
<div class="info">
|
||||
|
||||
<div class="note">
|
||||
<h5>ProTip™: Link using just the site root URL</h5>
|
||||
<p>
|
||||
You can skip the <code>{% raw %}{{ site.url }}{% endraw %}</code> variable
|
||||
if you <strong>know</strong> your site will only ever be displayed at the
|
||||
root URL of your domain. In this case you can reference assets directly with
|
||||
just <code>/path/file.jpg</code>.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
## A typical post
|
||||
|
||||
Jekyll can handle many different iterations of the idea you might associate with a "post," however a standard blog style post, including a Title, Layout, Publishing Date, and Categories might look like this:
|
||||
|
||||
```
|
||||
```markdown
|
||||
---
|
||||
layout: post
|
||||
title: "Welcome to Jekyll!"
|
||||
date: 2015-11-17 16:16:01 -0600
|
||||
categories: jekyll update
|
||||
---
|
||||
|
||||
You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `bundle exec jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.
|
||||
|
||||
To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.
|
||||
|
||||
```
|
||||
Everything in between the first and second `---` are part of the YAML Front Matter, and everything after the second `---` will be rendered with Markdown and show up as "Content."
|
||||
|
||||
Everything in between the first and second `---` are part of the YAML Front Matter, and everything after the second `---` will be rendered with Markdown and show up as "Content".
|
||||
|
||||
## Displaying an index of posts
|
||||
|
||||
|
|
@ -136,15 +135,17 @@ you have a list of posts somewhere. Creating an index of posts on another page
|
|||
language](https://docs.shopify.com/themes/liquid/basics) and its tags. Here’s a
|
||||
basic example of how to create a list of links to your blog posts:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<ul>
|
||||
{% raw %}{% for post in site.posts %}{% endraw %}
|
||||
{% for post in site.posts %}
|
||||
<li>
|
||||
<a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
|
||||
<a href="{{ post.url }}">{{ post.title }}</a>
|
||||
</li>
|
||||
{% raw %}{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Of course, you have full control over how (and where) you display your posts,
|
||||
and how you structure your site. You should read more about [how templates
|
||||
|
|
@ -170,24 +171,27 @@ a basic example of how to create a list of posts from a specific category.
|
|||
|
||||
First, in the `_layouts` directory create a new file called `category.html` - in
|
||||
that file put (at least) the following:
|
||||
```
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
layout: page
|
||||
---
|
||||
|
||||
{% for post in site.categories[page.category] %}
|
||||
<a href="{{ post.url | prepend: site.baseurl }}">
|
||||
<a href="{{ post.url | absolute_url }}">
|
||||
{{ post.title }}
|
||||
</a>
|
||||
<hr>
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Next, in the root directory of your Jekyll install, create a new directory
|
||||
called `category` and then create a file for each category you want to list. For
|
||||
example, if you have a category `blog` then create a file in the new directory
|
||||
called `blog.html` with at least
|
||||
|
||||
```text
|
||||
```yaml
|
||||
---
|
||||
layout: category
|
||||
title: Blog
|
||||
|
|
@ -208,31 +212,35 @@ Take the above example of an index of posts. Perhaps you want to include
|
|||
a little hint about the post's content by adding the first paragraph of each of
|
||||
your posts:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
```liquid
|
||||
<ul>
|
||||
{% raw %}{% for post in site.posts %}{% endraw %}
|
||||
{% for post in site.posts %}
|
||||
<li>
|
||||
<a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
|
||||
{% raw %}{{ post.excerpt }}{% endraw %}
|
||||
<a href="{{ post.url }}">{{ post.title }}</a>
|
||||
{{ post.excerpt }}
|
||||
</li>
|
||||
{% raw %}{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Because Jekyll grabs the first paragraph you will not need to wrap the excerpt
|
||||
in `p` tags, which is already done for you. These tags can be removed with the
|
||||
following if you'd prefer:
|
||||
|
||||
```html
|
||||
{% raw %}{{ post.excerpt | remove: '<p>' | remove: '</p>' }}{% endraw %}
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ post.excerpt | remove: '<p>' | remove: '</p>' }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
If you don't like the automatically-generated post excerpt, it can be
|
||||
explicitly overridden by adding an `excerpt` value to your post's YAML
|
||||
Front Matter. Alternatively, you can choose to define a custom
|
||||
`excerpt_separator` in the post's YAML front matter:
|
||||
|
||||
```text
|
||||
```yaml
|
||||
---
|
||||
excerpt_separator: <!--more-->
|
||||
---
|
||||
|
|
@ -259,8 +267,9 @@ Jekyll also has built-in support for syntax highlighting of code snippets using
|
|||
either Pygments or Rouge, and including a code snippet in any post is easy.
|
||||
Just use the dedicated Liquid tag as follows:
|
||||
|
||||
```text
|
||||
{% raw %}{% highlight ruby %}{% endraw %}
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% highlight ruby %}
|
||||
def show
|
||||
@widget = Widget(params[:id])
|
||||
respond_to do |format|
|
||||
|
|
@ -268,8 +277,9 @@ def show
|
|||
format.json { render json: @widget }
|
||||
end
|
||||
end
|
||||
{% raw %}{% endhighlight %}{% endraw %}
|
||||
{% endhighlight %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
And the output will look like this:
|
||||
|
||||
|
|
|
|||
|
|
@ -66,13 +66,13 @@ following metadata:
|
|||
</table>
|
||||
</div>
|
||||
|
||||
Note that in the above table, `file` can be anything. It's simply an arbitrarily set variable used in your own logic (such as in a for loop). It isn't a global site or page variable.
|
||||
Note that in the above table, `file` can be anything. It's simply an arbitrarily set variable used in your own logic (such as in a for loop). It isn't a global site or page variable.
|
||||
|
||||
## Add front matter to static files
|
||||
|
||||
Although you can't directly add front matter values to static files, you can set front matter values through the [defaults property](../configuration/#front-matter-defaults) in your configuration file. When Jekyll builds the site, it will use the front matter values you set.
|
||||
Although you can't directly add front matter values to static files, you can set front matter values through the [defaults property](../configuration/#front-matter-defaults) in your configuration file. When Jekyll builds the site, it will use the front matter values you set.
|
||||
|
||||
Here's an example:
|
||||
Here's an example:
|
||||
|
||||
In your `_config.yml` file, add the following values to the `defaults` property:
|
||||
|
||||
|
|
@ -88,11 +88,13 @@ This assumes that your Jekyll site has a folder path of `assets/img` where you
|
|||
|
||||
Suppose you want to list all your image assets as contained in `assets/img`. You could use this for loop to look in the `static_files` object and get all static files that have this front matter property:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% assign image_files = site.static_files | where: "image", true %}
|
||||
{% assign image_files = site.static_files | where: "image", true %}
|
||||
{% for myimage in image_files %}
|
||||
{{ myimage.path }}
|
||||
{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
When you build your site, the output will list the path to each file that meets this front matter condition.
|
||||
|
|
|
|||
|
|
@ -428,9 +428,11 @@ The default is `default`. They are as follows (with what they filter):
|
|||
|
||||
If you have small page snippets that you want to include in multiple places on your site, save the snippets as *include files* and insert them where required, by using the `include` tag:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include footer.html %}{% endraw %}
|
||||
{% include footer.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Jekyll expects all *include files* to be placed in an `_includes` directory at the root of your source directory. In the above example, this will embed the contents of `_includes/footer.html` into the calling file.
|
||||
|
||||
|
|
@ -451,15 +453,15 @@ languages](http://pygments.org/languages/)
|
|||
|
||||
To render a code block with syntax highlighting, surround your code as follows:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% highlight ruby %}
|
||||
def foo
|
||||
puts 'foo'
|
||||
end
|
||||
{% endhighlight %}
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The argument to the `highlight` tag (`ruby` in the example above) is the
|
||||
language identifier. To find the appropriate identifier to use for the language
|
||||
|
|
@ -474,15 +476,15 @@ Including the `linenos` argument will force the highlighted code to include line
|
|||
numbers. For instance, the following code block would include line numbers next
|
||||
to each line:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% highlight ruby linenos %}
|
||||
def foo
|
||||
puts 'foo'
|
||||
end
|
||||
{% endhighlight %}
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
#### Stylesheets for syntax highlighting
|
||||
|
||||
|
|
@ -503,25 +505,25 @@ To link to a post, a page, collection item, or file, the `link` tag will generat
|
|||
|
||||
You must include the file's original extension when using the `link` tag. Here are some examples:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ site.baseurl }}{% link _collection/name-of-document.md %}
|
||||
{{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %}
|
||||
{{ site.baseurl }}{% link news/index.html %}
|
||||
{{ site.baseurl }}{% link /assets/files/doc.pdf %}
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You can also use the `link` tag to create a link in Markdown as follows:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
[Link to a document]({{ site.baseurl }}{% link _collection/name-of-document.md %})
|
||||
[Link to a post]({{ site.baseurl }}{% link _posts/2016-07-26-name-of-post.md %})
|
||||
[Link to a page]({{ site.baseurl }}{% link news/index.html %})
|
||||
[Link to a file]({{ site.baseurl }}{% link /assets/files/doc.pdf %})
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
(Including `{% raw %}{{ site.baseurl }}{% endraw %}` is optional — it depends on whether you want to preface the page URL with the `baseurl` value.)
|
||||
|
||||
|
|
@ -539,26 +541,26 @@ Note you cannot add filters to `link` tags. For example, you cannot append a str
|
|||
|
||||
If you want to include a link to a post on your site, the `post_url` tag will generate the correct permalink URL for the post you specify.
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ site.baseurl }}{% post_url 2010-07-21-name-of-post %}
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
If you organize your posts in subdirectories, you need to include subdirectory path to the post:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ site.baseurl }}{% post_url /subdir/2010-07-21-name-of-post %}
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
There is no need to include the file extension when using the `post_url` tag.
|
||||
|
||||
You can also use this tag to create a link to a post in Markdown as follows:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
[Name of Link]({{ site.baseurl }}{% post_url 2010-07-21-name-of-post %})
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
|
|
|||
|
|
@ -88,7 +88,7 @@ With a clear understanding of the theme's files, you can now override any theme
|
|||
|
||||
Let's say, for a second example, you want to override Minima's footer. In your Jekyll site, create an `_includes` folder and add a file in it called `footer.html`. Jekyll will now use your site's `footer.html` file instead of the `footer.html` file from the Minima theme gem.
|
||||
|
||||
To modify any stylesheet you must take the extra step of also copying the main sass file (`_sass/minima.scss` in the Minima theme) into the `_sass` directory in your site's source.
|
||||
To modify any stylesheet you must take the extra step of also copying the main sass file (`_sass/minima.scss` in the Minima theme) into the `_sass` directory in your site's source.
|
||||
|
||||
Jekyll will look first to your site's content before looking to the theme's defaults for any requested file in the following folders:
|
||||
|
||||
|
|
@ -218,13 +218,15 @@ _sass
|
|||
|
||||
Your theme's styles can be included in the user's stylesheet using the `@import` directive.
|
||||
|
||||
{% raw %}
|
||||
```css
|
||||
{% raw %}@import "{{ site.theme }}";{% endraw %}
|
||||
@import "{{ site.theme }}";
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Theme-gem dependencies
|
||||
|
||||
From `v3.5`, Jekyll will automatically require all whitelisted `runtime_dependencies` of your theme-gem even if they're not explicitly included under the `gems` array in the site's config file. (NOTE: whitelisting is only required when building or serving with the `--safe` option.)
|
||||
From `v3.5`, Jekyll will automatically require all whitelisted `runtime_dependencies` of your theme-gem even if they're not explicitly included under the `plugins` array in the site's config file. (Note: whitelisting is only required when building or serving with the `--safe` option.)
|
||||
|
||||
With this, the end-user need not keep track of the plugins required to be included in their config file for their theme-gem to work as intended.
|
||||
|
||||
|
|
|
|||
|
|
@ -65,7 +65,7 @@ sudo emerge -av dev-ruby/rubygems
|
|||
On Windows, you may need to install [RubyInstaller
|
||||
DevKit](https://wiki.github.com/oneclick/rubyinstaller/development-kit).
|
||||
|
||||
On Android (with Termux) you can install all requirements by running:
|
||||
On Android (with Termux) you can install all requirements by running:
|
||||
|
||||
```sh
|
||||
apt update && apt install libffi-dev clang ruby-dev make
|
||||
|
|
@ -261,7 +261,7 @@ The issue is caused by trying to copy a non-existing symlink.
|
|||
<div class="note">
|
||||
<h5>Please report issues you encounter!</h5>
|
||||
<p>
|
||||
If you come across a bug, please <a href="{{ site.help_url }}/issues/new">create an issue</a>
|
||||
If you come across a bug, please <a href="{{ site.repository }}/issues/new">create an issue</a>
|
||||
on GitHub describing the problem and any work-arounds you find so we can
|
||||
document it here for others.
|
||||
</p>
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ and 2.0 that you'll want to know about.
|
|||
Before we dive in, go ahead and fetch the latest version of Jekyll:
|
||||
|
||||
```sh
|
||||
$ gem update jekyll
|
||||
gem update jekyll
|
||||
```
|
||||
|
||||
<div class="note feature">
|
||||
|
|
|
|||
|
|
@ -3,20 +3,21 @@ title: Upgrading from 2.x to 3.x
|
|||
permalink: /docs/upgrading/2-to-3/
|
||||
---
|
||||
|
||||
Upgrading from an older version of Jekyll? A few things have changed in 3.0
|
||||
Upgrading from an older version of Jekyll? A few things have changed in Jekyll 3
|
||||
that you'll want to know about.
|
||||
|
||||
Before we dive in, go ahead and fetch the latest version of Jekyll:
|
||||
|
||||
```sh
|
||||
$ gem update jekyll
|
||||
gem update jekyll
|
||||
```
|
||||
|
||||
Please note: Jekyll 3.2 requires Ruby version >= 2.1
|
||||
Since v3.2 Jekyll requires Ruby version >= 2.1
|
||||
{: .note .warning }
|
||||
|
||||
<div class="note feature">
|
||||
<h5 markdown="1">Diving in</h5>
|
||||
<p markdown="1">Want to get a new Jekyll site up and running quickly? Simply
|
||||
<h5>Diving in</h5>
|
||||
<p>Want to get a new Jekyll site up and running quickly? Simply
|
||||
run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
|
||||
Jekyll site.</p>
|
||||
</div>
|
||||
|
|
@ -68,7 +69,7 @@ generate when running `jekyll build` or `jekyll serve`.
|
|||
<h5>Future Posts on GitHub Pages</h5>
|
||||
<p>
|
||||
An exception to the above rule are GitHub Pages sites, where the <code>--future</code> flag remains <em>enabled</em>
|
||||
by default to maintain historical consistency for those sites.
|
||||
by default to maintain historical consistency for those sites.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
|
|
|||
|
|
@ -7,22 +7,22 @@ The Jekyll gem makes a `jekyll` executable available to you in your Terminal
|
|||
window. You can use this command in a number of ways:
|
||||
|
||||
```sh
|
||||
$ jekyll build
|
||||
jekyll build
|
||||
# => The current folder will be generated into ./_site
|
||||
|
||||
$ jekyll build --destination <destination>
|
||||
jekyll build --destination <destination>
|
||||
# => The current folder will be generated into <destination>
|
||||
|
||||
$ jekyll build --source <source> --destination <destination>
|
||||
jekyll build --source <source> --destination <destination>
|
||||
# => The <source> folder will be generated into <destination>
|
||||
|
||||
$ jekyll build --watch
|
||||
jekyll build --watch
|
||||
# => The current folder will be generated into ./_site,
|
||||
# watched for changes, and regenerated automatically.
|
||||
```
|
||||
|
||||
<div class="note info">
|
||||
<h5>Changes to _config.yml are not included during automatic regeneration.</h5>
|
||||
<h5>Changes to <code>_config.yml</code> are not included during automatic regeneration.</h5>
|
||||
<p>
|
||||
The <code>_config.yml</code> master configuration file contains global configurations
|
||||
and variable definitions that are read once at execution time. Changes made to <code>_config.yml</code>
|
||||
|
|
@ -52,25 +52,22 @@ Jekyll also comes with a built-in development server that will allow you to
|
|||
preview what the generated site will look like in your browser locally.
|
||||
|
||||
```sh
|
||||
$ jekyll serve
|
||||
jekyll serve
|
||||
# => A development server will run at http://localhost:4000/
|
||||
# Auto-regeneration: enabled. Use `--no-watch` to disable.
|
||||
|
||||
$ jekyll serve --detach
|
||||
jekyll serve --detach
|
||||
# => Same as `jekyll serve` but will detach from the current terminal.
|
||||
# If you need to kill the server, you can `kill -9 1234` where "1234" is the PID.
|
||||
# If you cannot find the PID, then do, `ps aux | grep jekyll` and kill the instance.
|
||||
```
|
||||
|
||||
<div class="note info">
|
||||
<h5>Be aware of default behavior</h5>
|
||||
<p>
|
||||
As of version 2.4, the <code>serve</code> command will watch for changes automatically. To disable this, you can use <code>jekyll serve --no-watch</code>, which preserves the old behavior.
|
||||
</p>
|
||||
<div class="note tip">
|
||||
<h5>Livereload</h5>
|
||||
<p>If you want to enable Livereload, you can enable the <a href="https://github.com/RobertDeRose/jekyll-livereload">jekyll-livereload</a> plugin in a <a href="../configuration/#build-command-options">development config file</a>.</p>
|
||||
</div>
|
||||
|
||||
```sh
|
||||
$ jekyll serve --no-watch
|
||||
jekyll serve --no-watch
|
||||
# => Same as `jekyll serve` but will not watch for changes.
|
||||
```
|
||||
|
||||
|
|
@ -89,8 +86,8 @@ destination: _deploy
|
|||
Then the following two commands will be equivalent:
|
||||
|
||||
```sh
|
||||
$ jekyll build
|
||||
$ jekyll build --source _source --destination _deploy
|
||||
jekyll build
|
||||
jekyll build --source _source --destination _deploy
|
||||
```
|
||||
|
||||
For more about the possible configuration options, see the
|
||||
|
|
|
|||
|
|
@ -17,17 +17,17 @@ If you are using Windows 10 Anniversary Update, the easiest way to run Jekyll is
|
|||
|
||||
First let's make sure all our packages / repositories are up to date. Open a new Command Prompt instance, and type the following:
|
||||
|
||||
```
|
||||
```sh
|
||||
bash
|
||||
```
|
||||
Your Command Prompt instance should now be a Bash instance. Now we must update our repo lists and packages.
|
||||
|
||||
```
|
||||
```sh
|
||||
sudo apt-get update -y && sudo apt-get upgrade -y
|
||||
```
|
||||
Now we can install Ruby. To do this we will use a repository from [BrightBox](https://www.brightbox.com/docs/ruby/ubuntu/), which hosts optimized versions of Ruby for Ubuntu.
|
||||
|
||||
```
|
||||
```sh
|
||||
sudo apt-add-repository ppa:brightbox/ruby-ng
|
||||
sudo apt-get update
|
||||
sudo apt-get install ruby2.3 ruby2.3-dev build-essential
|
||||
|
|
@ -35,19 +35,19 @@ sudo apt-get install ruby2.3 ruby2.3-dev build-essential
|
|||
|
||||
Next let's update our Ruby gems:
|
||||
|
||||
```
|
||||
```sh
|
||||
sudo gem update
|
||||
```
|
||||
|
||||
Now all that is left to do is install Jekyll.
|
||||
|
||||
```
|
||||
```sh
|
||||
sudo gem install jekyll bundler
|
||||
```
|
||||
|
||||
Check if Jekyll installed properly by running:
|
||||
|
||||
```
|
||||
```sh
|
||||
jekyll -v
|
||||
```
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ jekyll -v
|
|||
|
||||
To start a new project named `my_blog`, just run:
|
||||
|
||||
```
|
||||
```sh
|
||||
jekyll new my_blog
|
||||
```
|
||||
|
||||
|
|
@ -122,14 +122,14 @@ This gem is also needed in the github-pages and to get it running on Windows x64
|
|||
|
||||
**Note:** In the current [pre release][nokogiriFails] it works out of the box with Windows x64 but this version is not referenced in the github-pages.
|
||||
|
||||
`choco install libxml2 -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
|
||||
```sh
|
||||
choco install libxml2 -Source "https://www.nuget.org/api/v2/"
|
||||
|
||||
`choco install libxslt -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
|
||||
choco install libxslt -Source "https://www.nuget.org/api/v2/"
|
||||
|
||||
`choco install libiconv -Source "https://www.nuget.org/api/v2/"`{:.language-ruby}
|
||||
choco install libiconv -Source "https://www.nuget.org/api/v2/
|
||||
|
||||
```ruby
|
||||
gem install nokogiri --^
|
||||
gem install nokogiri --^
|
||||
--with-xml2-include=C:\Chocolatey\lib\libxml2.2.7.8.7\build\native\include^
|
||||
--with-xml2-lib=C:\Chocolatey\lib\libxml2.redist.2.7.8.7\build\native\bin\v110\x64\Release\dynamic\cdecl^
|
||||
--with-iconv-include=C:\Chocolatey\lib\libiconv.1.14.0.11\build\native\include^
|
||||
|
|
@ -138,7 +138,7 @@ This gem is also needed in the github-pages and to get it running on Windows x64
|
|||
--with-xslt-lib=C:\Chocolatey\lib\libxslt.redist.1.1.28.0\build\native\bin\v110\x64\Release\dynamic
|
||||
```
|
||||
|
||||
#### Install github-pages
|
||||
#### Install github-pages
|
||||
|
||||
* Open command prompt and install [Bundler][]: `gem install bundler`
|
||||
* Create a file called `Gemfile` without any extension in your root directory of your blog
|
||||
|
|
@ -165,14 +165,10 @@ In the future the installation process of the github-pages should be as simple a
|
|||
[Bundler]: http://bundler.io/ "Ruby Dependencie Manager"
|
||||
[nokogiriReleases]: https://github.com/sparklemotion/nokogiri/releases "Nokogiri Releases"
|
||||
|
||||
---
|
||||
|
||||
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].
|
||||
|
||||
Optionally you can use [Autoinstall Jekyll for Windows][fastjekyll-autoinstall].
|
||||
|
||||
---
|
||||
|
||||
[windows-installjekyll3]: https://labs.sverrirs.com/jekyll/
|
||||
[fastjekyll-autoinstall]: https://github.com/KeJunMao/fastjekyll#autoinstall-jekyll-for-windows
|
||||
|
||||
|
|
@ -185,11 +181,11 @@ Jekyll. This is especially relevant when you're running Jekyll on Windows.
|
|||
Additionally, you might need to change the code page of the console window to UTF-8 in case you get a "Liquid Exception: Incompatible character encoding" error during the site generation process. It can be done with the following command:
|
||||
|
||||
```sh
|
||||
$ chcp 65001
|
||||
chcp 65001
|
||||
```
|
||||
|
||||
|
||||
## Time-Zone Management
|
||||
## Time-Zone Management
|
||||
|
||||
Since Windows doesn't have a native source of zoneinfo data, the Ruby Interpreter would not understand IANA Timezones and hence using them had the `TZ` environment variable default to UTC/GMT 00:00.
|
||||
Though Windows users could alternatively define their blog's timezone by setting the key to use POSIX format of defining timezones, it wasn't as user-friendly when it came to having the clock altered to changing DST-rules.
|
||||
|
|
@ -205,9 +201,9 @@ gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
|
|||
[IANA-database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
|
||||
|
||||
|
||||
## Auto Regeneration
|
||||
## Auto Regeneration
|
||||
|
||||
As of v1.3.0, Jekyll uses the `listen` gem to watch for changes when the `--watch` switch is specified during a build or serve. While `listen` has built-in support for UNIX systems, it may require an extra gem for compatibility with Windows.
|
||||
Jekyll uses the `listen` gem to watch for changes when the `--watch` switch is specified during a build or serve. While `listen` has built-in support for UNIX systems, it may require an extra gem for compatibility with Windows.
|
||||
|
||||
Add the following to the Gemfile for your site if you have issues with auto-regeneration on Windows alone:
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Happy Holidays, everyone.
|
|||
|
||||
Jekyll v2.5.3 is a quick patch release, containing some minor fixes. See the
|
||||
[full history](/docs/history/) for more info. If you notice any problems,
|
||||
please [let us know]({{ site.help_url }}).
|
||||
please [let us know]({{ site.repository }}).
|
||||
|
||||
This release also marks the start of Jekyll 3 development. I wrote about it
|
||||
over on my personal blog: [Jekyll 3 — The Road Ahead](https://byparker.com/blog/2014/jekyll-3-the-road-ahead/).
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
.n { color: #ffffff} /* Name */
|
||||
.o { color: #ffffff} /* Operator */
|
||||
.x { color: #ffffff} /* Other */
|
||||
.p { color: #ffffff} /* Punctuation */
|
||||
.p { color: #98b9ef} /* Punctuation */
|
||||
.cm { color: #87ceeb} /* Comment.Multiline */
|
||||
.cp { color: #cd5c5c} /* Comment.Preproc */
|
||||
.c1 { color: #87ceeb} /* Comment.Single */
|
||||
|
|
@ -45,7 +45,7 @@
|
|||
.nx { color: #ffffff} /* Name.Other */
|
||||
.py { color: #ffffff} /* Name.Property */
|
||||
.nt { color: #f0e68c} /* Name.Tag */
|
||||
.nv { color: #98fb98} /* Name.Variable */
|
||||
.nv { color: #88d472} /* Name.Variable */
|
||||
.ow { color: #ffffff} /* Operator.Word */
|
||||
.w { color: #ffffff} /* Text.Whitespace */
|
||||
.mf { color: #ffffff} /* Literal.Number.Float */
|
||||
|
|
@ -69,10 +69,6 @@
|
|||
.vi { color: #98fb98} /* Name.Variable.Instance */
|
||||
.il { color: #ffffff} /* Literal.Number.Integer.Long */
|
||||
.bash .nv {
|
||||
-webkit-user-select: none;
|
||||
-moz-user-select: none;
|
||||
-ms-user-select: none;
|
||||
-o-user-select: none;
|
||||
user-select: none;
|
||||
user-select: none;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -306,7 +306,7 @@ At minimum, a layout should contain `{% raw %}{{ content }}{% endraw %}`, which
|
|||
|
||||
### For loops
|
||||
|
||||
By the way, let's pause here to look at the `for` loop logic a little more closely. [For loops in Liquid](https://help.shopify.com/themes/liquid/tags/iteration-tags#for) are one of the most commonly used Liquid tags. *For loops* let you iterate through content in your Jekyll site and build out a result. The `for` loop also has [certain properties available](https://help.shopify.com/themes/liquid/objects/for-loops) (like first or last iteration) based on the loop's position in the loop as well.
|
||||
By the way, let's pause here to look at the `for` loop logic a little more closely. [For loops in Liquid](https://shopify.github.io/liquid/tags/iteration/) are one of the most commonly used Liquid tags. *For loops* let you iterate through content in your Jekyll site and build out a result. The `for` loop also has [certain properties available](https://help.shopify.com/themes/liquid/objects/for-loops) (like first or last iteration) based on the loop's position in the loop as well.
|
||||
|
||||
We've only scratched the surface of what you can do with `for` loops in retrieving posts. For example, if you wanted to display posts from a specific category, you could do so by adding a `categories` property to your post's front matter and then look in those categories. Further, you could limit the number of results by adding a `limit` property. Here's an example:
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Simply add a `404.md` or `404.html` at the root of your site's source directory
|
|||
|
||||
If you plan to organize your files under subdirectories, the error page should have the following Front Matter Data, set: `permalink: /404.html`. This is to ensure that the compiled `404.html` resides at the root of your processed site, where it'll be picked by the server.
|
||||
|
||||
```
|
||||
```markdown
|
||||
---
|
||||
# example 404.md
|
||||
|
||||
|
|
@ -34,19 +34,19 @@ Apache Web Servers load a configuration file named [`.htaccess`](http://www.htac
|
|||
|
||||
Simply add the following to your `.htaccess` file.
|
||||
|
||||
```
|
||||
```apache
|
||||
ErrorDocument 404 /404.html
|
||||
```
|
||||
|
||||
With an `.htaccess` file, you have the freedom to place your error page within a subdirectory.
|
||||
|
||||
```
|
||||
```apache
|
||||
ErrorDocument 404 /error_pages/404.html
|
||||
```
|
||||
|
||||
Where the path is relative to your site's domain.
|
||||
|
||||
More info on configuring Apache Error Pages can found in [official documentation](https://httpd.apache.org/docs/current/mod/core.html#errordocument).
|
||||
More info on configuring Apache Error Pages can found in [official documentation](https://httpd.apache.org/docs/current/mod/core.html#errordocument).
|
||||
|
||||
|
||||
## Hosting on Nginx server
|
||||
|
|
@ -55,7 +55,7 @@ The procedure is just as simple as configuring Apache servers, but slightly diff
|
|||
|
||||
Add the following to the nginx configuration file, `nginx.conf`, which is usually located inside `/etc/nginx/` or `/etc/nginx/conf/`:
|
||||
|
||||
```
|
||||
```nginx
|
||||
server {
|
||||
error_page 404 /404.html;
|
||||
location /404.html {
|
||||
|
|
@ -63,4 +63,5 @@ server {
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `location` directive prevents users from directly browsing the 404.html page.
|
||||
|
|
|
|||
|
|
@ -91,12 +91,14 @@ Suppose you wanted to sort the list by the `title`. To do this, convert the refe
|
|||
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% assign doclist = site.data.samplelist.docs | sort: 'title' %}
|
||||
{% assign doclist = site.data.samplelist.docs | sort: 'title' %}
|
||||
{% for item in doclist %}
|
||||
<li><a href="{{ item.url }}" alt="{{ item.title }}">{{ item.title }}</a></li>
|
||||
{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result**
|
||||
|
||||
|
|
@ -110,9 +112,11 @@ The items now appear in alphabetical order. The `sort` property in the Liquid fi
|
|||
|
||||
See the [Liquid array filter](https://help.shopify.com/themes/liquid/filters/array-filters) for more filter options. Note that you can't simply use this syntax:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% for item in site.data.samplelist.docs | sort: "title" %}{% endfor %}{% endraw %}
|
||||
{% for item in site.data.samplelist.docs | sort: "title" %}{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You have to convert `site.data.samplelist.docs` to a variable first using either `assign` or `capture` tags.
|
||||
|
||||
|
|
@ -152,16 +156,18 @@ toc:
|
|||
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% for item in site.data.samplelist.toc %}
|
||||
{% for item in site.data.samplelist.toc %}
|
||||
<h3>{{ item.title }}</h3>
|
||||
<ul>
|
||||
{% for entry in item.subfolderitems %}
|
||||
<li><a href="{{ entry.url }}">{{ entry.page }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result**
|
||||
<div class="highlight result">
|
||||
|
|
@ -242,8 +248,9 @@ toc2:
|
|||
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}<div>
|
||||
<div>
|
||||
{% if site.data.samplelist.toc2[0] %}
|
||||
{% for item in site.data.samplelist.toc2 %}
|
||||
<h3>{{ item.title }}</h3>
|
||||
|
|
@ -263,8 +270,9 @@ toc2:
|
|||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</div>{% endraw %}
|
||||
</div>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result**
|
||||
|
||||
|
|
@ -327,13 +335,16 @@ sidebar: toc
|
|||
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}<ul>
|
||||
<ul>
|
||||
{% for item in site.data.samplelist[page.sidebar] %}
|
||||
<li><a href="{{ item.url }}">{{ item.title }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>{% endraw %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result**
|
||||
|
||||
<div class="highlight result">
|
||||
|
|
@ -361,13 +372,15 @@ In addition to inserting items from the YAML data file into your list, you also
|
|||
```
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% for item in site.data.samplelist.docs %}
|
||||
{% for item in site.data.samplelist.docs %}
|
||||
<li class="{% if item.url == page.url %}active{% endif %}">
|
||||
<a href="{{ item.url }}">{{ item.title }}</a>
|
||||
</li>
|
||||
{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result**
|
||||
|
||||
|
|
@ -412,15 +425,17 @@ docs2:
|
|||
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}<ul>
|
||||
<ul>
|
||||
{% for item in site.data.samplelist.docs2 %}
|
||||
{% if item.version == 1 %}
|
||||
<li><a href="{{ item.url }}">{{ item.title }}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ul>{% endraw %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result**
|
||||
|
||||
|
|
@ -491,16 +506,18 @@ Note that even though `category` is used in the doc front matter, `category` is
|
|||
|
||||
If you wanted to simply get all docs in the collection for a specific category, you could use a `for` loop with an `if` condition to check for a specific category:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}<h3>Getting Started</h3>
|
||||
<h3>Getting Started</h3>
|
||||
<ul>
|
||||
{% for doc in site.docs %}
|
||||
{% if doc.category == "getting-started" %}
|
||||
<li><a href="{{ doc.url }}">{{ doc.title }}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ul>{% endraw %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The result would be as follows:
|
||||
|
||||
|
|
@ -523,8 +540,9 @@ Here's the code for getting lists of pages grouped under their corresponding cat
|
|||
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% assign mydocs = site.docs | group_by: 'category' %}
|
||||
{% assign mydocs = site.docs | group_by: 'category' %}
|
||||
{% for cat in mydocs %}
|
||||
<h2>{{ cat.name | capitalize }}</h2>
|
||||
<ul>
|
||||
|
|
@ -533,8 +551,9 @@ Here's the code for getting lists of pages grouped under their corresponding cat
|
|||
<li><a href="{{ item.url }}">{{ item.title }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endfor %}{% endraw %}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result**
|
||||
|
||||
|
|
@ -574,6 +593,6 @@ After getting the category name, we assign the variable `items` for the docs and
|
|||
|
||||
The `for item in items` loop looks through each `item` and gets the `title` and `url` to form the list item link.
|
||||
|
||||
For more details on the `group_by` filter, see [Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort](https://help.shopify.com/themes/liquid/filters/array-filters#sort) in Liquid's documentation.
|
||||
For more details on the `group_by` filter, see [Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort](https://shopify.github.io/liquid/filters/sort/) in Liquid's documentation.
|
||||
|
||||
Whether you use properties in your doc's front matter to retrieve your pages or a YAML data file, in both cases you can programmatically build a more robust navigation for your site.
|
||||
|
|
|
|||
|
|
@ -37,15 +37,19 @@ The following scenarios highlight potential problems you might encounter. These
|
|||
|
||||
In your layout file (`_layouts/default.html`), suppose you have a variable assigned:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% assign myvar = "joe" %}
|
||||
```
|
||||
{% raw %}{% assign myvar = "joe" %}{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
On a page that uses the layout, you reference that variable:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ myvar }}
|
||||
```
|
||||
{% raw %}{{ myvar }}{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The variable won't render because the page's order of interpretation is to render Liquid first and later process the Layout. When the Liquid rendering happens, the variable assignment isn't available.
|
||||
|
||||
|
|
@ -63,9 +67,11 @@ This is a list:
|
|||
|
||||
You include the file into an HTML file as follows:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include mycontent.md %}{% endraw %}
|
||||
{% include mycontent.md %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The Markdown is not processed because first the Liquid (`include` tag) gets processed, inserting `mycontent.md` into the HTML file. *Then* the Markdown would get processed.
|
||||
|
||||
|
|
@ -75,11 +81,13 @@ To make the code work, use HTML formatting in includes that are inserted into HT
|
|||
|
||||
Note that `highlight` tags don't require Markdown to process. Suppose your include contains the following:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% highlight javascript %}
|
||||
{% highlight javascript %}
|
||||
console.log('alert');
|
||||
{% endhighlight %}{% endraw %}
|
||||
{% endhighlight %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments for syntax highlighting.) As a result, this code will actually convert to HTML with syntax highlighting. Jekyll does not need the Markdown filter to process `highlight` tags.
|
||||
|
||||
|
|
@ -87,8 +95,9 @@ The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments
|
|||
|
||||
Suppose you try to mix Liquid's `assign` tag with JavaScript, like this:
|
||||
|
||||
{% raw %}
|
||||
```javascript
|
||||
{% raw %}<button onclick="someFunction()">Click me</button>
|
||||
<button onclick="someFunction()">Click me</button>
|
||||
|
||||
<p id="intro"></p>
|
||||
|
||||
|
|
@ -97,15 +106,17 @@ Suppose you try to mix Liquid's `assign` tag with JavaScript, like this:
|
|||
function someFunction() {
|
||||
document.getElementById("intro").innerHTML = someContent;
|
||||
}
|
||||
</script>{% endraw %}
|
||||
</script>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This won't work because the `assign` tag is only available during the Liquid rendering phase of the site. In this JavaScript example, the script executes when a user clicks a button ("Click me") on the HTML page. At that time, the Liquid logic is no longer available, so the `assign` tag wouldn't return anything.
|
||||
|
||||
However, you can use Jekyll's site variables or Liquid to *populate* a script that is executed at a later time. For example, suppose you have the following property in your front matter: `someContent: "This is some content"`. You could do this:
|
||||
|
||||
{% raw %}
|
||||
```js
|
||||
{% raw %}<button onclick="someFunction()">Click me</button>
|
||||
<button onclick="someFunction()">Click me</button>
|
||||
|
||||
<p id="intro"></p>
|
||||
|
||||
|
|
@ -114,8 +125,9 @@ However, you can use Jekyll's site variables or Liquid to *populate* a script th
|
|||
function someFunction() {
|
||||
document.getElementById("intro").innerHTML = "{{ page.someContent }}";
|
||||
}
|
||||
</script>{% endraw %}
|
||||
</script>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
When Jekyll builds the site, this `someContent` property populates the script's values, converting `{% raw %}{{ page.someContent }}{% endraw %}` to `"This is some content"`.
|
||||
|
||||
|
|
@ -127,17 +139,21 @@ There's one more detail to remember: Liquid does not render when embedded in YAM
|
|||
|
||||
For example, suppose you have a `highlight` tag in your `_data/mydata.yml` file:
|
||||
|
||||
```
|
||||
{% raw %}myvalue: >
|
||||
{% raw %}
|
||||
```liquid
|
||||
myvalue: >
|
||||
{% highlight javascript %}
|
||||
console.log('alert');
|
||||
{% endhighlight %}{% endraw %}
|
||||
{% endhighlight %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
On a page, you try to insert the value:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ site.data.mydata.myvalue }}
|
||||
```
|
||||
{% raw %}{{ site.data.mydata.myvalue }}{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This would render only as a string rather than a code sample with syntax highlighting. To make the code render, consider using an include instead.
|
||||
|
|
|
|||
|
|
@ -4,9 +4,11 @@ title: Community
|
|||
permalink: /community/
|
||||
---
|
||||
|
||||
## Jekyllconf
|
||||
|
||||
[JekyllConf](http://jekyllconf.com) is a free, online conference for all things Jekyll hosted by [CloudCannon](http://cloudcannon.com). Each year members of the Jekyll community speak about interesting use cases, tricks they've learned, or meta Jekyll topics.
|
||||
|
||||
## Featured
|
||||
### Featured
|
||||
{% assign random = site.time | date: "%s%N" | modulo: site.data.jekyllconf-talks.size %}
|
||||
{% assign featured = site.data.jekyllconf-talks[random] %}
|
||||
|
||||
|
|
@ -17,7 +19,7 @@ permalink: /community/
|
|||
|
||||
{% assign talks = site.data.jekyllconf-talks | group_by: 'year' %}
|
||||
{% for year in talks reversed %}
|
||||
## {{ year.name }}
|
||||
### {{ year.name }}
|
||||
{% for talk in year.items %}
|
||||
* [{{ talk.topic }}](https://youtu.be/{{ talk.youtube_id }}) - [{{ talk.speaker }}](https://twitter.com/{{ talk.twitter_handle }})
|
||||
{% endfor %}
|
||||
|
|
|
|||
Loading…
Reference in New Issue