Getting Started with Jekyll

3 minute read
, ,

What is Jekyll?

Jekyll is a static site generator. It takes your content, renders Markdown and Liquid templates, and spits out a complete, static website ready to be served by Apache, Nginx or another web server. You can even host your site for free on GitHub Pages.

what language is jekyll written in?

Jekyll is written in Ruby.

Installing ruby

Windows

  1. Download and install Ruby+Devkit.
  2. Run ridk install to install the Devkit and install all components.
  3. To check if ruby is installed, run ruby -v and gem -v in the command prompt.

Note: If ruby is not recognized as a command, you may need to add the ruby bin directory to your PATH environment variable.

  • Go to ruby/bin directory, by default it is C:\Ruby27-x64\bin if you installed it in the default directory. Copy the path.
  • Open the Control Panel, click System and Security, then click System.
  • Click Advanced system settings on the left and then click Environment Variables.
  • Under System variables, click Path, then click Edit.
  • Click New and paste the path you copied earlier.
  • Click OK to save the change.

Installing Jekyll

  1. Run gem install jekyll bundler to install Jekyll and Bundler.
  2. Run jekyll -v to check if Jekyll is installed.

Jekyll Structure

 1./
 2├── _config.yml
 3├── _drafts/
 4│ ├── begin-with-the-crazy-ideas.textile
 5│ └── on-simplicity-in-technology.markdown
 6├── _includes/
 7│ ├── footer.html
 8│ └── header.html
 9├── _layouts/
10│ ├── default.html
11│ └── post.html
12├── _posts/
13│ ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
14│ └── 2009-04-26-barcamp-boston-4-roundup.textile
15├── _data/
16│ └── members.yml
17├── _site/
18└── index.html

How to create a new post in jekyll?

  1. Create a new file in _posts directory.
  2. The file name must be in the format YYYY-MM-DD-title.md.
  3. Add the following front matter to the top of the file:
 1---
 2title: "Title of the post"
 3date: YYYY-MM-DD HH:MM:SS +/-TTTT
 4tags:
 5  - tag1
 6  - tag2
 7category: category
 8keywords:
 9  - keyword1
10  - keyword2
11---
  1. Write the post in markdown.

what is markdown?

Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats using a tool by the same name.

Creating a new Jekyll site

  1. Run jekyll new my-awesome-site to create a new Jekyll site.
  2. Run cd my-awesome-site to go to the site directory.
  3. Run bundle exec jekyll serve to start the Jekyll server.
  4. Open http://localhost:4000 in your browser to see the site.

Creating a new post

  1. Run bundle exec jekyll post "My New Post" to create a new post.

  2. Open the post file in your text editor.

  3. Add the following front matter to the top of the file:

     1---
 2title: My New Post
 3date: 2019-04-03 17:51:42
 4tags:
 5  - tag1
 6  - tag2
 7category: category
 8keywords:
 9  - keyword1
10  - keyword2
11---

  4. Write your post in Markdown.

  5. Save the file.

  6. Run bundle exec jekyll serve to start the Jekyll server.

  7. Open http://localhost:4000 in your browser to see the site.

    Notes:

    • If you want to use a different date for the post, you can use the --date option when creating the post. For example, bundle exec jekyll post "My New Post" --date 2019-04-03.
    • If you want to use a different port, you can use the --port option when starting the server. For example, bundle exec jekyll serve --port 3000.

Creating a new page

  1. Run bundle exec jekyll page "My New Page" to create a new page.
  2. Open the page file in your text editor.
  3. Add the following front matter to the top of the file:
 1---
 2title: My New Page
 3date: 2019-04-03 17:51:42
 4tags:
 5  - tag1
 6  - tag2
 7category: category
 8keywords:
 9  - keyword1
10  - keyword2
11---

  1. Write your page in Markdown.

    Note: If you want to create a page that is not in the navigation menu, add nav_exclude: true to the front matter.

  2. Save the file.

  3. Run bundle exec jekyll serve to start the Jekyll server.

  4. Open http://localhost:4000 in your browser to see the site.

Questions

  • Is it possible to serve multiple Jekyll sites locally?

Yes, you can use the --port option to serve multiple sites on different ports. For example, bundle exec jekyll serve --port 3000 will serve the site on port 3000. You can then serve another site on port 4000 by running bundle exec jekyll serve --port 4000.

reference: stackoverflow question by Brian Zelip

Jekyll cheatsheet and documentation

reference:

comments powered by Disqus