diff --git a/_drafts/2014-02-01-jekyll-github-pages-poole.md b/_drafts/2014-02-01-jekyll-github-pages-poole.md index a2582df98..bdf592950 100644 --- a/_drafts/2014-02-01-jekyll-github-pages-poole.md +++ b/_drafts/2014-02-01-jekyll-github-pages-poole.md @@ -1,20 +1,34 @@ --- layout: page -title: Moving from Wordpress to Jekyll + Github Pages + poole +title: How I Created a Beautiful and Minimal Blog Using Jekyll, Github Pages, and poole comments: true --- -I recently migrated this website from [Wordpress](http://wordpress.com) to [Github pages](http://pages.github.com/), and I am really happy with the transition. Over time, I grew to really dislike how heavy-weight Wordpress is. I've never liked how when you write HTML in a WYSIWYG editor you aren't sure what code it is creating. The process of backing up my blog was a huge pain, as was having to constantly upgrade Wordpress to avoid scurity risks. And whenever I went in to edit anything, I was always afraid that I would fat-finger change somthing without realizing it. I hated having to mantain a opaque database in order to keep all of my text. And I was never sure how to dive into the HTML if I wanted to customize anything. +I recently migrated this website from [Wordpress](http://wordpress.com) to [Github pages](http://pages.github.com/) +using [Jekyll](http://jekyllrb.com) and [poole](https://github.com/poole/poole). So far I am really happy with the transition. Over time, I grew to really dislike how heavy-weight Wordpress is. I dislike how WYSIWYG editors make it really hard to see what HTML is being generated and tend to totally bloat the code that is produced. And I found the plugin system so confusing that I was always afraid to try to customize the layout of anything. -So when I learned about [Jekyll](http://jekyllrb.com/), it seemed like a great alternative. I like the idea that my entire blog is a set of static files. Besides simplicity, it makes backups so much easier and avoids most common security risks to a website. I could write my posts in [Markdown](http://en.wikipedia.org/wiki/Markdown) which I am used to from [Confluence](https://www.atlassian.com/software/confluence) and [GitHub](http://github.com). And I was really excited that all of my blog posts would be static markdown files and I wouldn't have to deal with configuring a website. Also, markdown has the ability to really nicely embed coding examples. And finally, becasuse Jekyll is so light weight, I was able to give my blog the super-minimal and super-lightweight look I wanted. +The process of backing up Wordpress is a huge pain. I was constantly annoyed by having to upgrade Wordpress to avoid security risks. I hated having to keep an opaque database in order to keep all of my content. And whenever I went in to edit my website, I was always afraid that I would fat-finger change something and have no idea what happened. -The fact that Github provides [free hosting for Jekyll blogs](http://pages.github.com) is just icing on the cake. Besides having super easy version control of the blog, I can use Github's online editor to write blog posts and make minor modificaitons of the blog. -Instead of reading a lot of documentation, I found this really great git repo called [poole](https://github.com/poole/poole). poole provides "a clear and concise foundational setup for any Jekyll site. And it has a super minimal look which I was interested in. It does so by furnishing a full vanilla Jekyll install with example templates, pages, posts, and styles". So to get started with your own blog, all you have to do is great a new Git repo with the name .github.io, download the poole repository, and push it into your repo. A few minutes later the website .github.io will be ready. I only had a few posts on my previous website so I jsut copied them over manually, but there is [a package](http://jekyllrb.com/docs/migrations) for migrating blogs to Jekyll. +So when I learned about [Jekyll](http://jekyllrb.com/), it seemed like a great alternative. I like the idea that my entire blog is a set of static files. Besides its simplicity, it makes backups so much easier and avoids most common security concerns caused by running dynamic websites. I could write my posts in [Markdown](http://en.wikipedia.org/wiki/Markdown) which I am used to from [Confluence](https://www.atlassian.com/software/confluence) and [GitHub](http://github.com). And I was really excited that all of my blog posts would be static markdown files and I wouldn't have to deal with configuring a website. Also, Jekyll allows for code examples to be very nicely embedded in the website. Finally, Jekyll being so lightweight allowed me to make my website be super-minimal and remove most of the bloat common to other websites. + +The fact that GitHub provides [free hosting for Jekyll blogs](http://pages.github.com) is just icing on the cake. It will save me ~$50 per year in hosting. GitHub provides automatic version control of my blog. I can use GitHub's web editor to write blog posts online. And I can still connect it to my custom domain. + +# Getting Started + +Instead of reading a lot of documentation, I found this really great git repo called [poole](https://github.com/poole/poole). poole provides: + +> "a clear and concise foundational setup for any Jekyll site. And it has a super minimal look which I was interested in. It does so by furnishing a full vanilla Jekyll install with example templates, pages, posts, and styles." + +[Here](http://demo.getpoole.com/) is a demo of the poole website. It looks like + +![The demo pool website](/assets/demo_poole_website.png) + +To get started with my blog, all I had to do was create a new Git repo with the name [joshualande.github.io](joshualande.github.io), download the poole repository, and push it to my git repo. A few minutes later the website joshualande.github.io was be ready! I only had a few posts on my previous website so I josh copied them over manually. But there is [a package](http://jekyllrb.com/docs/migrations) for migrating blogs to Jekyll. # Blog Layout -The initial state of the poole repository is: +The initial state of the [poole](https://github.com/poole/poole) repository is: {% highlight sh %} $ ls -1 @@ -32,24 +46,31 @@ index.html public {% endhighlight %} +You can view the folder structure on [GitHub](https://github.com/poole/poole). When you run Jekyll, it creates a folder called _site with the -static website. Every file or folder will get directly copied -into the website except files or folders which begin with an underscore. +static website. Every file or folder in the repo will get copied +into the website unless it begins with an underscore. Markdown files will get automatically converted to HTML. +And poole uses the [Liquid](http://liquidmarkup.org) templating system to allow +for somewhat dynamic content on the website. -_posts contains all of the blog posts in markdown format: +The folder [_posts](https://github.com/poole/poole/tree/master/_posts) contains all of the blog posts in markdown format. +The example posts that come with poole are: {% highlight html %} $ ls -1 _posts/ 2013-12-31-whats-jekyll.md 2014-01-01-example-content.md 2014-01-02-introducing-poole.md {% endhighlight %} -index.html contains the front page of the blog and about.md is a -plot post in markdown format (which can be viewed at DOMAIN.com/about). +[index.html](https://github.com/poole/poole/blob/master/index.html) +contains the front page of the blog and +[about.md](https://github.com/poole/poole/blob/master/about.md) is a +static post in markdown format. If you want to have more static files, you can just add them to the -website. +repo and poole will copy them to the _site folder when rendering the website. -_config contains general configuration stuff for the website. +[_config](https://github.com/poole/poole/blob/master/_config.yml) +contains general configuration stuff for the website. {% highlight yaml %} # Setup title: Poole @@ -59,8 +80,9 @@ url: http://getpoole.com ... {% endhighlight %} -Finally, the _layouts and _includes folders contain boiler-plate HTML for building the website. -It is not very hard to go in and modify those files to change the look and feel of the site. +Finally, the [_layouts](https://github.com/poole/poole/blob/master/_layouts) +and [_includes](https://github.com/poole/poole/tree/master/_includes) +folders contain boiler-plate HTML for building the website. {% highlight yaml %} $ ls -1 _layouts/ default.html @@ -69,6 +91,7 @@ post.html $ ls -1 _includes/ head.html {% endhighlight %} +It is not very hard to go in and modify those files to change the look and feel of the site. # Customizations @@ -92,34 +115,36 @@ title: Archive {% endraw %} {% endhighlight %} -Next, I wanted to add a navigation bar at the top of the website with links to the [About](/about) and [Archive](/archive) page. To do this, I modified the file [_config.yml](https://github.com/joshualande/joshualande.github.io/blob/5e5ca6389fbc66be06488b9b7803e0278ee1b89f/_config.yml) to define a list of pages to show in my header: +Next, I wanted to add a navigation bar at the top of the website with links to the [About](/about) page, [Archive](/archive) page, and the feed. To do this, I modified the file [_config.yml](https://github.com/joshualande/joshualande.github.io/blob/64d03b883b64dd8aedf30b903ecaae92a282955a/_config.yml) to define a dictionary of pages to show in my header: {% highlight yaml %} -# This is the list of pages to incldue in the header of the website. -pages_list: ['About', 'Archive'] +pages_list: {'About':'/about','Archive':'/archive','Feed':'/atom.xml'} {% endhighlight %} -I then modify the file [_layouts/default.html](https://github.com/joshualande/joshualande.github.io/blob/5e5ca6389fbc66be06488b9b7803e0278ee1b89f/_layouts/default.html) to loop over this list and create links to each of the pages on the website: +I then modify the file [_layouts/default.html](https://github.com/joshualande/joshualande.github.io/blob/64d03b883b64dd8aedf30b903ecaae92a282955a/_layouts/default.html) to loop over this list, creating links to each of the pages: {% highlight html %} +{% raw %}

- {{ site.title }} - {% for page_name in site.pages_list %} -    {{ page_name }} - {% endfor %} +{{ site.title }} + +{% for page in site.pages_list %} +     + {{ page[0] }} +{% endfor %}

+{% endraw %} {% endhighlight %} +# Disqus Comments I wanted to enable [Disqus](http://disqus.com/) comments on the -blog. To do that, I modified the file _layouts/default.html to -include the line +blog. To do that, I modified the file [_layouts/default.html](https://github.com/joshualande/joshualande.github.io/blob/64d03b883b64dd8aedf30b903ecaae92a282955a/_layouts/default.html) to include the line: {% highlight python %} {% raw %} {% include comments.html %} {% endraw %} {% endhighlight %} -And then I created a file _includes/comments.html which includes the HTML code given to my by Disqus: - +I then created a file [_includes/comments.html](https://github.com/joshualande/joshualande.github.io/blob/64d03b883b64dd8aedf30b903ecaae92a282955a/_includes/comments.html) which includes the code given to my by Disqus: {% highlight html %} {% if page.comments %} @@ -139,18 +164,45 @@ And then I created a file _includes/comments.html which includes the HTML code g comments powered by Disqus {% endif %} {% endhighlight %} -By setting up the code this way, I can enabled posts on a page-by-page basis to include comments by setting "comments: True" in the YAML header of a post. +By setting up the code this way, I can enabled commenting on a page-by-page basis. All I have to do is set "comments: True" in the YAML header of the post. -And finally, I enabled Google Analtyics on the website... [TODO DOCUMENT] +# Google Analytics -If you have any questions about my implementation, you can view my website [on github](https://github.com/joshualande/joshualande.github.io) +Finally, I enabled [Google Analytics](http://www.google.com/analytics) on the website. First, I had to register my website through +the Google Analytics. Google gave me some tracking code to embed on every website which I put in the file +[\_includes/google\_analytics.html](https://github.com/joshualande/joshualande.github.io/blob/64d03b883b64dd8aedf30b903ecaae92a282955a/_includes/google_analytics): +{% highlight html %} + +{% endhighlight %} +Finally, I included this tracking code on all pages of my website by modifying the file +[_layouts/default.html](https://github.com/joshualande/joshualande.github.io/blob/64d03b883b64dd8aedf30b903ecaae92a282955a/_layouts/default.html) +to include the line: +{% highlight html %} +{% raw %} +{% include google_analytics.html %} +{% endraw %} +{% endhighlight %} + +# Getting a Custom URL + +Once I got my blog up to speed on GitHub with the URL joshualande.github.io, it was easy to link my personal domain [joshualande.com](http://joshualande.com) to it. I use Namecheap to host my domain, so I followed the instructions [here](http://davidensinger.com/2013/03/setting-the-dns-for-github-pages-on-namecheap). + +If you have any questions about my implementation, you can view my website on [GitHub](https://github.com/joshualande/joshualande.github.io) or leave a question on this post. # Links: Here are some links which helped me along the way: + * The official [Jekyll](http://jekyllrb.com) website, along with detailed [documentation](http://jekyllrb.com/docs/home). * Documentation by GitHub about hosting static webpages with [GitHub pages](http://pages.github.com). * The [poole](https://github.com/poole/poole) GitHub repository. -... +* The GitHub repository for my [personal website](http://github.com/joshualande/joshualande.github.io). diff --git a/assets/demo_poole_website.png b/assets/demo_poole_website.png new file mode 100644 index 000000000..cdf63fe43 Binary files /dev/null and b/assets/demo_poole_website.png differ