visuals + news appsHello world: Nerd blogging with Jekyll
Updated June 12, 2014 by Helga Salinas
We’re a new team, and we’re trying something new (at least for us) as a blog publishing platform: Jekyll, a generator that creates simple, static websites. We’re not breaking any ground with this choice, of course, but we liked the idea of launching a blog that’s open source – both its code and also its content.
This initial post is an introduction to Jekyll for the members of our team – and anyone else who wants to get started with the tool and/or steal our simple code for their own site.
###Getting started
Jekyll eliminates the need for a traditional content management system, like WordPress. Instead, we’re creating plain-old HTML pages and serving them from GitHub Pages, where we host our blog code.
To get started, install the Ruby gem with these instructions.
Next, familiarize yourself with the usage and configuration documentation provided by Jekyll. There’s more detail in there about further customizing a site, which we’ll do over time (what we have now is super basic).
As you’ll see, Jekyll uses your source directory templates and converts your Markdown text and Liquid tags to build a static website. The website – and any posts you create – then get published with a git push to GitHub.
###Our configuration
Our templates are built from scratch on top of the Twitter Bootstrap framework, giving us responsive pages that we’ve customized for Jekyll. Your source directory should like something this:
.
|-- _config.yml
|-- _includes
|-- _layouts
| |-- default.html
| `-- post.html
|-- _posts
| |-- 2012-11-08-npr-news-apps-blog.markdown
|-- _site
|-- about
| |-- index.html
|-- bootstrap
`-- CNAME
|-- css
|-- img
`-- index.html
`-- README.md
This structure is explained in the usage documentation, but here are the highlights. Never mind _includes for now. The _layout folder has the templates. We will inject posts into them with the {{ content }} Liquid tag. The _posts folder contains, well, posts. Notice the structure of the file names. The date and title are used for the default permalinks structure, and they also define the post date. The _site folder contains the site generated when you run Jekyll.
###Adding content
Below is the Markdown of this post:
The YAML Front Matter at the top determines which layout file is used (in this case a post) as well as the title, description and author. You can add more information here, like categories and tags, for example, but we haven’t built out those features yet. Also notice that these files use Markdown that Jekyll will churn out as HTML later.
Below is the HTML of the index.html file, which is the {{ content }} we inject into the default.html template for displaying the home page:
Above YAML Front Matter selects the default.html template and defines the title element. We’re creating a reverse chronological list of stories, with headlines, dates, author names, and descriptions (here limited to the four most recent posts).
We add headlines linking to the corresponding posts with {{ post.url }} and {{ post.title }} Liquid output markup. We do the same with the date, and we’ve defined the display format using Liquid’s filter syntax. (As we add posts to the _posts directory, and git push them, more will display on the live home page). Notice the “#disqus_thread” attached to the post URL. That gives us a comment count.
Below is the HTML for the post.html template. Posts also get injected into the default.html template, but obviously with a deferent design. It too use Liquid output markup to get content onto the static page when Jekyll runs:
###Publishing to GitHub
We’ve created a GitHub repo called “nprapps.github.com” (btw: see documentation for publishing to a custom domain here).
Inside that directory on your local machine, run jekyll. That will build the site. As you edit, the site will be automatically rebuilt, a process you’ll notice in the Terminal. To run the site locally, execute jekyll --server watch, then point your browser to localhost:4000.
When you’re satisfied with your post, commit the code and use git push to publish. The site will be updated online soon after.
Thanks to our former interns, Angela Wong and Kevin Uhrmacher, for designing the site.
