All posts tagged “Jekyll”

How to Upload Jekyll to Github Page

We have discussed how to setup a Jekyll blog locally in our computer, create a draft, and manage multiple drafts with the use of a plugin in the previous posts. Now, we are ready to deploy the blog to the online server, letting the world see how awesome our blog is.

Deploying Jekyll to online server is so easy, as it is only a static website. All you need is shared hosting with decent hard disk space and bandwidth sufficient enough to host it. The cost for shared hosting should be affordable. But then again, why worry when you can host a Jekyll blog completely for free – using Github Pages.

Github offers Github Pages for free for anyone to host their static websites. It has Jekyll built-in, so it is a good place to host our Jekyll-powered blog. In this article, we will show you how to deploy our blog to Github Pages.

Getting Started

First, you need to have a Github account. Once you have one, create a new repository. The name of your repository will be used for the blog address in the following format {username}.github.io/{repo-name}.

In this example, I will name my repository simply as blog. When the repository has been created, copy the clone url.

Add, Commit, and Push

We are going to upload our local Jekyll files to our newly created Github repository. I will use Github for Mac to do the job, which can be downloaded for free – Github for Windows is also available for Windows users.

Let’s launch Github app, and then add our Jekyll blog directory as a Local Repository.

Head over to the Settings page. Paste the Github git clone URL that was copied above.

Commit and Push the files to Github.

Go to Github. Ensure that all files have been successfully uploaded.

Github Pages Branch

Creating a Github page for a repository is as easy as creating a new git branch. In the Github app, go to the Branches tab. Create a new branch named gh-pages of the master branch, and click the Publish button.

The new branch is now registered in the Github repository, like so.

The Github Page for your repository should be ready in a few minutes. When it is, you can open it on the browsers at {username}.github.io/{repo-name}, for example:

Troubleshooting

If the blog is not styled properly, this could be because the stylesheet is not linked properly. To solve this issue, open the default.html in _layouts folder. You will see that the stylesheet is initialized with a slash sign, /.

 <link rel="stylesheet" href="/css/syntax.css"> 

Omit that first slash, so the path looks like the following:

 <link rel="stylesheet" href="css/syntax.css"> 

Then Commit the change, and Push it to Github. The blog should now be displayed properly.





hongkiat.com

Managing Multiple Drafts Easily in Jekyll

Despite of only being a static website, we can utilize a plugin in Jekyll too. Let’s continue our discussion on creating drafts from the previous post. As you can see before – in the previous post – we created the drafts and put them within a special folder called _drafts first.

Then, as we are ready to publish it, we move them to the _posts folder with the proper naming format.

It sounds easy right? it should be no problem if you’d only manage 1 or 2 post drafts. But, when you have 5-10 post drafts, changing each file name, and specifying the correct date by hand can be a pain. Let’s take a look how we can simplify the workflow with a Jekyll plugin.

Getting Started

Before we go any further, let’s create a new folder named _plugins; this folder is required as Jekyll will search and execute plugins from within the folder. We also need to create a new file named publisher.rb in it; technically, you can freely name that file with any name you like.

We will be using a Jekyll plugin created by Jeffrey Sambells. This plugin will take care of the hassle when publishing a post from a draft in Jekyll. It will rename the file properly, along with the date. And it will also specify the date within the post Front Matter section.

The following is the source code of the plugin, available from this Gist page. Copy this code below and paste it to the publisher.rb file that we have just created.

 module Jekyll class PostPublisher < Generator safe false def replace(filepath, regexp, *args, &block) content = File.read(filepath).gsub(regexp, *args, &block) File.open(filepath, 'wb') { |file| file.write(content) } end def generate(site) @files = Dir["_publish/*"] @files.each_with_index { |f,i| now = DateTime.now.strftime("%Y-%m-%d %H:%M:%S") replace(f, /^date: unpublished/mi) { |match| "date: \"" + now + "\"" } now = Date.today.strftime("%Y-%m-%d") File.rename(f, "_posts/#{now}-#{File.basename(f)}") } end end end 

If your Jekyll server is currently running, restart it for the plugin to work.

Using the Plugin

To use the plugin, we need to create a new folder named _publish. We will move our post drafts to this folder, once we are ready to publish it. However, before doing so, set the date in the post draft’s front matter to unpublished, like so

 --- layout: post title: "This is My Second Post" date: unpublished --- 

Now, move the draft to the _publish folder.

jekyll-plugin/

As mentioned, Jekyll will automatically move the folder to _posts as well as set the post date, then publish the post for you.

Final Thought

We have seen that Jekyll is extensible with a plugin. In this post, for instance, we used one to simplify the process of publishing a draft. You can find more Jekyll plugins in this page: Available Plugins.

Now that we have learned how to setup Jekyll, and publish a post draft. In the next post, we will show you how to publish Jekyll blog to an online server via FTP. Stay tuned!





hongkiat.com

How to Create Post Draft In Jekyll

In the previous post, we have shown you how to install Jekyll and publish your first post with it. If you have followed it, you can see that creating a post is a breeze; we simply create a new Markdown file, save it within the /_posts folder, and it will show up in the blog immediately.

That, however, could be a problem if you have put your blog online. Your post may have unfinished sentences, contain errors, and a few other things that should not be seen by your readers.

That’s why we usually create a draft first before pressing the Publish button. So, in this post, we will show you how to create a post draft in Jekyll before it hits the public eye.

But first, let’s start up the Jekyll server with the following command line.

 jekyll server --watch 

File and Directory

Prior to version 1.0, working with a draft in Jekyll is hardly manageable. There are numerous ways to deal with it.

Some have set published: false in the post files to prevent it from being published, and some put future: false in the configuration file to prevent Jekyll from generating posts with a future date — which still will be published once the date rolls around.

Now, Jekyll has made things simpler to control.

Jekyll relies on strict directory structure. In the case of creating drafts, we need to create a new folder named _drafts. We put all drafts into this folder.

The draft file name does not have to include the post date; we can just name it this way:

Jekyll will ignore this folder. You can write your post as usual, and it won’t be displayed out in the open yet. Once you are done with your post, you can put it in the _posts folder, and add a proper date in the filename.

Hold on?!

Hold on, can’t we just create any folder? Well, the _drafts folder name is the official naming convention to put your drafts in. We technically can name the folder anything, but doing so would prevent us from previewing our drafts.

In Jekyll, we can run the jekyll command with the --drafts flag to preview the drafts: jekyll server --watch --drafts Refresh your blog, and you will see the draft appear on the blog. The draft will be displayed with its latest modified date.

Conclusion

We have shown you how to create a draft in Jekyll. It’s quite simple. But we can make the workflow from draft to publication more streamlined with the help of a plugin. We will discuss it in the next post. So, stay tuned.





hongkiat.com

How to Create a Blog with Jekyll – A Beginner’s Guide

WordPress, which humbly started as a blogging platform, has now transformed into a full-fledged and a very popular CMS. With WordPress, you can build (almost) any kind of website, from a portfolio to an e-Commerce website.

But what if you only concern about blogging, and you do not need jam-packed features in WordPress like custom taxonomy, user management, comment moderation, and a nice media uploader?

In short, you just want to be focusing on writing and publishing your content. If that is something you have in mind, let’s meet Jekyll, a static blogging engine.

About Jekyll

Jekyll comes with the idea of creating a static (same old HTML) blog, one which is easily maintainable. In comparison to a dynamic blogging tool, like WordPress that is built with a server-side language like PHP, a static website has 2 key advantages.

First, it serves and perform faster. Second, it consumes less web resources namely memory and database I/O. Additionally, if you use Jekyll, you can host your blog in Github Pages for free.

Install Jekyll

First, let’s install Jekyll in our system. Launch Terminal and type the following command line:

 sudo gem install jekyll 

Once installed, run this command to ensure that jekyll command is functioning.

 jekyll -v 

The command should show the Jekyll version, like so:

Create a Jekyll Site

To create a new blog with Jekyll, type jekyll followed by new and the name of the site in Terminal. For example:

 jekyll new jekyll-blog 

In this example, it created a new directory as specified, jekyll-blog, as well as the following stuff within:

Type this command below to activate Jekyll server.

 jekyll serve 

You can also run the the server using the --watch flag; that way it will automatically update the blog everytime we made a change.

Go to the browser and type http://localhost:4000, or as shown in the Terminal screen to open the blog.

The Document Structure

Jekyll applies a specific document structure that we have to follow, so the blog could function properly. Let’s take a look at what we have in our blog directory below:

 |-- _config.yml |-- _layouts |-- _posts |-- _site |-- css `-- index.html 

First, we have _config.yml; it is the the blog’s configuration file written in Yaml. In this file we can specify the blog name, the permalink format, host, Port number, and etc.

_layouts is where we put customized layout for page or post.

_posts is the directory where we save all our posts. All the posts should be written either with Markdown or Textile. They will be compiled and save the output in _site directory; this is the directory where Jekyll will serve the posts in the Browser.

Lastly, we have css and index.html.

For now, we will leave them as they are, with no custom configuration. Let’s start writing our first post.

Writing a New Post

As mentioned above, in Jekyll, we either write the post in Markdown or Textile. We have covered in the previous on how to write with Markdown; you may want to check that link first before going any further.

Naming Convention

To create a post, we also create a new file that must follow this naming convention year-month-date-{post-slug}.{file-extension}, for example: 2014-03-11-hello-world.md. Save the file in _posts directory.

Post Front-matter

Before we begin writing the body content of our post, we must first define the post front-matter namely the title and the post layout. We can also define the post categories and the tags, but these are optional. The most important thing is that the front-matter must be set within triple-dashed line. Here is an example:

 --- layout: post title: Hello World! --- 

Then we can write the content:

 Hello world! Welcome to Jekyll. This is your first post. 

Save the file. We will see the psot generated, and appear on our blog. Nice!

Wrap up

In this post, we have shown you how to install Jekyll and write your new post, which are the basic things that I think you ought to get to know before going further with Jekyll. There are a lot more things to explore in Jekyll, and we will discuss them in future posts. Stay tuned.





hongkiat.com