Easy Markdown to GitHub Pages

Introduction

This little guide demonstrates how to turn any Github repository with a bunch of Markdown files into a simple website using Github Pages and Jekyll.

Step by step instructions

Determine the repository where you want to activate GitHub Pages

You can of course create a new repository if you want.

Create the _.config.yml file

That file should be created on the root of your repository. Here is some content to copy-paste in it:

plugins:
  - jekyll-relative-links
relative_links:
  enabled: true
  collections: true
include:
  - CONTRIBUTING.md
  - README.md
  - LICENSE.md
  - COPYING.md
  - CODE_OF_CONDUCT.md
  - CONTRIBUTING.md
  - ISSUE_TEMPLATE.md
  - PULL_REQUEST_TEMPLATE.md

It’s basically just a few tuning of GitHub Pages default configuration to have a better handling of Markdown files.

Activate GitHub Pages in your repository configuration

On the GitHub page of your project go into Settings > Options > Github Pages:

In the Source option, select master branch then Save:

You must also choose a theme:

That’s it! Now you can just use the link provided by GitHub to access you website:

Your site is published at https://bolajiayodeji.github.io/xxxxxx/

Usage guide

So if you want to display your README.md file, you have to enter the URL as README.html

So your Markdown files will have correct links both in GitHub and GitHub Pages.

Known differences between GitHub and GitHub Pages