YFPR Gets A Blog

Your First Pull Request has a blog! It’s about time too. Now we can all share news and updates about YFPR and awesome guides on being an awesome contributor and maintainer! In this post I am going to explain the basics of writing blog posts for YFPR. Let’s dig in.

One of the most important things you need to know about the blog is where to put posts. Place post files inside the _posts folder. Next is the file name, use the following format: YEAR-MONTH-DAY-title.MARKUP. An example would be this post, 2016-09-29-new-blog.md. The title in the file name is used to create the url slug, i.e. yourfirstpr.github.io/blog/new-blog.html We can set a bigger, better title in the Front Matter.

Jekyll, which runs this site, uses YAML Front Matter to convey information to the site engine. To keep compatibility use the following format for posts:

---
layout: post
title: Your Bigger, Title Cased, Post Title
author: Your Name
author-url: optional url to your twitter or personal site etc
---

A example from this post is:

---
layout: post
title: YFPR Gets A Blog
author: Rob J Loranger
author-url: https://twitter.com/robjloranger
---

Jekyll uses Kramdown flavoured markdown by default. See the preceeding link for more details on how to write in Kramdown. There are also some good examples and more detailed info about Jekyll posts in Jekyll’s docs. The title at the top of a blog post’s page is formatted for us with a size 2 header, <h2> or in Kramdown ##. So to keep things looking good, please only use size 3 and smaller headers in your post.

In the list of blog posts, at yourfirstpr.github.io/blog, we get the title, the post date and an excerpt. This excerpt is automatically generated for us using the first block of text. Which is a paragraph or header. So to provide the most information about a post to browsing users, please start with a short, descriptive paragraph. Alternatively you can specify the excerpt in the YAML Front Matter using this format:

excerpt: Here is a big block of text describing the content of my post

To have multiple line breaks in your custom excerpt use the following:

excerpt: |
  That is one space followed by a pipe character then a new line, all following lines must be indented one level deeper than the 'excerpt:' tag.
  You can create new lines.

  Or even another paragraph using an empty new line as long as it is indented the same.

There is one more way to control the excerpt in Jekyll, which I will let you learn on your own by reading the previously mentioned documentation.

This should be enough to get you started writting posts for Your First Pull Request. Happy coding!

Written by: Rob J Loranger on September 29, 2016