Read Me

Introduction

This repository is meant to help create a quick start / Hello world version of a website using Jekyll and Markdown as a way of creating a website from plain text.

This page covers developer instructions to work with this repository.

Usage Pre-Requisites

This repository is meant to be a template repository for a Blog or a Website and uses Jekyll to transform markdown files into HTML. It has necessary setup to be deployed on to GitHub pages.

If you simply want to publish files using the default theme and markdown files and are happy to let Github pages do the publishing then the is not much to do just learn a little bit about Jekyll site structure and start creating posts inside the _posts directory. There is a getting started post already included there. You can start by editing that post.

A more detailed usage guide coming soon.

Developer Guide

For developers or programmers who want to have fine grained control over the site here are the steps.

If you want to edit and preview files on local machine then some set up is needed.

• ruby, gcc and make Installation: Latest stable Ruby version is recommended. Jekyll documentation provides up to date OS specific install guides
• Jekyll CLI setup: Once pre-requisites are installed we need the jekyll and bundle command line interface (CLI) tools. Again Jekyll documentation provides a quick start guide
• GitHub repository from Template: Create a new repository using this repository as a template with Github templates.
• Clone GitHub repository: Clone the newly created GitHub repository and start editing the project files using your favourite editor.
• Ensure all Ruby Gem dependencies are installed

  bundle install
  

• Jekyll local server: Running the site on local machine requires running the local server from the root directory of the newly created project.

  bundle exec jekyll serve
  

  Customization

  After creating a new repository there are some very simple and basic customization steps to be done and then the newly created GitHub repository would be ready to use as a blog or website.

• Configuration: Jekyll offers a lot of finegrained configuration options. The file _config.yml in the root folder has the bare bones configuration in place.
• Name Changes: A few changes are of course in order. In the _config.yml Modify the fields title, description, baseurl, url and github_username to make the site your own.
• Theme: The _config.yml file has a simple responsive theme set up already "alembic-jekyll-theme". It is a simple theme with features including configurable colours, pagination, search, post categories and more. The documentation page has a lot of information. However, if this is not to your liking consider using a different theme. Jekyll community has a lot of themes available for use.

Deployment

This template is meant to be a quick start for creating a website using Jekyll and Markdown. It includes ready GitHub Action for deploying to GitHub Pages using Jekyll. The file is jekyll.yml under .github/workflows is ready to use for deployments. All that is left is to set up GitHub pages deployment using this file as the configuration file for the GitHub deployment action.

TO DO

• Set up Jekyll Website project
• Set up GitHub Pages publishing Action
• Set up custom theme for Jekyll
• Set up site as a Jekyll Site starter template
• Improve read me file for real technical users.
• Create a “5 minute Quickstart - Jekyll for dummies” blog for non technical users