Cui Mingda

Cui Mingda

Sep 28, 2020

Publishing Static Website With Jekyll To Github Pages

First, let’s create a new site with Jekyll

jekyll new blog

enter the directory of new blog site and show directory structure

cd blog
tree

The directory structure now is like this

.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2020-09-29-welcome-to-jekyll.markdown
├── about.markdown
└── index.markdown

Without any config, just start the server, then we can preview the website with default url http//127.0.0.1:4000

bundle exec jekyll serve

Now let’s review the directory structure, a new directory called _site was found, that’s compiled results of Jekyll, it is also the directory we will deploy to GitHub Pages later.

.
├── 404.html
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│   └── 2020-09-29-welcome-to-jekyll.markdown
├── _site
│   ├── 404.html
│   ├── about
│   │   └── index.html
│   ├── assets
│   │   ├── main.css
│   │   ├── main.css.map
│   │   └── minima-social-icons.svg
│   ├── feed.xml
│   ├── index.html
│   └── jekyll
│       └── update
│           └── 2020
│               └── 09
│                   └── 29
│                       └── welcome-to-jekyll.html
├── about.markdown
└── index.markdown

Then we need initalization the git repository and commit all

git init
git add .
git commit --message 'init'

We can create a GitHub repository with GitHub CLI and push code to remote

gh repo create blog --public --confirm
git push --set-upstream origin master

GitHub Pages require code to be deployed in the gh-pages branch, not the master branch, certainly we can do it manully, considering that we have to do this operation very frequently, let us install a practical tool to help us to complete

yarn add gh-pages --dev

and create a branch called gh-pages, someone said that you should remove all the files in the branch, actually, this is completely unnecessary, we just need to create a branch.

git checkout --orphan gh-pages

Now we can use one command, push code in _site directory to the gh-pages

npx gh-pages --dist _site

The quickest way to verify is open project homepage on the GitHub, you can see that there are two branch now, and gh-pages branch contains the entire files in the _site directory.

gh repo view --web

Now click the Settings menu, in the GiHub Pages section, select gh-pages in the Branch dropdown list, keep folder as /(root) and Save.

In my example, now you can open website http://cuimingda.github.io/blog, next, you can also set custom domain and check Enforce HTTPS, then the website will be https://mingda.net/blog.

Since it is usually a blog, so we will update frequently, let us add some command to packag.json

"scripts": {
  "deploy": "npx gh-pages -d _site",
  "serve": "bundle exec jekyll serve --drafts",
  "build": "bundle exec jekyll build",
  "view": "open https://mingda.net/blog"
},

Before writing a post, we can run the server by this

yarn serve

After writing a post, we can publish website with these commands

git add .
git commit -m 'add a new post'
git push -u origin master
yarn build
yarn deploy

After all, we can open blog from terminal

yarn view

Conclution

Jekyll is a strong system to build static website, you can write HTML with markdown syntax and Sass, the _site can be easily published on GitHub Pages. We do not need to be limited to the ecosystem of Jekyll and Python, many Node.js tools can let us go fast, such as gh-pages.