Jekyll+Github Pages=Blog

Contents

Preparation
Setup
- Github pages
- Jekyll (local)
Operations
Other Tips
Some Issues
Cheat Sheet

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

Github > New Repository
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)

Ruby
RubyGems
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 s and 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/

page: 404.md, about.md
post-index: index.html, tags/index.html, posts/index.html
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.