Jekyll+Github Pages=Blog

Reading time ~13 minutes



Git | Github
Ruby | Gem, Bundle…
Jekyll | Markdown, Liquid, Rouge, YAML
Optional: RVM, Disqus, Google Search Console…

As follows, I’m trying to explain in the briefest way. It’s also good to get more detailed understandings here. Though written in English, links here I attach are almost Chinese (for better understandings).


Github pages

  1. Github > New Repository
  2. Repo > Settings > GitHub Pages > Source: the branch that your site built from.

    • Your site is published at https://[username][Repo_name]/

Jekyll (local)

  1. Ruby
  2. RubyGems
  3. Jekyll
gem install jekyll


Construct your site (code)

  • Completely by yourself. Reference: Jekyll Structure

      git init
  • A template may help a lot, e.g., Jekyll Themes

      git clone <> <folder>
      cd <folder>
      rm -rf .git
      git init

Update your contents

git add (-A)
git commit -m <annotation>

Test your blog locally

bundle exec jekyll serve
optinal: --watch, --drafts

Publish your blog / posts*

git remote add origin<...>.git
git push -u origin <local branch>:<remote branch> (-f)

* A good editor may help a lot, e.g., VS Code :-)

Other Tips


A lightweight markup language.
Syntax(CN DOC):


An template language written in Ruby.
Syntax(CN DOC):

Hilighter (for jekyll)

  • Rouge

      List of supported languages and lexers:

Some Issues

.gitignore file doesn’t work

  • Only ignore untracked files. Solution: delte all caches and commit then.

      git rm -r --cached .
      git add .
      git commit -m 'update .gitignore'

“Page Build Failure” from Github

  • Your plugins won’t work if you’re deploying to GitHub Pages.
  • To test locally, make sure you’re using the GitHub Pages gem in your Gemfile and not Jekyll.

      gem "github-pages", group: :jekyll_plugins

Emoji on GitHub Pages

  • Add the plugin in _config.yml:

          - jemoji
  • To test locally, (delete Gemfile.lock), edit Gemfile, (run ‘bundle update’):

      gem 'gemoji'
  • Example: it’s raining :cat:s and :dog:s! See EMOJI CHEAT SHEET for more.

Kramdown: Inser Markdown into HTML

  • If an HTML tag has an attribute markdown=”1”, then the default mechanism for parsing syntax in this tag is used.

      <div markdown="1">
      My text with **markdown** syntax

Liquid code can’t be displayed normally

  • {% raw %}{% endraw %}: temporarily disables tag processing

Just for my own blog. So skip this part as you like.

Cheat Sheet

Posts (YAML)



  1. page:,
  2. post-index: index.html, tags/index.html, posts/index.html
  3. post: _posts/[xx-xx-xx]-[title].md


feature: inner background for the head._layouts/posts.html

  • credit, credit-link: Image source

entry: shown on the index page.index.html

To add additional links in the drop down menu edit _data/navigation.yml. (External links will open in a new window.)

Truncate (Liquid) (use excerpts instead)

index.html: To abstract each post, add

{{ post.content | truncatewords:150 }}

Post excerpts

  • use excerpt variable on a post (default: the first paragraph of content).
  • customized by setting a excerpt_separator variable in YAML front-matter or _config.yml.
      excerpt_separator: <!--
      <!--

Support MathJax

_layouts/post.html: Add script in <head>

<script type="text/javascript" async

Test here:

质能方程 \(E = mc^2\)

More usages here.


Published on January 01, 2022


Published on November 29, 2021