Jekyll+Github Pages=Blog

Reading time ~13 minutes

Contents

Preparation

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

Setup

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].github.io/[Repo_name]/

Jekyll (local)

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

Operations

Construct your site (code)

  • Completely by yourself. Reference: Jekyll Structure

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

      git clone <https://github.com/...> <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@github.com:<...>.git
git push -u origin <local branch>:<remote branch> (-f)

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

Other Tips

Markdown

A lightweight markup language.
Syntax(CN DOC): https://markdown-zh.readthedocs.io/en/latest/

Liquid

An template language written in Ruby.
Syntax(CN DOC): https://liquid.bootcss.com/

Hilighter (for jekyll)

  • Rouge

      List of supported languages and lexers:
      https://github.com/jneen/rouge/wiki/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:

      plugins:
          - 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
      </div>
    

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)

Layout

_layouts/

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

Image

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: <!--read more-->
      ---
    
      Excerpt
      <!--read more-->
      Out-of-excerpt
    

Support MathJax

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

<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

Test here:

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

More usages here.

SHAP源码之GradientExplainer

Published on January 01, 2022

可解释方法LIME和SHAP代码实战

Published on November 29, 2021