Quickstart Guide

  1. Fork the pulpproject.org repository on GitHub. https://github.com/pulp/pulpproject.org/

  2. Clone your fork locally and checkout the gh-pages branch.

  3. Create a new file in the _posts directory. The name for the file should be in the following format: YYYY-MM-DD-title-of-post.md e.g. 2016-11-30-contributing-blog-post-to-pulpproject.org.md

  4. Write a blog post in the new file.

  5. Commit your changes to the gh-pages branch. By committing directly onto the gh-pages branch, you can preview it using Github.

  6. Push your gh-pages branch to your fork.

  7. Preview the blog at https://<username>.github.io/pulpproject.org/blog/. Another option to preview your blog post (without GitHub) is to build the site locally.

  8. Create a Pull Request against the gh-pages branch of pulproject.org repository.

Writing the Blog Post

Pulpproject.org is a GitHub Pages site. Each page is created using GitHub flavored Markdown. Each blog post begins with the YAML Front Matter. Front Matter specifies metadata such as the author and title. Here is an example of Front Matter for a blog post:

---
title: Django14 Retirement From EPEL 6
author: Brian Bouterse
tags:
  - platform
  - rpm
---

tags may be specified optionally, and the list of available tags is here. Including a tag or multiple tags makes the post discoverable by looking at posts organized by tag. More detailed documentation on creating blog posts is available here.

Previewing the HTML Site on GitHub

Your fork of the pulpproject.org repository should already be configured to serve the gh-pages branch at http://<username>.github.io/pulpproject.org. Once you push your changes to the gh-pages branch, the blog can be viewed at https://<username>.github.io/pulpproject.org/blog/. It may take a few minutes for the pages to be regenerated.

Previewing the HTML Site Locally

Another option for previewing your blog entry is to build it locally. The simplest way to prepare an environment for generating the Jekyll site is to use the Pulp development environment provisioned using Vagrant. The documentation on provisioning using Vagrant can be found in the Pulp developer docs. Once the Vagrant VM is provisioned, connect to it via ssh with the following commend:

vagrant ssh -- -L 4000:127.0.0.1:4000

The above command will forward your local port 4000 to port 4000 on the VM. This will enable you to view the generated site at http://127.0.0.1:4000.

Gotchas

Every time you push the gh-pages branch to GitHub, you will receive an email from GitHub notifying you that the CNAME pulpproject.org is already taken. You can disregard these emails.

If the date in the name of the blog post file is in the future, the generated site will not display the new blog post. While writing the post, you should use the current date in the name of the file.