How to Convert GitHub Markdown Files to a Simple Website

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.

You don't need to use the command line or anything other than your browser.
It doesn't require any knowledge in Jekyll.
It's completely compatible with any bunch of markdown files you already have in any existing repository without any modification to those files. That includes the basic README.md almost all repositories contain.
The markdown files will remain just as readable and usable in Github than in your website.

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 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

Any markdown file in your repository will display in your GitHub Pages website. You just have to use the same path to access it and replace the .md extension by .html.

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

To make links between your Markdown files just use a relative path to the other Markdown file. The configuration you copy pasted in your _config.yml provides a plugin to convert those URLs.

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

The index page of your website can be a index.md file or a README.md file. If both exist the index.md file has priority.
You should be able to use any GitHub Flavored Markdown.

Known differences between GitHub and GitHub Pages

There are no automatic links with GitHub Pages. The GitHub Markdown renderer can automatically detect a simple copy-pasted link and make it a clickable link. GitHub Pages doesn't propose a feature to reproduce that behaviour, so you'll have to braces your links with the []()syntax.

How to Convert GitHub Markdown Files to a Simple Website

Comments

Open Source

Introducing GitHub Community Health Files

More from this blog

Using GraphQL for Building Server Driven UIs

Career Update: Joining the Digital Public Goods Alliance

How to Build Design Editing Apps using Nextjs, Clerk, and IMGLY’s CE.SDK Engine

How to Build an Audio Chatbot with Nextjs, OpenAI, and ElevenLabs

How to Create an Automated Profile README using Nodejs and GitHub Actions

Step by step instructions

Usage guide

Known differences between GitHub and GitHub Pages

Command Palette

Comments

Open Source

Introducing GitHub Community Health Files

More from this blog

Step by step instructions

Usage guide

Known differences between GitHub and GitHub Pages