Set up a site with Github Pages and Jekyll Tutorial

-

 By leveraging Jekyll and Github Pages, you can quickly and easily set up a website for documentation or a simple blog. Jekyll is a static page generator capable of generating just about any data format including HTML. Write pages in markdown and Jekyll will build the HTML pages on your configuration, theme and layouts. By coupling this powerful tool with a Github repository and pages, you now have a powerful way to generic a website.

Getting Started

Before you can use Jekyll to create a website hosted on Github Pages, you’ll need to install some software first. You’ll need to install Jekyll, Ruby, Git, a code editor and Bundle.

It’s recommended to using Bundler to install and run Jekyll. It makes life much easier by managing the Ruby gem dependencies and helps prevent environment issues.

Install Jekyll, Ruby and Bundler

Follow the Jekyl installation guide for your operating system. This includes instructions to intall Ruby, which is the base language used by Jekyll. Don’t worry, you won’t need to need the Ruby programming language.

Install Bundler

Install Git

In order to interface with GitHub, you’ll need to install Git. Git will allow you to make changes to your website and test it locally before committing the changes to your production website. Install it - you’ll learn to use it in a few moments.

Install a code editor

Any editor will work, but it’s recommended to use Visual Studio Code which is available for Windows, Linux and Apple.

Create the project

Using the command line of your operating system, execute these commands to create a new Jekyll project. This will be the location where all your website configuration and source files will be located.

mkdir my-website
cd my-website
jekyll new

If you installed everything correctly, you should be able to execute the command below, then use a web browser to see your newly created website at http://localhost:4000.

bundle exec jekyll serve

Editing the website

Go ahead and start up your code editor and point it at your base websitefolder. If you’re using Visual Studio Code, use File => Open Folder to open it.

Structure

The initial structure for your website is fairly lean - and that’s good! When you browsed to your website earlier, you should have been a single post named Welcome to Jekyll! as well as a link to a page named About. Those files plus more are outlined below. Take a moment to look at these files and folders.

NameTypeDescription
_postsFolderThis folder contains all the weblog posts for your website.
welcome-to-jekyll.markdownFileA default post for reference.
_config.ymlFileThe site configuration file.
.gitignoreFileUsed by git to determine which files it should ignore.
404.htmlFileA default page if someone tries to browse to a page that doesn’t exist.
about.markdownFileA default About page. This file appears in the top-level menu.
GemfileFileContains the ruby gems used by Jekyll.
Gemfile.lockFileContains the ruby gem versions and dependency map.
index.markdownFileThe main page that shows when you browse to the root of your website.

Base Theme: Minima

One thing you may have noticed (or not) is there are no HTML files in the folders, but there’s certainly a layout and structure to your website. That’s because Jekyll set up the project with a default theme named Minima. Look in the _config.yml file and you’ll see a site setting named theme: minima.

You can read more about Minima on Github and see all the layouts and include files it contains. This default theme is minimalistic, but it certainly saves you a ton of time since you don’t have to worry about setting up your own page layout system.

There are hundreds of themes available, but that’s an exercise for another day. Let’s keep moving.

Markdown

Jekyll leverages an easy to learn markup language named Markdown. You can use this cheatsheet to quickly come up to speed on how to make your pages quickly look great.

Git

Now it’s time to create a git repository, add your website files to it and configure it for Github Pages. You must have already installed git to proceed and a Github account.

Github

Login to Github create a new repository. Name your repository whatever you’d like. Make sure you have selected this to be a Public repository – only public repository can use Github Pages. Leave all the other defaults and press Create Repository.

It’s time to create the local repository, add and commit the files and link the local repository to the remote repository on Github. In the git remote add origin command, make sure you replace your actual username & repository name.

echo "# MySite" >> README.md
git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/USERNAME/REPOSITORY-NAME.git
git push -u origin main

After you’ve executed the git add . command, you can use the git status command to get a status of all the files to be commited in the next step.

$ git add .
$ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
	new file:   .gitignore
	new file:   404.html
	new file:   Gemfile
	new file:   Gemfile.lock
	new file:   README.md
	new file:   _config.yml
	new file:   _posts/2023-01-07-welcome-to-jekyll.markdown
	new file:   about.markdown
	new file:   index.markdown

The final command synchronizes your local changes with the remote Github repository. This is sample output of the final command.

$ git push -u origin master
Enumerating objects: 21, done.
Counting objects: 100% (21/21), done.
Delta compression using up to 12 threads
Compressing objects: 100% (20/20), done.
Writing objects: 100% (21/21), 8.52 KiB | 8.52 MiB/s, done.
Total 21 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), done.
To https://github.com/USERNAME/REPOSITORY-NAME.git
 * [new branch]      master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.

Github Pages

It’s time to enable github Pages for your website repository. Open your browser, login to Github and browse to your repository. Go the Settings tab and find Pages on the left-hand column.

The source will be Deploy from a branch. Select the master branch or whatever branch you decided to call yours. Use the /root folder ans press save. Give it 5 minutes or so and browse to your website.

https://USERNAME.github.io/REPOSITORY-NAME

Comments

Post a Comment

Popular posts from this blog

Max Upload File Size in Spring Framework

-
  Spring framework comes preconfigured with default upload file size and max request size. You can modify the sizes with application settings. Settings max-file-size  specifies the maximum size permitted for uploaded files. The default is 1MB max-request-size  specifies the maximum size allowed for multipart/form-data requests. The default is 10MB. Error exceeding max file size Java with Spring 6 will throw a  MaxUploadSizeExceededException  exception when the max size is exceeded. threw exception [ Request processing failed: org . springframework . web . multipart . MaxUploadSizeExceededException : Maximum upload size exceeded ] with root cause org . apache . tomcat . util . http . fileupload . impl . FileSizeLimitExceededException : The field image exceeds its maximum permitted size of 1048576 bytes . at org . apache . tomcat . util . http . fileupload . impl . FileItemStreamImpl $ 1 . raiseError ( FileItemStreamImpl . java : 117 )...
Read more

Use Java Enums with JPA

-
Java Persistence API (JPA) is a widely used standard for object-relational mapping (ORM) in Java applications. One of the common challenges when working with JPA is mapping database columns to Java enums. This can be especially challenging if the database column is not a string, such as when using an integer or a byte as the database column type. In this article, we will explore how to use Java enums with JPA. Mapping Java enums to database columns Before we dive into the details of how to use Java enums with JPA, let's first discuss how JPA maps Java enums to database columns. JPA provides two basic ways to map Java enums to database columns: Ordinal-based mapping : This maps the enum's ordinal value (the position of each enum value in the enum declaration) to the database column. For example, if we have an enum named Status with values ACTIVE, INACTIVE, and SUSPENDED, ACTIVE will have an ordinal value of 0, INACTIVE will have an ordinal value of 1, and so on. Name-based mappi...
Read more

Spring Security part 3 - OidcUser

-
  In the last article, I showed you how to return your own   UserDetails   object via a bean interface for username/password authentication. But what if you want to use OAuth authentication too? Spring Security works differently with OAuth but with a little engineering we can bring it all together into a cohesive solution. Other Articles Architecture -  Spring Security Architecture Part 1 -  Security configuration Part 2 -  How to handle UserDetails gracefully Part 3 -  UserDetails for OAuth authentication Part 4 -  Handling GrantedAuthorities with custom roles/permissions Part 5 -  Security tags for Freemarker If you’re new to Spring, you should take a look at  Getting started with Spring Framework for Web Apps OidcUser You’ve already learned about  UserDetails  but do you know about its cousin [OidcUser](https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/oauth2/core/oidc/user/OidcUser.ht...
Read more