dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Step By Step Instructions Review (#8399) 

Merge pull request 8399
This commit is contained in:
Shannon Kularathna 2021-01-19 03:56:09 -05:00 committed by GitHub
parent 4f0dbdb9e8
commit d46897fabf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 118 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/_docs/step-by-step/01-setup.md
View File

@ -4,59 +4,58 @@ title: Setup
menu_name: Step by Step Tutorial menu_name: Step by Step Tutorial
position: 1 position: 1
--- ---
Welcome to Jekyll's step-by-step tutorial. The goal of this tutorial is to take Welcome to Jekyll's step-by-step tutorial. This tutorial takes
you from having some front end web development experience to building your 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. first Jekyll site from scratch without relying on the default gem-based theme.
Let's get into it!
## Installation ## Installation
Jekyll is a Ruby program so you need to install Ruby on your machine to begin Jekyll is a Ruby gem. First, install Ruby on your machine.
with. Head over to the [install guide](/docs/installation/) and follow the Go to [Installation]({{ '/docs/installation/' | relative_url }}) and follow the
instructions for your operating system. instructions for your operating system.
With Ruby setup you can install Jekyll by running the following in your With Ruby installed, install Jekyll from the terminal:
terminal:
```sh ```sh
gem install jekyll bundler 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 ```sh
bundle init 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 ```ruby
gem "jekyll" 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` 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`. to make sure you use the jekyll version defined in your `Gemfile`.
## Create a site ## Create a site
It's time to create a site! Create a new directory for your site, you can name It's time to create a site! Create a new directory for your site and name
it whatever you'd like. Through the rest of this tutorial we'll refer to this it whatever you want. Through the rest of this tutorial we'll refer to this
directory as “root”. 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 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 site structure are files that a Git repository can version. Using a repository
is completely optional but it's a great habit to get into. You can learn more is optional but is recommended. You can learn more
about using Git by reading through the about using Git by reading the
[Git Handbook](https://guides.github.com/introduction/git-handbook/). [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: content:
```html ```html
<!doctype html> <!DOCTYPE html>
<html> <html>
<head> <head>
<meta charset="utf-8"> <meta charset="utf-8">
@ -70,22 +69,24 @@ content:
## Build ## Build
Jekyll is a static site generator so we need Jekyll to build the site Since Jekyll is a static site generator, it has to build the site
before we can view it. There are two commands you can run in the root of your site before we can view it. Run either of the following commands to build your site:
to build it:
* `jekyll build` - Builds the site and outputs a static site to a directory * `jekyll build` - Builds the site and outputs a static site to a directory
called `_site`. called `_site`.
* `jekyll serve` - Does the same thing except it rebuilds any time you make * `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.
a change and runs a local web server at `http://localhost:4000`.
When you're developing a site you'll use `jekyll serve` as it updates with any {: .note .info}
changes you make. 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 Run `jekyll serve` and go to
<a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a> in <a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a> in
your browser. You should see "Hello World!". your browser. You should see "Hello World!".
Well, you might be thinking what's the point in this? Jekyll just copied an 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. Well patience young grasshopper, there's HTML file from one place to another.
Patience, young grasshopper, there's
still much to learn! still much to learn!
Next. you'll learn about Liquid and templating.

72
docs/_docs/step-by-step/02-liquid.md
View File

@ -3,28 +3,25 @@ layout: step
title: Liquid title: Liquid
position: 2 position: 2
--- ---
Liquid is where Jekyll starts to get more interesting. Liquid is a templating Liquid is where Jekyll starts to get more interesting. It is a templating
language which has three main parts: [objects](#objects), [tags](#tags) and language which has three main components:
[filters](#filters). * [objects](#objects)
* [tags](#tags)
* [filters](#filters)
## Objects ## Objects
Objects tell Liquid where to output content. They're denoted by double curly Objects tell Liquid to output predefined [variables](../../variables) as content on a page. Use double curly braces for objects: {% raw %}`{{`{% endraw %} and {% raw %}`}}`{% endraw %}.
braces: {% raw %}`{{`{% endraw %} and {% raw %}`}}`{% endraw %}. For example:
{% raw %} For example, {% raw %}`{{ page.title }}`{% endraw %} displays the `page.title` variable.
```liquid
{{ page.title }}
```
{% endraw %}
Outputs a variable called `page.title` on the page.
## Tags ## Tags
Tags create the logic and control flow for templates. They are denoted by curly Tags define the logic and control flow for templates. Use curly
braces and percent signs: {% raw %}`{%`{% endraw %} and braces and percent signs for objects: {% raw %}`{%`{% endraw %} and
{% raw %}`%}`{% endraw %}. For example: {% raw %}`%}`{% endraw %}.
For example:
{% raw %} {% raw %}
```liquid ```liquid
@ -36,13 +33,16 @@ braces and percent signs: {% raw %}`{%`{% endraw %} and
``` ```
{% endraw %} {% endraw %}
Outputs the sidebar if `page.show_sidebar` is true. You can learn more about the This displays the sidebar if the value of the `show_sidebar` page variable is true.
tags available to Jekyll [here](/docs/liquid/tags/).
Learn more about the tags available in Jekyll [here](/docs/liquid/tags/).
## Filters ## Filters
Filters change the output of a Liquid object. They are used within an output 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 %} {% raw %}
```liquid ```liquid
@ -50,12 +50,13 @@ and are separated by a `|`. For example:
``` ```
{% endraw %} {% endraw %}
Outputs `Hi`. You can learn more about the filters available to Jekyll This displays `Hi` instead of `hi`.
[here](/docs/liquid/filters/).
Learn more about the filters available in Jekyll [here](/docs/liquid/filters/).
## Use Liquid ## 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 %} {% raw %}
```liquid ```liquid
@ -65,7 +66,7 @@ Now it's your turn, change the Hello World! on your page to output as lowercase:
``` ```
{% endraw %} {% 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 ```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 {% raw %}
Liquid with other features. ```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.

24
docs/_docs/step-by-step/03-front-matter.md
View File

@ -3,9 +3,10 @@ layout: step
title: Front Matter title: Front Matter
position: 3 position: 3
--- ---
Front matter is a snippet of [YAML](http://yaml.org/) which sits between two Front matter is a snippet of [YAML](http://yaml.org/) placed between two
triple-dashed lines at the top of a file. Front matter is used to set variables triple-dashed lines at the start of a file.
for the page, for example:
You can use front matter to set variables for the page:
```yaml ```yaml
--- ---
@ -13,8 +14,8 @@ my_number: 5
--- ---
``` ```
Front matter variables are available in Liquid under the `page` variable. For You can call front matter variables in Liquid using the `page` variable. For
example to output the variable above you would use: example, to output the value of the `my_number` variable above:
{% raw %} {% raw %}
```liquid ```liquid
@ -24,7 +25,7 @@ example to output the variable above you would use:
## Use front matter ## 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 %} {% raw %}
```liquid ```liquid
@ -44,15 +45,14 @@ title: Home
``` ```
{% endraw %} {% endraw %}
Note that in order for Jekyll to process any liquid tags on your page, {: .note .info }
you _must_ include front matter on it. The most minimal snippet of front matter You _must_ include front matter on the page for Jekyll to process any Liquid tags on it.
you can include is:
To make Jekyll process a page without defining variables in the front matter, use:
```yaml ```yaml
--- ---
--- ---
``` ```
You may still be wondering why you'd output it this way as it takes Next, you'll learn more about layouts and why your pages use more source code than plain HTML.
more source code than raw HTML. In this next step, you'll see why we've
been doing this.

60
docs/_docs/step-by-step/04-layouts.md
View File

@ -3,27 +3,27 @@ layout: step
title: Layouts title: Layouts
position: 4 position: 4
--- ---
Websites typically have more than one page and this website is no different.
Jekyll supports [Markdown](https://daringfireball.net/projects/markdown/syntax) 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 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. You could copy the contents of `index` and modify it for the About page. However,
The problem with doing this is duplicate code. Let's say you wanted to add a this creates duplicate code that has to be customized for each new page you add
stylesheet to your site, you would have to go to each page and add it to the to your site.
`<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. 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 ## Creating a layout
Using a layout is a much better choice. Layouts are templates that wrap around Layouts are templates that can be used by any page in your site and wrap around page content.
your content. They live in a directory called `_layouts`. 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 %} {% raw %}
```liquid ```liquid
@ -40,14 +40,17 @@ Create your first layout at `_layouts/default.html` with the following content:
``` ```
{% endraw %} {% endraw %}
You'll notice this is almost identical to `index.html` except there's This HTML is almost identical to `index.html` except there's
no front matter and the content of the page is replaced with a `content` no front matter and the content of the page is replaced by a `content`
variable. `content` is a special variable which has the value of the rendered variable.
content of the page it's called on.
To have `index.html` use this layout, you can set a `layout` variable in front `content` is a special variable that returns the rendered
matter. The layout wraps around the content of the page so all you need in content of the page on which it's called.
`index.html` is:
## 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 %} {% raw %}
```liquid ```liquid
@ -59,16 +62,14 @@ title: Home
``` ```
{% endraw %} {% endraw %}
After doing this, the output will be exactly the same as before. Note that you When you reload the site, the output remains the same.
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.
## 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 ## Build the About page
layout.
Add the following to `about.md`: Add the following to `about.md` to use your new layout in the About page:
```markdown ```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> 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. in your browser and view your new page.
Congratulations, you now have a two page website! But how do you Congratulations, you now have a two page website!
navigate from one page to another? Keep reading to find out.
Next, you'll learn about navigating from page to page in your site.