Shannon Kularathna
GitHub
parent
4f0dbdb9e8
commit
d46897fabf
|
|
@ -4,59 +4,58 @@ title: Setup
|
|||
menu_name: Step by Step Tutorial
|
||||
position: 1
|
||||
---
|
||||
Welcome to Jekyll's step-by-step tutorial. The goal of this tutorial is to take
|
||||
you from having some front end web development experience to building your
|
||||
first Jekyll site from scratch — not relying on the default gem-based theme.
|
||||
Let's get into it!
|
||||
Welcome to Jekyll's step-by-step tutorial. This tutorial takes
|
||||
you from having some front-end web development experience to building your
|
||||
first Jekyll site from scratch without relying on the default gem-based theme.
|
||||
|
||||
## Installation
|
||||
|
||||
Jekyll is a Ruby program so you need to install Ruby on your machine to begin
|
||||
with. Head over to the [install guide](/docs/installation/) and follow the
|
||||
Jekyll is a Ruby gem. First, install Ruby on your machine.
|
||||
Go to [Installation]({{ '/docs/installation/' | relative_url }}) and follow the
|
||||
instructions for your operating system.
|
||||
|
||||
With Ruby setup you can install Jekyll by running the following in your
|
||||
terminal:
|
||||
With Ruby installed, install Jekyll from the terminal:
|
||||
|
||||
```sh
|
||||
gem install jekyll bundler
|
||||
```
|
||||
|
||||
To create a new `Gemfile` to list your project's dependencies run:
|
||||
Create a new `Gemfile` to list your project's dependencies:
|
||||
|
||||
```sh
|
||||
bundle init
|
||||
```
|
||||
|
||||
Now edit the `Gemfile` and add jekyll as a dependency:
|
||||
Edit the `Gemfile` in a text editor and add jekyll as a dependency:
|
||||
|
||||
```ruby
|
||||
gem "jekyll"
|
||||
```
|
||||
|
||||
Finally run `bundle` to install jekyll for your project.
|
||||
Run `bundle` to install jekyll for your project.
|
||||
|
||||
You can now prefix all jekyll commands listed in this tutorial with `bundle exec`
|
||||
to make sure you use the jekyll version defined in your `Gemfile`.
|
||||
|
||||
## Create a site
|
||||
|
||||
It's time to create a site! Create a new directory for your site, you can name
|
||||
it whatever you'd like. Through the rest of this tutorial we'll refer to this
|
||||
directory as “root”.
|
||||
It's time to create a site! Create a new directory for your site and name
|
||||
it whatever you want. Through the rest of this tutorial we'll refer to this
|
||||
directory as **root**.
|
||||
|
||||
You can also initialize a Git repository here.
|
||||
|
||||
If you're feeling adventurous, you can also initialize a Git repository here.
|
||||
One of the great things about Jekyll is there's no database. All content and
|
||||
site structure are files which a Git repository can version. Using a repository
|
||||
is completely optional but it's a great habit to get into. You can learn more
|
||||
about using Git by reading through the
|
||||
site structure are files that a Git repository can version. Using a repository
|
||||
is optional but is recommended. You can learn more
|
||||
about using Git by reading the
|
||||
[Git Handbook](https://guides.github.com/introduction/git-handbook/).
|
||||
|
||||
Let's add your first file. Create `index.html` in the root with the following
|
||||
Let's add your first file. Create `index.html` in **root** with the following
|
||||
content:
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
|
|
@ -70,22 +69,24 @@ content:
|
|||
|
||||
## Build
|
||||
|
||||
Jekyll is a static site generator so we need Jekyll to build the site
|
||||
before we can view it. There are two commands you can run in the root of your site
|
||||
to build it:
|
||||
Since Jekyll is a static site generator, it has to build the site
|
||||
before we can view it. Run either of the following commands to build your site:
|
||||
|
||||
* `jekyll build` - Builds the site and outputs a static site to a directory
|
||||
called `_site`.
|
||||
* `jekyll serve` - Does the same thing except it rebuilds any time you make
|
||||
a change and runs a local web server at `http://localhost:4000`.
|
||||
* `jekyll serve` - Does `jekyll build` and runs it on a local web server at `http://localhost:4000`, rebuilding the site any time you make a change.
|
||||
|
||||
When you're developing a site you'll use `jekyll serve` as it updates with any
|
||||
changes you make.
|
||||
{: .note .info}
|
||||
When you're developing a site, use `jekyll serve`. To force the browser to refresh with every change, use `jekyll serve --livereload`.
|
||||
|
||||
Run `jekyll serve` and go to
|
||||
<a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a> in
|
||||
your browser. You should see "Hello World!".
|
||||
|
||||
Well, you might be thinking what's the point in this? Jekyll just copied an
|
||||
HTML file from one place to another. Well patience young grasshopper, there's
|
||||
At this point, you might be thinking, "So what?". The only thing that happened was that Jekyll copied an
|
||||
HTML file from one place to another.
|
||||
|
||||
Patience, young grasshopper, there's
|
||||
still much to learn!
|
||||
|
||||
Next. you'll learn about Liquid and templating.
|
||||
|
|
|
|||
|
|
@ -3,28 +3,25 @@ layout: step
|
|||
title: Liquid
|
||||
position: 2
|
||||
---
|
||||
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).
|
||||
Liquid is where Jekyll starts to get more interesting. It is a templating
|
||||
language which has three main components:
|
||||
* [objects](#objects)
|
||||
* [tags](#tags)
|
||||
* [filters](#filters)
|
||||
|
||||
## Objects
|
||||
|
||||
Objects tell Liquid where to output content. They're denoted by double curly
|
||||
braces: {% raw %}`{{`{% endraw %} and {% raw %}`}}`{% endraw %}. For example:
|
||||
Objects tell Liquid to output predefined [variables](../../variables) as content on a page. Use double curly braces for objects: {% raw %}`{{`{% endraw %} and {% raw %}`}}`{% endraw %}.
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ page.title }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Outputs a variable called `page.title` on the page.
|
||||
For example, {% raw %}`{{ page.title }}`{% endraw %} displays the `page.title` variable.
|
||||
|
||||
## Tags
|
||||
|
||||
Tags create the logic and control flow for templates. They are denoted by curly
|
||||
braces and percent signs: {% raw %}`{%`{% endraw %} and
|
||||
{% raw %}`%}`{% endraw %}. For example:
|
||||
Tags define the logic and control flow for templates. Use curly
|
||||
braces and percent signs for objects: {% raw %}`{%`{% endraw %} and
|
||||
{% raw %}`%}`{% endraw %}.
|
||||
|
||||
For example:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
|
|
@ -36,13 +33,16 @@ braces and percent signs: {% raw %}`{%`{% endraw %} and
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
Outputs the sidebar if `page.show_sidebar` is true. You can learn more about the
|
||||
tags available to Jekyll [here](/docs/liquid/tags/).
|
||||
This displays the sidebar if the value of the `show_sidebar` page variable is true.
|
||||
|
||||
Learn more about the tags available in Jekyll [here](/docs/liquid/tags/).
|
||||
|
||||
## Filters
|
||||
|
||||
Filters change the output of a Liquid object. They are used within an output
|
||||
and are separated by a `|`. For example:
|
||||
and are separated by a `|`.
|
||||
|
||||
For example:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
|
|
@ -50,12 +50,13 @@ and are separated by a `|`. For example:
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
Outputs `Hi`. You can learn more about the filters available to Jekyll
|
||||
[here](/docs/liquid/filters/).
|
||||
This displays `Hi` instead of `hi`.
|
||||
|
||||
Learn more about the filters available in Jekyll [here](/docs/liquid/filters/).
|
||||
|
||||
## Use Liquid
|
||||
|
||||
Now it's your turn, change the Hello World! on your page to output as lowercase:
|
||||
Now, use Liquid to make your `Hello World!` text from [Setup](../01-setup) lowercase:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
|
|
@ -65,7 +66,7 @@ Now it's your turn, change the Hello World! on your page to output as lowercase:
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
To get our changes processed by Jekyll we need to add [front matter](../03-front-matter/) to the top of the page:
|
||||
To make Jekyll process your changes, add [front matter](../03-front-matter/) to the top of the page:
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -73,11 +74,28 @@ To get our changes processed by Jekyll we need to add [front matter](../03-front
|
|||
---
|
||||
```
|
||||
|
||||
Our "Hello World!" will now be downcased on render.
|
||||
Your HTML document should look like this:
|
||||
|
||||
It may not seem like it now, but much of Jekyll's power comes from combining
|
||||
Liquid with other features.
|
||||
{% raw %}
|
||||
```html
|
||||
---
|
||||
---
|
||||
|
||||
In order to see the changes from `downcase` Liquid filter, we will need to add front matter.
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Home</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>{{ "Hello World!" | downcase }}</h1>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
That's next. Let's keep going.
|
||||
When you reload your browser, you should see `hello world!`.
|
||||
|
||||
Much of Jekyll's power comes from combining Liquid with other features. Add frontmatter to pages to make Jekyll process the Liquid on those pages.
|
||||
|
||||
Next, you'll learn more about frontmatter.
|
||||
|
|
@ -3,9 +3,10 @@ layout: step
|
|||
title: Front Matter
|
||||
position: 3
|
||||
---
|
||||
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:
|
||||
Front matter is a snippet of [YAML](http://yaml.org/) placed between two
|
||||
triple-dashed lines at the start of a file.
|
||||
|
||||
You can use front matter to set variables for the page:
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -13,8 +14,8 @@ my_number: 5
|
|||
---
|
||||
```
|
||||
|
||||
Front matter variables are available in Liquid under the `page` variable. For
|
||||
example to output the variable above you would use:
|
||||
You can call front matter variables in Liquid using the `page` variable. For
|
||||
example, to output the value of the `my_number` variable above:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
|
|
@ -24,7 +25,7 @@ example to output the variable above you would use:
|
|||
|
||||
## Use front matter
|
||||
|
||||
Let's change the `<title>` on your site to populate using front matter:
|
||||
Change the `<title>` on your site to use front matter:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
|
|
@ -44,15 +45,14 @@ 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:
|
||||
{: .note .info }
|
||||
You _must_ include front matter on the page for Jekyll to process any Liquid tags on it.
|
||||
|
||||
To make Jekyll process a page without defining variables in the front matter, use:
|
||||
|
||||
```yaml
|
||||
---
|
||||
---
|
||||
```
|
||||
|
||||
You may still be wondering why you'd output it this way as it takes
|
||||
more source code than raw HTML. In this next step, you'll see why we've
|
||||
been doing this.
|
||||
Next, you'll learn more about layouts and why your pages use more source code than plain HTML.
|
||||
|
|
@ -3,27 +3,27 @@ layout: step
|
|||
title: Layouts
|
||||
position: 4
|
||||
---
|
||||
Websites typically have more than one page and this website is no different.
|
||||
|
||||
Jekyll supports [Markdown](https://daringfireball.net/projects/markdown/syntax)
|
||||
as well as HTML for pages. Markdown is a great choice for pages with a simple
|
||||
in addition to HTML when building pages. Markdown is a great choice for pages with a simple
|
||||
content structure (just paragraphs, headings and images), as it's less verbose
|
||||
than raw HTML. Let's try it out on the next page.
|
||||
than raw HTML.
|
||||
|
||||
Create `about.md` in the root.
|
||||
Create a new Markdown file named `about.md` in your site's root folder.
|
||||
|
||||
For the structure you could copy `index.html` and modify it for the about page.
|
||||
The problem with doing this is duplicate code. Let's say you wanted to add a
|
||||
stylesheet to your site, you would have to go to each page and add it to the
|
||||
`<head>`. It might not sound so bad for a two page site, imagine doing it
|
||||
for 100 pages. Even simple changes will take a long time to make.
|
||||
You could copy the contents of `index` and modify it for the About page. However,
|
||||
this creates duplicate code that has to be customized for each new page you add
|
||||
to your site.
|
||||
|
||||
For example, adding a new stylesheet to your site would involve adding the link
|
||||
to the stylesheet to the `<head>` of each page. For sites with many pages, this
|
||||
is a waste of time.
|
||||
|
||||
## Creating a layout
|
||||
|
||||
Using a layout is a much better choice. Layouts are templates that wrap around
|
||||
your content. They live in a directory called `_layouts`.
|
||||
Layouts are templates that can be used by any page in your site and wrap around page content.
|
||||
They are stored in a directory called `_layouts`.
|
||||
|
||||
Create your first layout at `_layouts/default.html` with the following content:
|
||||
Create the `_layouts` directory in your site's root folder and create a new `default.html` file with the following content:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
|
|
@ -40,14 +40,17 @@ Create your first layout at `_layouts/default.html` with the following content:
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
You'll notice this is almost identical to `index.html` except there's
|
||||
no front matter and the content of the page is replaced with a `content`
|
||||
variable. `content` is a special variable which has the value of the rendered
|
||||
content of the page it's called on.
|
||||
This HTML is almost identical to `index.html` except there's
|
||||
no front matter and the content of the page is replaced by a `content`
|
||||
variable.
|
||||
|
||||
To have `index.html` use this layout, you can set a `layout` variable in front
|
||||
matter. The layout wraps around the content of the page so all you need in
|
||||
`index.html` is:
|
||||
`content` is a special variable that returns the rendered
|
||||
content of the page on which it's called.
|
||||
|
||||
## Use layouts
|
||||
|
||||
To make `index.html` use your new layout, set the `layout` variable in the front
|
||||
matter. The file should look like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
|
|
@ -59,16 +62,14 @@ title: Home
|
|||
```
|
||||
{% endraw %}
|
||||
|
||||
After doing this, the output will be exactly the same as before. Note that you
|
||||
can access the `page` front matter from the layout. In this case `title` is
|
||||
set in the index page's front matter but is output in the layout.
|
||||
When you reload the site, the output remains the same.
|
||||
|
||||
## About page
|
||||
Since the layout wraps around the content on the page, you can call front matter like `page`
|
||||
in the layout file. When you apply the layout to a page, it uses the front matter on that page.
|
||||
|
||||
Back to the about page, instead of copying from `index.html`, you can use the
|
||||
layout.
|
||||
## Build the About page
|
||||
|
||||
Add the following to `about.md`:
|
||||
Add the following to `about.md` to use your new layout in the About page:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
|
@ -83,5 +84,6 @@ This page tells you a little bit about me.
|
|||
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.
|
||||
|
||||
Congratulations, you now have a two page website! But how do you
|
||||
navigate from one page to another? Keep reading to find out.
|
||||
Congratulations, you now have a two page website!
|
||||
|
||||
Next, you'll learn about navigating from page to page in your site.
|
||||
Loading…
Reference in New Issue