docs: improve highlighting of code blocks (#8017)
Merge pull request 8017
This commit is contained in:
Eric Knibbe
GitHub
parent
1a0a4b709a
commit
8c3276133d
|
|
@ -46,6 +46,9 @@ plugins:
|
|||
feed:
|
||||
categories:
|
||||
- release
|
||||
kramdown:
|
||||
syntax_highlighter_opts:
|
||||
default_lang: plaintext
|
||||
sass:
|
||||
style: compressed
|
||||
strict_front_matter: true
|
||||
|
|
|
|||
|
|
@ -79,7 +79,6 @@ sass:
|
|||
These are passed to Sass, so any output style options Sass supports are valid
|
||||
here, too.
|
||||
|
||||
|
||||
## Coffeescript
|
||||
|
||||
To enable Coffeescript in Jekyll 3.0 and up you must
|
||||
|
|
|
|||
|
|
@ -15,6 +15,7 @@ example here's a collection of staff members:
|
|||
collections:
|
||||
- staff_members
|
||||
```
|
||||
|
||||
In this case `collections` is defined as a sequence (i.e array) with no additional metadata defined for each collection.
|
||||
You can optionally specify metadata for your collection by defining `collections` as a mapping (i.e hashmap) instead of sequence, and then defining additional fields in it:
|
||||
|
||||
|
|
@ -96,7 +97,6 @@ using the `content` variable:
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
If you'd like Jekyll to create a rendered page for each document in your
|
||||
collection, you can set the `output` key to `true` in your collection
|
||||
metadata in `_config.yml`:
|
||||
|
|
@ -285,7 +285,6 @@ you specified in your `_config.yml` (if present) and the following information:
|
|||
</p>
|
||||
</div>
|
||||
|
||||
|
||||
### Documents
|
||||
|
||||
In addition to any front matter provided in the document's corresponding
|
||||
|
|
|
|||
|
|
@ -28,7 +28,6 @@ There are a bunch of helpful community members on these services that should be
|
|||
* [How to file a bug](/docs/community/bug/)
|
||||
* [Guide for maintaining Jekyll](/docs/maintaining/)
|
||||
|
||||
|
||||
## Jekyllconf
|
||||
|
||||
[Watch videos](/jekyllconf/) from members of the Jekyll community speak about interesting use cases, tricks they’ve learned or meta Jekyll topics.
|
||||
|
|
|
|||
|
|
@ -114,7 +114,6 @@ defaults:
|
|||
</p>
|
||||
</div>
|
||||
|
||||
|
||||
### Precedence
|
||||
|
||||
Jekyll will apply all of the configuration settings you specify in the `defaults` section of your `_config.yml` file. You can choose to override settings from other scope/values pair by specifying a more specific path for the scope.
|
||||
|
|
|
|||
|
|
@ -346,7 +346,6 @@ class="flag">flags</code> (specified on the command-line) that control them.
|
|||
</table>
|
||||
</div>
|
||||
|
||||
|
||||
### Serve Command Options
|
||||
|
||||
In addition to the options below, the `serve` sub-command can accept any of the options
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ Save the commands you want to run and succeed in a file: `./script/cibuild`
|
|||
|
||||
### The HTML Proofer Executable
|
||||
|
||||
```sh
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -e # halt script on error
|
||||
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ In `_data/members.yml`:
|
|||
|
||||
Or `_data/members.csv`:
|
||||
|
||||
```text
|
||||
```
|
||||
name,github
|
||||
Eric Mill,konklone
|
||||
Parker Moore,parkr
|
||||
|
|
|
|||
|
|
@ -31,7 +31,6 @@ Most traditional web hosting provider let you upload files to their servers over
|
|||
|
||||
If you have direct access to the deployment web server, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server.
|
||||
|
||||
|
||||
## Rack-Jekyll
|
||||
|
||||
[Rack-Jekyll](https://github.com/adaoraul/rack-jekyll/) allows you to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](https://github.com/rtomayko/shotgun/), [rackup](https://github.com/rack/rack), [mongrel](https://github.com/mongrel/mongrel), [unicorn](https://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
|
||||
|
|
|
|||
|
|
@ -33,7 +33,6 @@ Kickster provides a basic Jekyll project setup packed with web best practises an
|
|||
|
||||
Install the Kickster gem and you are good to go. More documentation can here found [here](https://github.com/nielsenramon/kickster#kickster). If you do not want to use the gem or start a new project you can just copy paste the deployment scripts for [Travis CI](https://github.com/nielsenramon/kickster/tree/master/snippets/travis) or [Circle CI](https://github.com/nielsenramon/kickster#automated-deployment-with-circle-ci).
|
||||
|
||||
|
||||
## Netlify
|
||||
|
||||
Netlify provides Global CDN, Continuous Deployment, one click HTTPS and [much more](https://www.netlify.com/features/), providing developers the most robust toolset available for modern web projects, without added complexity. Netlify supports custom plugins for Jekyll and has a free plan for open source projects.
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ You can also pass parameters to an include. For example, suppose you have a file
|
|||
```
|
||||
{% 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:
|
||||
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
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ brew install ruby
|
|||
|
||||
Add the brew ruby path to your shell config:
|
||||
|
||||
```
|
||||
```bash
|
||||
export PATH=/usr/local/opt/ruby/bin:$PATH
|
||||
```
|
||||
|
||||
|
|
@ -56,10 +56,10 @@ Ruby versions. This is very useful when you need to be able to run a given Ruby
|
|||
# Install rbenv and ruby-build
|
||||
brew install rbenv
|
||||
|
||||
# Setup rbenv integration to your shell
|
||||
# Set up rbenv integration with your shell
|
||||
rbenv init
|
||||
|
||||
# Check your install
|
||||
# Check your installation
|
||||
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
|
||||
```
|
||||
|
||||
|
|
@ -94,7 +94,7 @@ ruby -v
|
|||
|
||||
Then append your path file with the following, replacing the `X.X` with the first two digits of your Ruby version.
|
||||
|
||||
```
|
||||
```bash
|
||||
export PATH=$HOME/.gem/ruby/X.X.0/bin:$PATH
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,6 @@ redirect_from:
|
|||
While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks. This page aims to
|
||||
collect some of the general knowledge and lessons that have been unearthed by Windows users.
|
||||
|
||||
|
||||
## Installing Jekyll
|
||||
|
||||
### Installation via RubyInstaller
|
||||
|
|
@ -43,11 +42,13 @@ First let's make sure all our packages / repositories are up to date. Open a new
|
|||
```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.
|
||||
|
||||
|
|
@ -90,7 +91,6 @@ with the current date in the filename.
|
|||
|
||||
**Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues.
|
||||
|
||||
|
||||
## Encoding
|
||||
|
||||
If you use UTF-8 encoding, make sure that no `BOM` header characters exist in your files or very, very bad things will happen to
|
||||
|
|
|
|||
|
|
@ -24,17 +24,14 @@ from this as needed.
|
|||
</p>
|
||||
</div>
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
The first step is to put the template source code in `default.html`. `content`
|
||||
is a special variable, the value is the rendered content of the post or page
|
||||
being wrapped.
|
||||
|
||||
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
```liquid
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
|
|
@ -67,7 +64,7 @@ You can also use
|
|||
[front matter defaults](/docs/configuration/front-matter-defaults/) to save you
|
||||
from having to set this on every page.
|
||||
|
||||
```
|
||||
```markdown
|
||||
---
|
||||
title: My First Page
|
||||
layout: default
|
||||
|
|
@ -78,7 +75,7 @@ This is the content of my page
|
|||
|
||||
The rendered output of this page is:
|
||||
|
||||
```
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
|
|
@ -102,7 +99,6 @@ The rendered output of this page is:
|
|||
</html>
|
||||
```
|
||||
|
||||
|
||||
## Inheritance
|
||||
|
||||
Layout inheritance is useful when you want to add something to an existing
|
||||
|
|
@ -115,7 +111,7 @@ layout in front matter. For example this layout will live at
|
|||
`_layouts/post.html`:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
|
@ -134,7 +130,7 @@ using in Liquid, you need to use the `layout` variable instead of `page`. For
|
|||
example:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
```liquid
|
||||
---
|
||||
city: San Francisco
|
||||
---
|
||||
|
|
|
|||
|
|
@ -108,15 +108,21 @@ The default is `default`. They are as follows (with what they filter):
|
|||
|
||||
You can use the `where` filter to detect documents and pages with properties that are `nil` or `""`. For example,
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
// Using `nil` to select posts that either do not have `my_prop` defined or `my_prop` has been set to `nil` explicitly.
|
||||
{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', nil %}{% endraw %}
|
||||
// Using `nil` to select posts that either do not have `my_prop`
|
||||
// defined or `my_prop` has been set to `nil` explicitly.
|
||||
{% assign filtered_posts = site.posts | where: 'my_prop', nil %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
// Using Liquid's special literal `empty` or `blank` to select posts that have `my_prop` set to an empty value.
|
||||
{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', empty %}{% endraw %}
|
||||
// Using Liquid's special literal `empty` or `blank` to select
|
||||
// posts that have `my_prop` set to an empty value.
|
||||
{% assign filtered_posts = site.posts | where: 'my_prop', empty %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Binary operators in `where_exp` filter {%- include docs_version_badge.html version="4.0" -%}
|
||||
|
||||
|
|
@ -125,15 +131,19 @@ conditionals in the operation.
|
|||
|
||||
For example, to get a list of documents on English horror flicks, one could use the following snippet:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}{% endraw %}
|
||||
{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Or to get a list of comic-book based movies, one may use the following:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}{% endraw %}
|
||||
{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Standard Liquid Filters
|
||||
|
||||
|
|
|
|||
|
|
@ -117,11 +117,11 @@ The path to the post, page, or collection is defined as the path relative to the
|
|||
|
||||
For example, suppose you're creating a link in `page_a.md` (stored in `pages/folder1/folder2`) to `page_b.md` (stored in `pages/folder1`). Your path in the link would not be `../page_b.html`. Instead, it would be `/pages/folder1/page_b.md`.
|
||||
|
||||
If you're unsure of the path, add `{% raw %}{{ page.path }}{% endraw %}` to the page and it will display the path.
|
||||
If you're unsure of the path, add {% raw %}`{{ page.path }}`{% endraw %} to the page and it will display the path.
|
||||
|
||||
One major benefit of using the `link` or `post_url` tag is link validation. If the link doesn't exist, Jekyll won't build your site. This is a good thing, as it will alert you to a broken link so you can fix it (rather than allowing you to build and deploy a site with broken links).
|
||||
|
||||
Note you cannot add filters to `link` tags. For example, you cannot append a string using Liquid filters, such as `{% raw %}{% link mypage.html | append: "#section1" %} {% endraw %}`. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques.
|
||||
Note you cannot add filters to `link` tags. For example, you cannot append a string using Liquid filters, such as {% raw %}`{% link mypage.html | append: "#section1" %}`{% endraw %}. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques.
|
||||
|
||||
### Linking to posts
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ We have [a helpful little bot](https://github.com/jekyllbot) which we use to mer
|
|||
|
||||
To merge a pull request, leave a comment thanking the contributor, then add the special merge request:
|
||||
|
||||
```text
|
||||
```
|
||||
Thank you very much for your contribution. Folks like you make this project and community strong. :heart:
|
||||
|
||||
@jekyllbot: merge +dev
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ a `.md` extension which converts to HTML on build. For a site with
|
|||
a homepage, an about page, and a contact page, here’s what the root directory
|
||||
and associated URLs might look like:
|
||||
|
||||
```sh
|
||||
```
|
||||
.
|
||||
|-- about.md # => http://example.com/about.html
|
||||
|-- index.html # => http://example.com/
|
||||
|
|
@ -22,7 +22,7 @@ and associated URLs might look like:
|
|||
|
||||
If you have a lot of pages, you can organize them into subfolders. The same subfolders that are used to group your pages in your project's source will then exist in the `_site` folder when your site builds. However, when a page has a *different* permalink set in the front matter, the subfolder at `_site` changes accordingly.
|
||||
|
||||
```sh
|
||||
```
|
||||
.
|
||||
|-- about.md # => http://example.com/about.html
|
||||
|-- documentation # folder containing pages
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ For example, you might have a page on your site located at
|
|||
`/my_pages/about-me.html` and you want the output url to be `/about/`. In
|
||||
front matter of the page you would set:
|
||||
|
||||
```
|
||||
```yaml
|
||||
---
|
||||
permalink: /about/
|
||||
---
|
||||
|
|
@ -46,7 +46,6 @@ For example, a permalink style of
|
|||
|
||||
Here's the full list of placeholders available:
|
||||
|
||||
|
||||
<div class="mobile-side-scroller">
|
||||
<table>
|
||||
<thead>
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ In the example above, we can place the following tag anywhere in one of our
|
|||
pages:
|
||||
|
||||
{% raw %}
|
||||
```ruby
|
||||
```liquid
|
||||
<p>{% render_time page rendered at: %}</p>
|
||||
```
|
||||
{% endraw %}
|
||||
|
|
|
|||
|
|
@ -58,8 +58,6 @@ I hope you like it!
|
|||
</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<div class="note info">
|
||||
<h5>Be aware of character sets</h5>
|
||||
<p>
|
||||
|
|
@ -102,7 +100,7 @@ Creating an index of posts on another page should be easy thanks to
|
|||
simple example of how to create a list of links to your blog posts:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
<ul>
|
||||
{% for post in site.posts %}
|
||||
<li>
|
||||
|
|
@ -166,7 +164,7 @@ post. By default this is the first paragraph of content in the post, however it
|
|||
can be customized by setting a `excerpt_separator` variable in front matter or
|
||||
`_config.yml`.
|
||||
|
||||
```yaml
|
||||
```markdown
|
||||
---
|
||||
excerpt_separator: <!--more-->
|
||||
---
|
||||
|
|
@ -199,9 +197,11 @@ Drafts are posts without a date in the filename. They're posts you're still
|
|||
working on and don't want to publish yet. To get up and running with drafts,
|
||||
create a `_drafts` folder in your site's root and create your first draft:
|
||||
|
||||
```text
|
||||
|-- _drafts/
|
||||
| |-- a-draft-post.md
|
||||
```
|
||||
.
|
||||
├── _drafts
|
||||
| └── a-draft-post.md
|
||||
...
|
||||
```
|
||||
|
||||
To preview your site with drafts, run `jekyll serve` or `jekyll build`
|
||||
|
|
|
|||
|
|
@ -18,7 +18,6 @@ A gem is code you can include in Ruby projects. It allows you to package up func
|
|||
[jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) and
|
||||
[jekyll-archives](https://github.com/jekyll/jekyll-archives).
|
||||
|
||||
|
||||
## Gemfile
|
||||
|
||||
A `Gemfile` is a list of gems required for your site. For a simple Jekyll site it might look something like this:
|
||||
|
|
|
|||
|
|
@ -18,19 +18,19 @@ instructions for your operating system.
|
|||
With Ruby setup you can install Jekyll by running the following in your
|
||||
terminal:
|
||||
|
||||
```
|
||||
```sh
|
||||
gem install jekyll bundler
|
||||
```
|
||||
|
||||
To create a new `Gemfile` to list your project's dependencies run:
|
||||
|
||||
```
|
||||
```sh
|
||||
bundle init
|
||||
```
|
||||
|
||||
Now edit the `Gemfile` and add jekyll as a dependency:
|
||||
|
||||
```
|
||||
```ruby
|
||||
gem "jekyll"
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,6 @@ Liquid is where Jekyll starts to get more interesting. Liquid is a templating
|
|||
language which has three main parts: [objects](#objects), [tags](#tags) and
|
||||
[filters](#filters).
|
||||
|
||||
|
||||
## Objects
|
||||
|
||||
Objects tell Liquid where to output content. They're denoted by double curly
|
||||
|
|
@ -68,7 +67,7 @@ Now it's your turn, change the Hello World! on your page to output as lowercase:
|
|||
|
||||
To get our changes processed by Jekyll we need to add [front matter](../03-front-matter/) to the top of the page:
|
||||
|
||||
```markdown
|
||||
```yaml
|
||||
---
|
||||
# front matter tells Jekyll to process Liquid
|
||||
---
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Front matter is a snippet of [YAML](http://yaml.org/) which sits between two
|
|||
triple-dashed lines at the top of a file. Front matter is used to set variables
|
||||
for the page, for example:
|
||||
|
||||
```liquid
|
||||
```yaml
|
||||
---
|
||||
my_number: 5
|
||||
---
|
||||
|
|
@ -27,7 +27,7 @@ example to output the variable above you would use:
|
|||
Let's change the `<title>` on your site to populate using front matter:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
title: Home
|
||||
---
|
||||
|
|
@ -44,12 +44,11 @@ title: Home
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
Note that in order for Jekyll to process any liquid tags on your page,
|
||||
you _must_ include front matter on it. The most minimal snippet of front matter
|
||||
you can include is:
|
||||
|
||||
```liquid
|
||||
```yaml
|
||||
---
|
||||
---
|
||||
```
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ matter. The layout wraps around the content of the page so all you need in
|
|||
`index.html` is:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
title: Home
|
||||
|
|
@ -70,8 +70,7 @@ layout.
|
|||
|
||||
Add the following to `about.md`:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```markdown
|
||||
---
|
||||
layout: default
|
||||
title: About
|
||||
|
|
@ -80,7 +79,6 @@ title: About
|
|||
|
||||
This page tells you a little bit about me.
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Open <a href="http://localhost:4000/about.html" target="_blank" data-proofer-ignore>http://localhost:4000/about.html</a>
|
||||
in your browser and view your new page.
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ include.
|
|||
Create a file for the navigation at `_includes/navigation.html` with the
|
||||
following content:
|
||||
|
||||
```liquid
|
||||
```
|
||||
<nav>
|
||||
<a href="/">Home</a>
|
||||
<a href="/about.html">About</a>
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ them in your site folder and they’ll copy across to the built site.
|
|||
|
||||
Jekyll sites often use this structure to keep assets organized:
|
||||
|
||||
```sh
|
||||
```
|
||||
.
|
||||
├── assets
|
||||
| ├── css
|
||||
|
|
@ -38,13 +38,11 @@ to CSS baked right into Jekyll.
|
|||
|
||||
First create a Sass file at `/assets/css/styles.scss` with the following content:
|
||||
|
||||
{% raw %}
|
||||
```css
|
||||
```sass
|
||||
---
|
||||
---
|
||||
@import "main";
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The empty front matter at the top tells Jekyll it needs to process the file. The
|
||||
`@import "main"` tells Sass to look for a file called `main.scss` in the sass
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ The `post` layout doesn't exist so you'll need to create it at
|
|||
`_layouts/post.html` with the following content:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
|
@ -65,7 +65,7 @@ Jekyll makes posts available at `site.posts`.
|
|||
Create `blog.html` in your root (`/blog.html`) with the following content:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
title: Blog
|
||||
|
|
@ -139,7 +139,7 @@ golden flesh with rows of tiny, black, edible seeds. The fruit has a soft
|
|||
texture, with a sweet and unique flavor.
|
||||
```
|
||||
|
||||
Open <a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a> and have
|
||||
a look through your blog posts.
|
||||
Open <a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a>
|
||||
and have a look through your blog posts.
|
||||
|
||||
Next we'll focus on creating a page for each post author.
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ collection available at `site.authors`.
|
|||
Create `staff.html` and iterate over `site.authors` to output all the staff:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
title: Staff
|
||||
|
|
@ -117,7 +117,7 @@ You can link to the output page using `author.url`.
|
|||
Add the link to the `staff.html` page:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
title: Staff
|
||||
|
|
@ -141,7 +141,7 @@ Just like posts you'll need to create a layout for authors.
|
|||
Create `_layouts/author.html` with the following content:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
|
@ -203,7 +203,7 @@ Iterate over this filtered list in `_layouts/author.html` to output the
|
|||
author's posts:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
|
@ -228,7 +228,7 @@ The posts have a reference to the author so let's link it to the author's page.
|
|||
You can do this using a similar filtering technique in `_layouts/post.html`:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ different environments.
|
|||
|
||||
Create `Gemfile` in the root with the following:
|
||||
|
||||
```
|
||||
```ruby
|
||||
source 'https://rubygems.org'
|
||||
|
||||
gem 'jekyll'
|
||||
|
|
@ -27,7 +27,7 @@ creates `Gemfile.lock` which locks the current gem versions for a future
|
|||
When using a `Gemfile`, you'll run commands like `jekyll serve` with
|
||||
`bundle exec` prefixed. So the full command is:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
bundle exec jekyll serve
|
||||
```
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ with SEO
|
|||
To use these first you need to add them to your `Gemfile`. If you put them
|
||||
in a `jekyll_plugins` group they'll automatically be required into Jekyll:
|
||||
|
||||
```
|
||||
```ruby
|
||||
source 'https://rubygems.org'
|
||||
|
||||
gem 'jekyll'
|
||||
|
|
@ -65,7 +65,7 @@ end
|
|||
|
||||
Then add these lines to your `_config.yml`:
|
||||
|
||||
```
|
||||
```yaml
|
||||
plugins:
|
||||
- jekyll-feed
|
||||
- jekyll-sitemap
|
||||
|
|
@ -109,7 +109,7 @@ To do this you can use [environments](/docs/configuration/environments/). You
|
|||
can set the environment by using the `JEKYLL_ENV` environment variable when
|
||||
running a command. For example:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
JEKYLL_ENV=production bundle exec jekyll build
|
||||
```
|
||||
|
||||
|
|
@ -130,7 +130,7 @@ on production you would do the following:
|
|||
The final step is to get the site onto a production server. The most basic way
|
||||
to do this is to run a production build:
|
||||
|
||||
```bash
|
||||
```sh
|
||||
JEKYLL_ENV=production bundle exec jekyll build
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ permalink: /docs/structure/
|
|||
---
|
||||
A basic Jekyll site usually looks something like this:
|
||||
|
||||
```sh
|
||||
```
|
||||
.
|
||||
├── _config.yml
|
||||
├── _data
|
||||
|
|
|
|||
|
|
@ -23,6 +23,7 @@ With gem-based themes, some of the site's directories (such as the `assets`, `_l
|
|||
In the case of Minima, you see only the following files in your Jekyll site directory:
|
||||
|
||||
```
|
||||
.
|
||||
├── Gemfile
|
||||
├── Gemfile.lock
|
||||
├── _config.yml
|
||||
|
|
@ -76,6 +77,7 @@ To locate a theme's files on your computer:
|
|||
A Finder or Explorer window opens showing the theme's files and directories. The Minima theme gem contains these files:
|
||||
|
||||
```
|
||||
.
|
||||
├── LICENSE.txt
|
||||
├── README.md
|
||||
├── _includes
|
||||
|
|
@ -129,7 +131,7 @@ To do this, copy the files from the theme gem's directory into your Jekyll site
|
|||
|
||||
Then you must tell Jekyll about the plugins that were referenced by the theme. You can find these plugins in the theme's gemspec file as runtime dependencies. If you were converting the Minima theme, for example, you might see:
|
||||
|
||||
```
|
||||
```ruby
|
||||
spec.add_runtime_dependency "jekyll-feed", "~> 0.12"
|
||||
spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.6"
|
||||
```
|
||||
|
|
@ -191,6 +193,7 @@ To install a gem-based theme:
|
|||
# This is an example, declare the theme gem you want to use here
|
||||
gem "jekyll-theme-minimal"
|
||||
```
|
||||
|
||||
Or if you've started with the `jekyll new` command, replace `gem "minima", "~> 2.0"` with the gem you want, e.g:
|
||||
|
||||
```diff
|
||||
|
|
@ -274,7 +277,7 @@ Your theme's stylesheets should be placed in your theme's `_sass` folder, again,
|
|||
|
||||
```
|
||||
_sass
|
||||
├── jekyll-theme-awesome.scss
|
||||
└── jekyll-theme-awesome.scss
|
||||
```
|
||||
|
||||
Your theme's styles can be included in the user's stylesheet using the `@import` directive.
|
||||
|
|
|
|||
|
|
@ -111,7 +111,7 @@ possible to run Jekyll as a non-superuser and without having to install
|
|||
gems to system-wide locations by adding the following lines to the end
|
||||
of your `.bashrc` file:
|
||||
|
||||
```
|
||||
```bash
|
||||
# Ruby exports
|
||||
|
||||
export GEM_HOME=$HOME/gems
|
||||
|
|
@ -252,7 +252,7 @@ specified elsewhere.
|
|||
|
||||
**Note: From v3.3.0 onward, Jekyll does not process `node_modules` and certain subdirectories within `vendor`, by default. But, by having an `exclude:` array defined explicitly in the config file overrides this default setting, which results in some users to encounter an error in building the site, with the following error message:**
|
||||
|
||||
```sh
|
||||
```
|
||||
ERROR: YOUR SITE COULD NOT BE BUILT:
|
||||
------------------------------------
|
||||
Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>':
|
||||
|
|
@ -262,7 +262,6 @@ specified elsewhere.
|
|||
|
||||
Adding `vendor/bundle` to the `exclude:` list will solve this problem but will lead to having other sub-directories under `/vendor/` (and also `/node_modules/`, if present) be processed to the destination folder `_site`.
|
||||
|
||||
|
||||
The proper solution is to incorporate the default setting for `exclude:` rather than override it completely:
|
||||
|
||||
For versions up to `v3.4.3`, the `exclude:` setting must look like following:
|
||||
|
|
@ -281,7 +280,6 @@ exclude:
|
|||
|
||||
From `v3.5` onward, `Gemfile` and `Gemfile.lock` are also excluded by default. So, in most cases there is no need to define another `exclude:` array in the config file. So an existing definition can either be modified as above, or removed completely, or commented out to enable easy edits in future.
|
||||
|
||||
|
||||
## Markup Problems
|
||||
|
||||
The various markup engines that Jekyll uses may have some issues. This
|
||||
|
|
@ -293,7 +291,7 @@ problems.
|
|||
Liquid version 2.0 seems to break the use of `{{ "{{" }}` in templates.
|
||||
Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the following error:
|
||||
|
||||
```sh
|
||||
```
|
||||
'{{ "{{" }}' was not properly terminated with regexp: /\}\}/ (Liquid::SyntaxError)
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -120,13 +120,12 @@ such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes
|
|||
that easier with the new `--baseurl` flag. To take advantage of this
|
||||
feature, first add the production `baseurl` to your site's `_config.yml`
|
||||
file. Then, throughout the site, prefix relative URLs
|
||||
with `{% raw %}{{ site.baseurl }}{% endraw %}`.
|
||||
with {% raw %}`{{ site.baseurl }}`{% endraw %}.
|
||||
When you're ready to preview your site locally, pass along the `--baseurl`
|
||||
flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll
|
||||
will swap in whatever you've passed along, ensuring all your links work as
|
||||
you'd expect in both environments.
|
||||
|
||||
|
||||
<div class="note warning">
|
||||
<h5 markdown="1">All page and post URLs contain leading slashes</h5>
|
||||
<p markdown="1">If you use the method described above, please remember
|
||||
|
|
|
|||
|
|
@ -36,11 +36,11 @@ When iterating over `site.collections`, ensure the above conversions are made.
|
|||
|
||||
For `site.collections.myCollection` in Jekyll 2, you now do:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% assign myCollection = site.collections | where: "label", "myCollection" | first %}
|
||||
{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This is a bit cumbersome at first, but is easier than a big `for` loop.
|
||||
|
||||
|
|
@ -83,7 +83,7 @@ Introducing: `layout`. In Jekyll 2 and below, any metadata in the layout was mer
|
|||
the `page` variable in Liquid. This caused a lot of confusion in the way the data was
|
||||
merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible via `layout`
|
||||
in Liquid. For example, if your layout has `class: my-layout` in its front matter,
|
||||
then the layout can access that via `{% raw %}{{ layout.class }}{% endraw %}`.
|
||||
then the layout can access that via {% raw %}`{{ layout.class }}`{% endraw %}.
|
||||
|
||||
### Syntax highlighter changed
|
||||
|
||||
|
|
@ -101,7 +101,7 @@ In Jekyll 3 and above, relative permalinks have been deprecated. If you
|
|||
created your site using Jekyll 2 and below, you may receive the following
|
||||
error when trying to **serve** or **build**:
|
||||
|
||||
```text
|
||||
```
|
||||
Since v3.0, permalinks for pages in subfolders must be relative to the site
|
||||
source directory, not the parent directory. Check
|
||||
https://jekyllrb.com/docs/upgrading/ for more info.
|
||||
|
|
|
|||
|
|
@ -42,7 +42,6 @@ gem update jekyll
|
|||
{% endhighlight %}
|
||||
</div>
|
||||
|
||||
|
||||
## Template rendering
|
||||
|
||||
We've slightly altered the way Jekyll parses and renders your various templates
|
||||
|
|
@ -161,6 +160,7 @@ Notes:
|
|||
end
|
||||
end
|
||||
```
|
||||
|
||||
* Vendors that provide a versioned Jekyll Environment Image (e.g. Docker Image, GitHub Pages, etc)
|
||||
will have to manually whitelist kramdown's extension gems in their distributions for Jekyll 4.0.
|
||||
|
||||
|
|
|
|||
|
|
@ -38,31 +38,31 @@ new filters have you covered. When working locally, if you set your
|
|||
then `relative_url` will ensure that this baseurl is prepended to anything
|
||||
you pass it:
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ "/docs/assets/" | relative_url }} => /myproject/docs/assets
|
||||
```
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
By default, `baseurl` is set to `""` and therefore yields (never set to
|
||||
`"/"`):
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ "/docs/assets/" | relative_url }} => /docs/assets
|
||||
```
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
A result of `relative_url` will safely always produce a URL which is
|
||||
relative to the domain root. A similar principle applies to `absolute_url`.
|
||||
It prepends your `baseurl` and `url` values, making absolute URLs all the
|
||||
easier to make:
|
||||
|
||||
{% highlight liquid %}
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ "/docs/assets/" | absolute_url }} => https://jekyllrb.com/myproject/docs/assets
|
||||
```
|
||||
{% endraw %}
|
||||
{% endhighlight %}
|
||||
|
||||
### 3. `site.url` is set by the development server
|
||||
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ The highlights being:
|
|||
Ergo, if you set a custom location for your collections, please ensure you
|
||||
move all of your collections into that directory. **This includes posts and
|
||||
drafts as well**. Your links generated by
|
||||
`{% raw %}{% post_url %}{% endraw %}` or `{% raw %}{% link %}{% endraw %}`
|
||||
{% raw %}`{% post_url %}`{% endraw %} or {% raw %}`{% link %}`{% endraw %}
|
||||
will adapt automatically.
|
||||
|
||||
* We also found out that `gem "wdm"` boosts performance while directories are
|
||||
|
|
|
|||
|
|
@ -64,7 +64,6 @@ is built.
|
|||
This will clear all cached objects from a particular Cache. The Cache will be
|
||||
empty, both in memory and on disk.
|
||||
|
||||
|
||||
### The following methods will probably only be used in special circumstances
|
||||
|
||||
## cache[key] → value
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ First, let's start with a grounding in the basics. Stripping a Jekyll site down
|
|||
We'll start with a *basic Jekyll site* consisting of three files:
|
||||
|
||||
```
|
||||
.
|
||||
├── _config.yml
|
||||
├── _layouts
|
||||
│ └── default.html
|
||||
|
|
@ -28,8 +29,8 @@ We'll start with a *basic Jekyll site* consisting of three files:
|
|||
Manually create these three files in a folder called `my_jekyll_site` or whatever suits you the most, and place `default.html` inside a folder named `_layouts`.
|
||||
|
||||
```sh
|
||||
$ touch _config.yml index.md default.html
|
||||
$ mkdir _layouts && mv default.html _layouts
|
||||
touch _config.yml index.md default.html
|
||||
mkdir _layouts && mv default.html _layouts
|
||||
```
|
||||
|
||||
Fire up your favorite editor, and populate the contents of the `default.html` and `index.md` files as follows:
|
||||
|
|
@ -42,35 +43,42 @@ name: My Jekyll Website
|
|||
|
||||
**_layouts/default.html**
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<body>
|
||||
{% raw %}{{ content }}{% endraw %}
|
||||
{{ content }}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**index.md**
|
||||
|
||||
```yaml
|
||||
{% raw %}
|
||||
```markdown
|
||||
---
|
||||
title: My page
|
||||
layout: default
|
||||
---
|
||||
|
||||
# {% raw %}{{ page.title }}{% endraw %}
|
||||
# {{ page.title }}
|
||||
|
||||
Content is written in [Markdown](https://learnxinyminutes.com/docs/markdown/). Plain text format allows you to focus on your **content**.
|
||||
Content is written in [Markdown](https://learnxinyminutes.com/docs/markdown/).
|
||||
Plain text format allows you to focus on your **content**.
|
||||
|
||||
<!--
|
||||
You can use HTML elements in Markdown, such as the comment element, and they won't be affected by a markdown parser. However, if you create an HTML element in your markdown file, you cannot use markdown syntax within that element's contents.
|
||||
You can use HTML elements in Markdown, such as the comment element, and they won't
|
||||
be affected by a markdown parser. However, if you create an HTML element in your
|
||||
markdown file, you cannot use markdown syntax within that element's contents.
|
||||
-->
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Now `cd` to `my_jekyll_site` and serve the site with the built-in server:
|
||||
|
||||
```
|
||||
```sh
|
||||
cd my_jekyll_site
|
||||
jekyll serve
|
||||
```
|
||||
|
|
@ -84,7 +92,7 @@ This is a Jekyll site at the most basic functional level. Here's what is happeni
|
|||
|
||||
* The `_config.yml` file contains settings that Jekyll uses as it processes your site. An empty config file will use default values for building a Jekyll site. For example, to convert [Markdown](https://learnxinyminutes.com/docs/markdown/) to HTML, Jekyll will automatically use the [kramdown Markdown filter](https://rubygems.org/gems/kramdown/), without any need to specify it.
|
||||
* Jekyll looks for files with [front matter tags]({% link _docs/front-matter.md %}) (the two sets of dashed lines `---` like those in `index.md`) and processes the files (populating site variables, rendering any [Liquid](https://shopify.github.io/liquid/), and converting Markdown to HTML).
|
||||
* Jekyll pushes the content from all pages and posts into the `{% raw %}{{ content }}{% endraw %}` variable in the layout specified (`default`) in the front matter tags.
|
||||
* Jekyll pushes the content from all pages and posts into the {% raw %}`{{ content }}`{% endraw %} variable in the layout specified (`default`) in the front matter tags.
|
||||
* The processed files get written as `.html` files in the `_site` directory.
|
||||
|
||||
You can read more about how Jekyll processes the files in [order of Interpretation]({% link _tutorials/orderofinterpretation.md %}).
|
||||
|
|
@ -110,21 +118,25 @@ For example, if the paths were relative on the site you copied, you'll need to e
|
|||
|
||||
Jekyll provides some [filters](/docs/liquid/filters) to prepend a site URL before path. For example, you could preface your stylesheet like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{{ "/assets/style.css" | relative_url }}{% endraw %}
|
||||
{{ "/assets/style.css" | relative_url }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The `relative_url` filter will prepend the [`baseurl`](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/) value from your config file (as `blog` for instance) to the input. This is useful if your site is hosted at a subpath rather than at the root of the domain (for example, `http://mysite.com/blog/`).
|
||||
|
||||
You can also use an `absolute_url` filter. This filter will prepend the `url` *and* `baseurl` value to the input:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{{ "/assets/style.css" | absolute_url }}{% endraw %}
|
||||
{{ "/assets/style.css" | absolute_url }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Again, both `url` and `baseurl` can be defined in your site's config file, like this:
|
||||
|
||||
```
|
||||
```yaml
|
||||
url: http://mysite.com
|
||||
baseurl: /blog
|
||||
```
|
||||
|
|
@ -141,9 +153,9 @@ In the next section, you'll blank out the content of the layout and replace it w
|
|||
|
||||
## 2. Identify the content part of the layout
|
||||
|
||||
In `default.html`, find where the page content begins (usually at `h1` or `h2` tags). Replace the title that appears inside these tags with `{% raw %}{{ page.title }}{% endraw %}`.
|
||||
In `default.html`, find where the page content begins (usually at `h1` or `h2` tags). Replace the title that appears inside these tags with {% raw %}`{{ page.title }}`{% endraw %}.
|
||||
|
||||
Remove the content part (keep everything else: navigation menu, sidebar, footer, etc.) and replace it with `{% raw %}{{ content }}{% endraw %}`.
|
||||
Remove the content part (keep everything else: navigation menu, sidebar, footer, etc.) and replace it with {% raw %}`{{ content }}`{% endraw %}.
|
||||
|
||||
Check the layout again in your browser and make sure you didn't corrupt or alter it up by inadvertently removing a crucial `div` tag or other element. The only change should be to the title and page content, which are now blanked out or showing the placeholder tag.
|
||||
|
||||
|
|
@ -153,7 +165,7 @@ Create a couple of files (`index.md` and `about.md`) in your root directory.
|
|||
|
||||
In your `index.md` file, add some front matter tags containing a `title` and `layout` property, like this:
|
||||
|
||||
```yaml
|
||||
```markdown
|
||||
---
|
||||
title: Home
|
||||
layout: default
|
||||
|
|
@ -171,13 +183,13 @@ If you don't specify a layout in your pages, Jekyll will simply render that page
|
|||
|
||||
Add a `_config.yml` file in your root directory. In `_config.yml`, you can optionally specify the markdown filter you want. By default, [kramdown](https://kramdown.gettalong.org/) is used (without the need to specify it). If no other filter is specified, your config file will automatically apply the following as a default setting:
|
||||
|
||||
```
|
||||
```yaml
|
||||
markdown: kramdown
|
||||
```
|
||||
|
||||
You can also specify [some options](https://kramdown.gettalong.org/converter/html.html) for kramdown to make it behave more like [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/):
|
||||
|
||||
```
|
||||
```yaml
|
||||
kramdown:
|
||||
input: GFM
|
||||
auto_ids: true
|
||||
|
|
@ -193,7 +205,7 @@ You've now extracted your content out into separate files and defined a common l
|
|||
|
||||
You could define any number of layouts you want for pages. Then just identify the layout you want that particular page to use. For example:
|
||||
|
||||
```
|
||||
```yaml
|
||||
---
|
||||
title: Sample page
|
||||
layout: homepage
|
||||
|
|
@ -206,7 +218,7 @@ You can even set [default front matter tags](/docs/configuration/front-matter-de
|
|||
|
||||
## 6. Configure site variables
|
||||
|
||||
You already configured the page title using `{% raw %}{{ page.title }}{% endraw %}` tags. But there are more `title` tags to populate. Pages also have a [`title`](https://moz.com/learn/seo/title-tag) tag that appears in the browser tab or window. Typically you put the page title followed by the site title here.
|
||||
You already configured the page title using {% raw %}`{{ page.title }}`{% endraw %} tags. But there are more `title` tags to populate. Pages also have a [`title`](https://moz.com/learn/seo/title-tag) tag that appears in the browser tab or window. Typically you put the page title followed by the site title here.
|
||||
|
||||
In your `default.html` layout, look for the `title` tags below your `head` tags:
|
||||
|
||||
|
|
@ -216,13 +228,15 @@ In your `default.html` layout, look for the `title` tags below your `head` tags:
|
|||
|
||||
Insert the following site variables:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
<title>{{ page.title }} | {{ site.title }}</title>
|
||||
```
|
||||
{% raw %}<title>{{ page.title }} | {{ site.title }}</title>{% endraw %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Open `_config.yml` and add a `title` property for your site's name.
|
||||
|
||||
```
|
||||
```yaml
|
||||
title: ACME Website
|
||||
```
|
||||
|
||||
|
|
@ -247,7 +261,7 @@ Add some posts in a `_posts` folder following the standard `YYYY-MM-DD-title.md`
|
|||
|
||||
In each post, add some basic content:
|
||||
|
||||
```
|
||||
```markdown
|
||||
---
|
||||
title: My First Post
|
||||
layout: default
|
||||
|
|
@ -258,43 +272,44 @@ Some sample content...
|
|||
|
||||
Now let's create a layout that will display the posts. Create a new file in `_layouts` called `home.html` and add the following logic:
|
||||
|
||||
```
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
||||
{% raw %}{{ content }}
|
||||
{{ content }}
|
||||
<ul class="myposts">
|
||||
{% for post in site.posts %}
|
||||
<li><a href="{{ post.url }}">{{ post.title}}</a>
|
||||
<span class="postDate">{{ post.date | date: "%b %-d, %Y" }}</span>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>{% endraw %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Create a file called `blog.md` in your root directory and specify the `home` layout:
|
||||
|
||||
```
|
||||
```yaml
|
||||
---
|
||||
title: Blog
|
||||
layout: home
|
||||
---
|
||||
```
|
||||
|
||||
In this case, contents of `blog.md` will be pushed into the `{% raw %}{{ content }}{% endraw %}` tag in the `home` layout. Then the `home` layout will be pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the `default` layout.
|
||||
|
||||
In this case, contents of `blog.md` will be pushed into the {% raw %}`{{ content }}`{% endraw %} tag in the `home` layout. Then the `home` layout will be pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the `default` layout.
|
||||
|
||||
### How layouts work
|
||||
|
||||
When a layout specifies another layout, it means the content of the first layout will be stuffed into the `{% raw %}{{ content }}{% endraw %}` tag of the second layout. As an analogy, think of Russian dolls that fit into each other. Each layout fits into another layout that it specifies.
|
||||
When a layout specifies another layout, it means the content of the first layout will be stuffed into the {% raw %}`{{ content }}`{% endraw %} tag of the second layout. As an analogy, think of Russian dolls that fit into each other. Each layout fits into another layout that it specifies.
|
||||
|
||||
The following diagram shows how layouts work in Jekyll:
|
||||
|
||||
<img src="../../img/jekylllayoutconcept.png" alt="Concept of Jekyll layouts" />
|
||||
|
||||
{: .image-description}
|
||||
In this example, the content from a Markdown document `document.md` that specifies `layout: docs` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the layout file `docs.html`. Because the `docs` layout itself specifies `layout: page`, the content from `docs.html` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag in the layout file `page.html`. Finally because the `page` layout specifies `layout: default`, the content from `page.html` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the layout file `default.html`.
|
||||
In this example, the content from a Markdown document `document.md` that specifies `layout: docs` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the layout file `docs.html`. Because the `docs` layout itself specifies `layout: page`, the content from `docs.html` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag in the layout file `page.html`. Finally because the `page` layout specifies `layout: default`, the content from `page.html` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the layout file `default.html`.
|
||||
|
||||
You don't need multiple layouts. You could just use one: `default`. You have options for how you design your site. In general, it's common to define one layout for pages and another layout for posts, but for both of these layouts to inherit the `default` template (which usually defines the top and bottom parts of the site).
|
||||
|
||||
|
|
@ -302,7 +317,7 @@ In your browser, go to `blog.html` and see the list of posts.
|
|||
Note that you don't have to use the method described here. You could have simply added the `for` loop to any page, such as `index.md`, to display these posts. But given that you may have more complex logic for other features, it can be helpful to store your logic in templates separate from the page area where you frequently type your content.
|
||||
|
||||
{: .note .info}
|
||||
At minimum, a layout should contain `{% raw %}{{ content }}{% endraw %}`, which acts as a receiver for the *content* to be rendered.
|
||||
At minimum, a layout should contain {% raw %}`{{ content }}`{% endraw %}, which acts as a receiver for the *content* to be rendered.
|
||||
|
||||
### For loops
|
||||
|
||||
|
|
@ -310,15 +325,17 @@ By the way, let's pause here to look at the `for` loop logic a little more close
|
|||
|
||||
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:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}<ul class="myposts">
|
||||
<ul class="myposts">
|
||||
{% for post in site.categories.podcasts limit:3 %}
|
||||
<li><a href="{{ post.url }}">{{ post.title}}</a>
|
||||
<span class="postDate">{{ post.date | date: "%b %-d, %Y" }}</span>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>{% endraw %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This loop would get the latest three posts that have a category called `podcasts` in the front matter.
|
||||
|
||||
|
|
@ -330,18 +347,20 @@ In this tutorial, we'll assume you've got a simple list of pages you want to gen
|
|||
|
||||
Identify the part of your code where the list of pages appears. Usually this is a `<ul>` element with various child `<li>` elements. Replace the code with the following:
|
||||
|
||||
```html
|
||||
{% raw %}<ul>
|
||||
{% raw %}
|
||||
```liquid
|
||||
<ul>
|
||||
{% assign mypages = site.pages | sort: "order" %}
|
||||
{% for page in mypages %}
|
||||
<li><a href="{{ page.url | absolute_url }}">{{ page.title }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>{% endraw %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This example assumes each page would have front matter containing both a `title` and `order` property like this:
|
||||
|
||||
```
|
||||
```yaml
|
||||
---
|
||||
title: My page
|
||||
order: 2
|
||||
|
|
@ -372,13 +391,15 @@ You can store additional properties for each item in this data file as desired.
|
|||
|
||||
To print the list of pages from the data file, use code like this:
|
||||
|
||||
```html
|
||||
{% raw %}<ul>
|
||||
{% raw %}
|
||||
```liquid
|
||||
<ul>
|
||||
{% for link in site.data.navigation %}
|
||||
<li><a href="{{ link.url }}">{{ link.title }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>{% endraw %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
If you have more sophisticated requirements around navigation, such as when building a documentation site, see the [detailed tutorial on navigation](/tutorials/navigation/).
|
||||
|
||||
|
|
@ -392,9 +413,11 @@ Remove your sidebar code from your `default.html` layout and insert it into the
|
|||
|
||||
Where the sidebar code previously existed in `default.html`, pull in your "include" like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% raw %}{% include sidebar.html %}{% endraw %}
|
||||
{% include sidebar.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You can break up other elements of your theme like this, such as your header or footer. Then you can apply these common elements to other layout files. This way you won't have duplicate code.
|
||||
|
||||
|
|
@ -402,12 +425,13 @@ You can break up other elements of your theme like this, such as your header or
|
|||
|
||||
Your Jekyll site needs an RSS feed. Here's the [basic RSS feed syntax](http://www.w3schools.com/xml/xml_rss.asp). To create an RSS file in Jekyll, create a file called `feed.xml` in your root directory and add the following:
|
||||
|
||||
```xml
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
layout: null
|
||||
---
|
||||
|
||||
{% raw %}<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<rss version="2.0">
|
||||
|
||||
<channel>
|
||||
|
|
@ -431,8 +455,9 @@ layout: null
|
|||
</item>
|
||||
{% endfor %}
|
||||
</channel>
|
||||
</rss>{% endraw %}
|
||||
</rss>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Make sure your `_config.yml` file has properties for `title`, `url`, and `description`.
|
||||
|
||||
|
|
@ -440,9 +465,11 @@ This code uses a `for` loop to look through your last 20 posts. The content from
|
|||
|
||||
In your `default.html` layout, look for a reference to the RSS or Atom feed in your header, and replace it with a reference to the file you just created. For example:
|
||||
|
||||
```html
|
||||
<link rel="alternate" type="application/rss+xml" href="{% raw %}{{ site.url }}{% endraw %}/feed.xml" title="{% raw %}{{ site.title }}{% endraw %}">
|
||||
{% raw %}
|
||||
```liquid
|
||||
<link rel="alternate" type="application/rss+xml" href="{{ site.url }}/feed.xml" title="{{ site.title }}">
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You can also auto-generate your posts feed by adding a gem called [`jekyll-feed`](https://help.github.com/articles/atom-rss-feeds-for-github-pages/). This gem will also work on GitHub Pages.
|
||||
|
||||
|
|
@ -450,13 +477,14 @@ You can also auto-generate your posts feed by adding a gem called [`jekyll-feed`
|
|||
|
||||
Finally, add a [site map](https://www.sitemaps.org/protocol.html). Create a `sitemap.xml` file in your root directory and add this code:
|
||||
|
||||
```xml
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
layout: null
|
||||
search: exclude
|
||||
---
|
||||
|
||||
{% raw %}<?xml version="1.0" encoding="UTF-8"?>
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
|
||||
{% for page in site.pages %}
|
||||
|
|
@ -477,8 +505,9 @@ search: exclude
|
|||
</url>
|
||||
{% endfor %}
|
||||
|
||||
</urlset>{% endraw %}
|
||||
</urlset>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Again, we're using a `for` loop here to iterate through all posts and pages to add them to the sitemap.
|
||||
|
||||
|
|
@ -501,7 +530,7 @@ As you integrate code for these services, note that **if a page in your Jekyll s
|
|||
|
||||
If you do want Jekyll to process some page content (for example, to populate a variable that you define in your site's config file), just add front matter tags to the page. If you don't want any layout applied to the page, specify `layout: null` like this:
|
||||
|
||||
```
|
||||
```yaml
|
||||
---
|
||||
layout: null
|
||||
---
|
||||
|
|
|
|||
|
|
@ -6,7 +6,6 @@ title: Custom 404 Page
|
|||
|
||||
You can easily serve custom 404 error pages with Jekyll to replace the default **Error 404 -- File Not Found** page displayed when one tries to access a broken link on your site.
|
||||
|
||||
|
||||
## On GitHub Pages
|
||||
|
||||
Any `404.html` at the **root of your `_site` directory** will be served automatically by GitHub Pages and the local WEBrick development server.
|
||||
|
|
@ -48,7 +47,6 @@ 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).
|
||||
|
||||
|
||||
## Hosting on Nginx server
|
||||
|
||||
The procedure is just as simple as configuring Apache servers, but slightly different.
|
||||
|
|
@ -63,6 +61,7 @@ server {
|
|||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the `server` block already exists, only add the code inside the `server` block given above.
|
||||
The `location` directive prevents users from directly browsing the 404.html page.
|
||||
|
||||
|
|
|
|||
|
|
@ -31,5 +31,3 @@ We welcome your tutorial contributions. To add your tutorial:
|
|||
6. Follow the regular git workflow to submit the pull request.
|
||||
|
||||
When you submit your pull request, the Jekyll documentation team will review your contribution and either merge it or suggest edits.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -371,12 +371,14 @@ For more information, see [Expressions and Variables](https://github.com/Shopify
|
|||
In addition to inserting items from the YAML data file into your list, you also usually want to highlight the current link if the user is viewing that page. You do this by inserting an `active` class for items that match the current page URL.
|
||||
|
||||
**CSS**
|
||||
|
||||
```css
|
||||
.result li.active a {
|
||||
color: lightgray;
|
||||
cursor: default;
|
||||
}
|
||||
```
|
||||
|
||||
**Liquid**
|
||||
|
||||
{% raw %}
|
||||
|
|
@ -408,13 +410,14 @@ In addition to inserting items from the YAML data file into your list, you also
|
|||
|
||||
In this case, assume `Deployment` is the current page.
|
||||
|
||||
To make sure the `item.url` (stored in the YAML file) matches the `page.url`, it can be helpful to print the `{% raw %}{{ page.url }}{% endraw %}` to the page.
|
||||
To make sure the `item.url` (stored in the YAML file) matches the `page.url`, it can be helpful to print the {% raw %}`{{ page.url }}`{% endraw %} to the page.
|
||||
|
||||
## Scenario 7: Including items conditionally
|
||||
|
||||
You might want to include items conditionally in your list. For example, maybe you have multiple site outputs and only want to include the sidebar item for certain outputs. You can add properties in each list item and then use those properties to conditionally include the content.
|
||||
|
||||
**YAML**
|
||||
|
||||
```yaml
|
||||
docs2_list_title: ACME Documentation
|
||||
docs2:
|
||||
|
|
@ -588,7 +591,7 @@ Let's walk through the code. First, we assign a variable (`mydocs`) to the colle
|
|||
|
||||
The `group_by` filter groups the collection content by `category`. More specifically, the `group_by` filter converts `mydocs` into an array with `name`, `items`, and `size` properties, somewhat like this:
|
||||
|
||||
```yaml
|
||||
```json
|
||||
[
|
||||
{"name": "getting-started", "items": [Sample 1, Sample 2],"size": 2},
|
||||
{"name": "configuration", "items": [Topic 1, Topic 2], "size": 2},
|
||||
|
|
|
|||
|
|
@ -17,13 +17,13 @@ Jekyll converts your site in the following order:
|
|||
1. **Site variables**. Jekyll looks across your files and populates [site variables]({% link _docs/variables.md %}), such as `site`, `page`, `post`, and collection objects. (From these objects, Jekyll determines the values for permalinks, tags, categories, and other details.)
|
||||
|
||||
2. **Liquid**. Jekyll processes any [Liquid](https://github.com/Shopify/liquid) formatting in pages that contain [front matter]({% link _docs/front-matter.md %}). You can identify Liquid as follows:
|
||||
* **Liquid tags** start with `{% raw %}{%{% endraw %}` and end with a `{% raw %}%}{% endraw %}`. For example: `{% raw %}{% highlight %}{% endraw %}` or `{% raw %}{% seo %}{% endraw %}`. Tags can define blocks or be inline. Block-defining tags will also come with a corresponding end tag — for example, `{% raw %}{% endhighlight %}{% endraw %}`.
|
||||
* **Liquid variables** start and end with double curly braces. For example: `{% raw %}{{ site.myvariable }}{% endraw %}` or `{% raw %}{{ content }}{% endraw %}`.
|
||||
* **Liquid filters** start with a pipe character (`|`) and can only be used within **Liquid variables** after the variable string. For example: the `relative_url` filter in `{% raw %}{{ "css/main.css" | relative_url }}{% endraw %}`.
|
||||
* **Liquid tags** start with {% raw %}`{%`{% endraw %} and end with a {% raw %}`%}`{% endraw %}. For example: {% raw %}`{% highlight %}`{% endraw %} or {% raw %}`{% seo %}`{% endraw %}. Tags can define blocks or be inline. Block-defining tags will also come with a corresponding end tag — for example, {% raw %}`{% endhighlight %}`{% endraw %}.
|
||||
* **Liquid variables** start and end with double curly braces. For example: {% raw %}`{{ site.myvariable }}`{% endraw %} or {% raw %}`{{ content }}`{% endraw %}.
|
||||
* **Liquid filters** start with a pipe character (`|`) and can only be used within **Liquid variables** after the variable string. For example: the `relative_url` filter in {% raw %}`{{ "css/main.css" | relative_url }}`{% endraw %}.
|
||||
|
||||
3. **Markdown**. Jekyll converts Markdown to HTML using the Markdown filter specified in your config file. Files must have a Markdown file extension and front matter in order for Jekyll to convert them.
|
||||
|
||||
4. **Layout**. Jekyll pushes content into the layouts specified by the page's front matter (or as specified in the config file). The content from each page gets pushed into the `{% raw %}{{ content }}{% endraw %}` tags within the layouts.
|
||||
4. **Layout**. Jekyll pushes content into the layouts specified by the page's front matter (or as specified in the config file). The content from each page gets pushed into the {% raw %}`{{ content }}`{% endraw %} tags within the layouts.
|
||||
|
||||
5. **Files**. Jekyll writes the generated content into files in the [directory structure]({% link _docs/structure.md %}) in `_site`. Pages, posts, and collections get structured based on their [permalink]({% link _docs/permalinks.md %}) setting. Directories that begin with `_` (such as `_includes` and `_data`) are usually hidden in the output.
|
||||
|
||||
|
|
@ -115,7 +115,7 @@ This won't work because the `assign` tag is only available during the Liquid ren
|
|||
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
|
||||
```javascript
|
||||
<button onclick="someFunction()">Click me</button>
|
||||
|
||||
<p id="intro"></p>
|
||||
|
|
@ -129,7 +129,7 @@ function someFunction() {
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
When Jekyll builds the site, this `someContent` property populates the script's values, converting `{% raw %}{{ page.someContent }}{% endraw %}` to `"This is some content"`.
|
||||
When Jekyll builds the site, this `someContent` property populates the script's values, converting {% raw %}`{{ page.someContent }}`{% endraw %} to `"This is some content"`.
|
||||
|
||||
The key to remember is that Liquid renders when Jekyll builds your site. Liquid is not available at run-time in the browser when a user executes an event.
|
||||
|
||||
|
|
|
|||
|
|
@ -105,4 +105,3 @@ _site/
|
|||
.bundle/
|
||||
vendor/
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -31,5 +31,3 @@ title: Video Walkthroughs
|
|||
17. [Data Files](https://www.youtube.com/watch?v=M6b0KmLB-pM&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB&index=17)
|
||||
18. [Static Files](https://www.youtube.com/watch?v=knWjmVlVpso&index=18&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB)
|
||||
19. [Hosting on Github Pages](https://www.youtube.com/watch?v=fqFjuX4VZmU&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB&index=19)
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue