Creating Blogs with Jekyll

Vikram Dhillon

Creating Blogs with Jekyll

Vikram Dhillon Orlando, Florida, USA

ISBN-13 (pbk): 978-1-4842-1465-7 ISBN-13 (electronic): 978-1-4842-1464-0DOI 10.1007/978-1-4842-1464-0

Library of Congress Control Number: 2016943682

Copyright © 2016 by Vikram Dhillon

This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed. Exempted from this legal reservation are brief excerpts in connection with reviews or scholarly analysis or material supplied specifically for the purpose of being entered and executed on a computer system, for exclusive use by the purchaser of the work. Duplication of this publication or parts thereof is permitted only under the provisions of the Copyright Law of the Publisher’s location, in its current version, and permission for use must always be obtained from Springer. Permissions for use may be obtained through RightsLink at the Copyright Clearance Center. Violations are liable to prosecution under the respective Copyright Law.

Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.

The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights.

While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein.

Managing Director: Welmoed SpahrAcquisitions Editor: Ben-Renow ClarkeDevelopment Editor: Matthew MoodieTechnical Reviewer: Massimo NardoneEditorial Board: Steve Anglin, Pramila Balen, Louise Corrigan, James DeWolf, Jonathan Gennick,

Robert Hutchinson, Celestin Suresh John, Nikhil Karkal, James Markham, Susan McDermott, Matthew Moodie, Ben Renow-Clarke, Gwenan Spearing

Coordinating Editor: Nancy ChenCopy Editor: Teresa HortonCompositor: SPi GlobalIndexer: SPi Global

Distributed to the book trade worldwide by Springer Science+Business Media New York, 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail orders-ny@springer-sbm.com , or visit www.springer.com . Apress Media, LLC is a California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation.

For information on translations, please e-mail rights@apress.com , or visit www.apress.com .

Apress and friends of ED books may be purchased in bulk for academic, corporate, or promotional use. eBook versions and licenses are also available for most titles. For more information, reference our Special Bulk Sales–eBook Licensing web page at www.apress.com/bulk-sales .

Any source code or other supplementary materials referenced by the author in this text is available to readers at www.apress.com . For detailed information about how to locate your book’s source code, go to www.apress.com/source-code/ .

Printed on acid-free paper

To the pioneers of the Internet: I wrote this book as requiem to you. Hear it sing, for your work has brought freedom to the world.

To Clara, for the tremendous mental support which kept me doing. It should be noted that she helped me rethink about a lot of the

topics in the book, please direct complaints accordingly.

But most of all, I dedicate this book to you, the reader, because without you, my work would have no meaning.

v

Contents at a Glance

About the Author .....................................................................................................xv

About the Technical Reviewer ...............................................................................xvii

Acknowledgments ..................................................................................................xix

Introduction ............................................................................................................xxi

■Part I: History and Development ......................................................... 1

■Chapter 1: Static Web ............................................................................................ 3

■Chapter 2: Web 2.0 .............................................................................................. 11

■Chapter 3: Static Site Generators ........................................................................ 21

■Part II: The Fundamentals ................................................................ 35

■Chapter 4: Fundamentals of Version Control ....................................................... 37

■Chapter 5: Fundamentals of Style ....................................................................... 51

■Chapter 6: Fundamentals of Jekyll ...................................................................... 73

■Part III: Projects ................................................................................ 89

■Chapter 7: Blog-awareness ................................................................................. 91

■Chapter 8: Git It Done ........................................................................................ 107

■Chapter 9: Photo Blogging ................................................................................. 137

■Chapter 10: Open Debates ................................................................................. 163

■Chapter 11: Open Research ............................................................................... 195

■ CONTENTS AT A GLANCE

vi

■Chapter 12: Open Health Care............................................................................ 229

■Chapter 13: Open Jekyll? .................................................................................. 265

■Appendix ............................................................................................................ 335

Index ..................................................................................................................... 339

vii

Contents

About the Author .....................................................................................................xv

About the Technical Reviewer ...............................................................................xvii

Acknowledgments ..................................................................................................xix

Introduction ............................................................................................................xxi

■Part I: History and Development ......................................................... 1

■Chapter 1: Static Web ............................................................................................ 3

Here Be Dragons .............................................................................................................. 3

Commercial Internet: CERN .............................................................................................. 6

Summary .......................................................................................................................... 8

Further Reading ................................................................................................................ 8

■Chapter 2: Web 2.0 .............................................................................................. 11

Early Web Browsers ....................................................................................................... 11

Defi ning Web 2.0 ............................................................................................................ 12

Boom and Bust ............................................................................................................... 15

Connecting the Dots ....................................................................................................... 17

Summary ........................................................................................................................ 19

Further Reading .............................................................................................................. 19

■Chapter 3: Static Site Generators ........................................................................ 21

The Maturing Web .......................................................................................................... 21

Blogging in Web 2.0 .............................................................................................................................. 22

Looking Back ........................................................................................................................................ 23

Components of a Static Generator ........................................................................................................ 24

■ CONTENTS

viii

Static Generators Showcase .......................................................................................... 26

Jekyll .................................................................................................................................................... 26

Octopress.............................................................................................................................................. 26

Hexo ...................................................................................................................................................... 27

Pelican .................................................................................................................................................. 28

Hugo ..................................................................................................................................................... 28

Brunch .................................................................................................................................................. 29

Middleman ............................................................................................................................................ 30

Metalsmith ............................................................................................................................................ 31

Nanoc ................................................................................................................................................... 31

Summary ........................................................................................................................ 32

Further Reading .............................................................................................................. 33

■Part II: The Fundamentals ................................................................ 35

■Chapter 4: Fundamentals of Version Control ....................................................... 37

Parsing Engine ............................................................................................................... 37

Markdown ...................................................................................................................... 38

Version Control ............................................................................................................... 43

Installing Git ................................................................................................................... 47

Jekyll Workfl ow .............................................................................................................. 48

Summary ........................................................................................................................ 48

Further Reading .............................................................................................................. 49

■Chapter 5: Fundamentals of Style ....................................................................... 51

What Is Style? ................................................................................................................ 51

Bootstrap ........................................................................................................................ 54

Foundation ..................................................................................................................... 59

Style Sheet Management: Sass ...................................................................................... 62

Style Sheet Management: LESS ..................................................................................... 65

■ CONTENTS

ix

Jekyll Themes ................................................................................................................ 67

Summary ........................................................................................................................ 70

Further Reading .............................................................................................................. 71

■Chapter 6: Fundamentals of Jekyll ...................................................................... 73

Folders ........................................................................................................................... 73

Drafts and confi g .................................................................................................................................. 74

Includes ................................................................................................................................................ 74

Layouts ................................................................................................................................................. 75

Posts, data, and site ............................................................................................................................. 76

YAML .............................................................................................................................. 77

Liquid and Handlebars ................................................................................................... 80

Tags ...................................................................................................................................................... 80

Objects .................................................................................................................................................. 82

Inheritance ..................................................................................................................... 84

Installing Jekyll Locally? ................................................................................................ 85

Summary ........................................................................................................................ 86

Further Reading .............................................................................................................. 86

■Part III: Projects ................................................................................ 89

■Chapter 7: Blog-awareness ................................................................................. 91

Getting the Theme .......................................................................................................... 91

Installing a Code Editor .................................................................................................. 93

A Kactus in the Desert .................................................................................................... 94

The _includes Folder ............................................................................................................................ 95

The _layouts Folder ............................................................................................................................ 100

The _posts Folder ............................................................................................................................... 103

Summary ...................................................................................................................... 104

Further Reading ............................................................................................................ 105

■ CONTENTS

x

■Chapter 8: Git It Done ........................................................................................ 107

Scope and Scale ........................................................................................................... 107

Tools List ...................................................................................................................... 111

Just Do It ...................................................................................................................... 112

Font-Awesome ................................................................................................................................... 116

Navigation ........................................................................................................................................... 118

Page Profi le ........................................................................................................................................ 120

Pagination ........................................................................................................................................... 120

Post List .............................................................................................................................................. 121

Share Buttons ..................................................................................................................................... 123

Archive ................................................................................................................................................ 125

Comments .......................................................................................................................................... 127

MailChimp ........................................................................................................................................... 129

Cleaning Up ........................................................................................................................................ 132

Summary ...................................................................................................................... 135

Further Reading ............................................................................................................ 136

■Chapter 9: Photo Blogging ................................................................................. 137

Project Specifi cation .................................................................................................... 138

Using GitHub ................................................................................................................. 141

Deleting Repositories.......................................................................................................................... 142

Visual Tutorial ..................................................................................................................................... 143

Dope Editing ................................................................................................................. 144

Navigation Bar .................................................................................................................................... 145

Photography Specialties ..................................................................................................................... 146

Portfolio .............................................................................................................................................. 147

The Blog .............................................................................................................................................. 148

Footer ................................................................................................................................................. 149

Blog Post Layout ................................................................................................................................. 151

Embedding Photography .................................................................................................................... 153

■ CONTENTS

xi

Content Delivery Network (CDN) .................................................................................. 155

MailChimp Campaign ................................................................................................... 156

Summary ...................................................................................................................... 161

Further Reading ............................................................................................................ 161

■Chapter 10: Open Debates ................................................................................. 163

Rules of the Game ........................................................................................................ 163

Navigating GitHub ......................................................................................................... 165

Repository Overview ........................................................................................................................... 166

Issues ................................................................................................................................................. 166

Pull Requests ...................................................................................................................................... 168

Wiki ..................................................................................................................................................... 168

Pulse and Graphs ................................................................................................................................ 169

GitHub Pages ...................................................................................................................................... 171

Prototyping ................................................................................................................... 174

Jekyll Collections ......................................................................................................... 176

Theming the Debate ..................................................................................................... 177

Phases .......................................................................................................................... 183

Summary ...................................................................................................................... 193

Further Reading ............................................................................................................ 193

■Chapter 11: Open Research ............................................................................... 195

A New Platform ............................................................................................................ 195

KaTeX .................................................................................................................................................. 196

Plot.ly .................................................................................................................................................. 197

IPython ................................................................................................................................................ 198

Reveal.js ............................................................................................................................................. 199

Planning the Theme ............................................................................................................................ 200

Exploring Git ................................................................................................................. 202

Git Internals ........................................................................................................................................ 204

Distributed Development Model ......................................................................................................... 207

■ CONTENTS

xii

Let’s Git Coding ............................................................................................................ 211

Writing Equations ............................................................................................................................... 215

Adding a Graph ................................................................................................................................... 218

Writing Bibliographies ........................................................................................................................ 219

Adding Notebooks .............................................................................................................................. 222

Making Presentations ......................................................................................................................... 223

Summary ...................................................................................................................... 226

Further Reading ............................................................................................................ 226

■Chapter 12: Open Health Care............................................................................ 229

Overview ...................................................................................................................... 229

Introduction to Cards .................................................................................................... 231

Creating Cards .................................................................................................................................... 232

Writing a Quote Card .......................................................................................................................... 237

Content Guide ............................................................................................................... 238

Writing in Prose ............................................................................................................ 240

Prosing Through ................................................................................................................................. 241

Material Design ............................................................................................................ 247

Summary ...................................................................................................................... 262

Further Reading ............................................................................................................ 263

■Chapter 13: Open Jekyll? .................................................................................. 265

Now Open: Jekyll Design Studio ................................................................................... 267

A Ruby from Japan ....................................................................................................... 269

Playing with Ruby ............................................................................................................................... 273

Gems of Ruby ..................................................................................................................................... 284

A Bucket of Gems ............................................................................................................................... 290

Build Tools .................................................................................................................... 301

Continuous Integration ................................................................................................. 303

■ CONTENTS

xiii

Solid Studio .................................................................................................................. 313

Fiverr and Gumroad ............................................................................................................................ 313

YouTube and Wistia ............................................................................................................................. 317

Shopping Cart ..................................................................................................................................... 319

Prototyping in InVision ........................................................................................................................ 322

Customer Support ............................................................................................................................... 323

Deployment and Custom Builds .......................................................................................................... 325

Further Reading ............................................................................................................ 333

■Appendix ............................................................................................................ 335

Custom Domain for a Root Repository ......................................................................... 335

Custom Domain for a Project Page? ............................................................................. 336

Confi guring Jekyll-Powered Project Pages .................................................................. 338

Domain Directory ......................................................................................................... 338

Index ..................................................................................................................... 339

xv

About the Author

Vikram Dhillon is currently a research fellow in the Institute of Simulation and Training at University of Central Florida. He holds a Bachelor of Science degree in Molecular Biology from the University of Central Florida, where his main focus was bioinformatics. He has published a few scientific papers on computational genomics. He has worked as a software and business development coach at the Blackstone Launchpad to mentor young entrepreneurs and startups through the process of building technology products. He was previously funded by the National Science Foundation through the Innovation Corps program to study customer discovery and apply it to commercialize high-risk startup ideas. He is a member of the Linux Foundation and has been very involved in open source projects and initiatives for the past several years. He often speaks at local conferences and meetups about programming, design, security, and entrepreneurship. He currently lives in Orlando and writes a technology-focused blog at opsbug.com .

xvii

About the Technical Reviewer

Massimo Nardone holds a Master of Science degree in Computing Science from the University of Salerno, Italy. He has worked as a Project Manager, Software Engineer, Research Engineer, Chief Security Architect, Information Security Manager, PCI/SCADA Auditor, and Senior Lead IT Security/Cloud/SCADA Architect for many years. He currently works as Chief Information Security Office for Cargotec Oyj. He has more than 22 years of work experience in IT including security, SCADA, cloud computing, IT infrastructure, mobile, security, and Web technology areas for both national and international projects. He worked as visiting lecturer and supervisor for exercises at the Networking Laboratory of the Helsinki University of Technology (Aalto University). He has been programming and teaching how to program with Android, Perl, PHP, Java, VB, Python, C/C++, and MySQL for more than 20 years. He holds four international patents (PKI, SIP, SAML, and Proxy areas). He is also the co-author of Pro Android Games (Apress, 2015).

xix

Acknowledgments

I want to acknowledge my editors, Ben, Mark, and Nancy, who guided me through every stage of this book. Their patience and advice helped tremendously in shaping this book.

I want to thank Zachary Loparo for helpful discussions about the projects included in this book and the overall direction.

I would like to thank Anthony Nguyen for opuning up to me and showing me the the world of puns.

Finally, I want to thank Katelyn Rae MacKenzie for organizing those Ruby Meetups at Cloudspace. Without that first meetup, this book might never have happened. Thank you for all the hard work that you do!

xxi

Introduction

This book is more than just a standard text on Jekyll. Anyone who tries to learn about Jekyll is faced with instructions on how to set up a blog in 10 minutes and confounded with commands to type on the terminal. What has been missing is a thorough introduction to the landscape surrounding Jekyll as a static site generator: Where did the idea for Jekyll come from? Why did it become relevant? How can Jekyll integrate new web technologies and tools to create functional and stylish web sites?

This book answers those questions in a practical manner, and provides a theoritical framework to transfer that “Jekyll thinking” to your own personal projects. A tool like Jekyll is very versatile, but you have to think creatively to apply it toward a problem that you are trying to solve. Most problems don’t lend themselves to easy solutions, but we will apply Jekyll features toward creating custom blogs. Sometimes, just reformulating the problem leads to better solutions.

This book is organized as follows. The content material has been divided into three distinct sections, with each one focusing on a specific theme or set of questions. The first section is about the development of static generators like Jekyll and how the Internet got started. It was a much different time then, and the economic factors shaped what the Internet was capable of doing. The dot-com bust was one of the most important financial crises, and it had a lasting impact on society. For the Internet to survive and make it through, many changes were required, and a complete technical overhaul enabled exactly that. This section answers the question of how Jekyll came about.

The second section of this book dives into the fundamental tools required to use Jekyll appropriately. You can think of Jekyll essentially as a collection of technologies that work together to create a static site. To begin working with Jekyll regularly, you’ll have to learn how to use these prerequisite tools. After covering these fundamentals, we are ready to start creating projects with Jekyll. This section answers the question of what makes Jekyll work.

The last section covers a variety of projects in which Jekyll is applied to create a static web site for solving problems. These project ideas include casual or hobby web sites as well as more serious ones that have a particular social inclination. The story behind a project mostly serves as a way to demonstrate the application of Jekyll and related web technologies to an existing problem. The chapters actually build up and slowly increase in complexity and application, leading up to the boss-level last chapter. This section answers the question of how Jekyll can incorporate new web technologies as exciting features into a new personal blog. As you go through this section, I hope that you obtain practical advice as well as potential inspiration for your own projects.

Stay Hungry. Stay Foolish. Keep doing more, and write about it using Jekyll. Good luck!