Ducumentation

Github: Renovamen/jekyll-theme-gungnir

Derived from Huxpro/huxpro.github.io. Some of the designs and code are borrowed from other themes, including but not limited to mashirozx/Sakura, kitian616/jekyll-TeXt-theme, Fechin/hexo-theme-diaspora, liuzc/LeaveIt, et al.

Gungnir is the spear of the god Odin in Norse mythology, made from the wood of the world tree Yggdrasil. It has nothing to do with this theme, but I still use this name.

Installation

Clone the project from Github:

git clone https://github.com/Renovamen/jekyll-theme-gungnir.git
cd jekyll-theme-gungnir

To run the theme locally, Ruby and Jekyll should be installed firstly, refer to here for details. Then you could install the dependencies:

bundle config set path 'vendor/bundle'
bundle install

Then you could start the development server and preview the blog by:

bundle exec jekyll serve --watch

To modify the source code of the theme, you may need to install Grunt (for compressing js files):

npm install

Then:

npm run dev

Configuration

All the following options should be configured in _config.yml.

Site Settings

title: Renovamen # title of your site
SEOTitle: Renovamen's blog # SEO title of your site
description: Hmm, interesting blog. # description of your site
keyword: "blog, personal website" # keywords of your site
url: "https://renovamen.ink" # URL of your site
baseurl: "" # Base URL of your site. If you site is hosted on 'https://renovamen.ink/blog', it should be '/blog'
avatar: "img/header-avatar.jpeg" # path of the avatar showing on home page

Theme Style

theme_style: 
  highlight:  # syntax highlighting theme
  alert:  # style of alerts
  post_preview: # style of the post list showing on home page

Highlight

Highlight.js instead of Rouge is used as syntax highlighter. The default syntax highlighting theme of this blog looks like this:

import food

class Dragon:
    def __init__(self, happiness):
        self.happiness = happiness
    def code(self):
        """ just code """
        self.happiness -= 60
    def eat(self, n)
        # just eat
        self.happiness += n * food.size

me = Dragon(100)

while True:
    me.code()
    me.eat(10)

Click the span in the upper-right corner to make the code block full screen.

The default highlighting theme is dark, you can also switch it to light:

highlight: # "dark" (default), "light"

Highlighting stylesheets could be found here. You can also modify them to create your own theme, or just import the stylesheets provided by Highlight.js.

Alert

Showing alerts in articles is supported, refer to here for more information about the usages. You can specify the style of alerts:

alert:  # "flat" (default), "modern"

The default style is flat, like this. modern style alerts look like this：

Post List

image (default) means showing featured image of each article on home page, while text means showing text only:

post_preview: # "image" (default), "text"

image：

text：

Social Network

sns:
  github_username: # Github
  weibo_username: # Weibo
  zhihu_username: # Zhihu
  twitter_username: # Twitter
  facebook_username: # Facebook
  linkedin_username:  # Linkedin
  email_address: # Email Address

Links of your social networks will be shown on home page and about page.

Navigation

Configuration of the first level menu is like this:

menus:
  - title: Home
    font: fab fa-fort-awesome
    url: /
  - title: Archive
    font: fas fa-archive
    url: /archive/

You should specify the name, URL and icon of each page. Font Awesome is used as icon set, you can search for icons here.

Use key submenus to add the second level menu:

menus:
  - title: About
    font: fas fa-paw
    submenus:
      - title: Me
        font: fas fa-user-astronaut
        url: /about/
      - title: Theme
        font: fas fa-meteor
        url: /theme/

Comment

comment: 
  provider: # false (default), "disqus", "gitalk", "valine"

Disqus, Gitalk and Valine are supported as third party comment systems. You should specify the name of your prefer comment system or use false to disable comments.

Disqus

Apply for a shortname on Disqus, then:

comment: 
  provider: disqus
  disqus_username: # Disqus shortname

Gitalk

Register a Github Application and get the Client ID and Client Secret, then:

comment: 
  provider: gitalk
  gitalk:
    clientID: # Github Application Client ID
    clientSecret: # Github Application Client Secret
    repo: # Github repo for storing comments
    owner: # owners of the above mentioned repo
    admin: 
      - admin1
      - admin2
      - ...

Refer to the documentation of Gitalk for more information.

Valine

Create a new application on Leancloud and get the APP ID and APP Key, then:

comment: 
  provider: valine
  valine:
    appID: # LeanCloud App ID
    appKey: # LeanCloud App Key

Refer to the documentation of Valine for more information.

Analytics

Google Analytics and Baidu Tongji are supported as the site analytics tools.

Baidu Tongji

Paste the code offered by Baidu Tongji here:

analytics:
  ba_track_id: # your tracking code

Google Analytics

Paste the code offered by Google Analytics here:

analytics:
  ga_track_id: 'G-ZYM02DSEHS' # your tracking code

CDN

cdn: # "jsdelivr" (default), "bootcdn", "unpkg", "cdnjs"

jsDelivr is used as the default CDN provider. You can also choose BootCDN, unpkg or cdnjs to be your CDN provider. All CDN URLs can be found in _data/cdn.yml.

Additional Functions for Markdown

math: 
    enable: # if to enable math rendering for all articles
            # false (default), true
    engine: # specify the math rendering engine
            # "katex" (default), "mathjax"
chart: # if to enable Chart.js: false (defaule), true
mermaid: # if to enable mermaid: false (default), true
emoji-plus: # if to enable additional emoji: false (default), true

Refer to here for more information.

Hitokoto

hitokoto: true # default: false

Set hitokoto to true to enable the Hitokoto bubble on home page. The bubble will appear when you hover your mouse cursor over the avatar:

Page

Home

Switching among multiple cover images is supported. The path and the RGB value of the mask of each cover image should be specified in the Front-matter of index.html:

description: # the sentence you want to show on the home page
header-img:
    -   url: # path of the cover image1
        mask: # RGB value of the mask of the cover image1 (optional), like: rgba(40, 57, 101, .4)
    -   url: # path of the cover image2
        mask: # RGB value of the mask of the cover image2 (optional)

The mask is the translucent overlay placed on the cover image. It will be helpful when your cover image is so complex that your title can not stand out.

About

Just refer to the About page and its Front-matter of this site.

Links

Just refer to the Links page and its Front-matter of this site. (Repeat *1)

If any of the links’ avatar is not specified, img/links/default.jpg will be shown as the default avatar.

If you want to enable comments in this page, you should enable comments in _config.yml and set comment: true in the Front-matter of this page.

Content

Post

Create your posts (Markdown files) under _posts/ directory. The format of their filename should be year-month-day-title.md. Their YAML Front-matter should be like this：

---
layout: post
title: # title
subtitle: # subtitle
author: # author's name, defaults to the site's title
header-img: # path of the cover image
header-mask: # RGB value of the mask of the cover image, like: rgba(40, 57, 101, .4)
header-style: text # add this line if you don't want a cover image
catalog: # if to enable catalog: false (default), true
math: # if to enable math rendering
tags: # tags
  - tag1
  - tag2
  - ...
---

It should be noted that, header-img will be shown on both home page and post page. Refer to here for the information about the configuration of math.

Additional Functions for Markdown

Math Rendering

Mathjax and Katex are supported for rendering mathematical formulas in articles.

Katex is faster than Mathjax (check it out here), but the number of Tex functions it supports is less than Mathjax (here is all functions supported by Katex).

Math rendering will only be enabled for the articles with math: true in their Front-matter when math.enable: false is set in _config.yml:

---
layout: post
math: true
---

Otherwise, this function will be enabled for all articles (including post and keynote).

Example：

Inline math: $ E = mc^2 $

Display math:

$ E = mc^2 $

$$
i \hbar \frac{\partial \psi}{\partial t}
= \frac{-\hbar^2}{2m} ( \frac{\partial^2}{\partial x^2} + \frac{\partial^2}{\partial y^2} + \frac{\partial^2}{\partial z^2} ) \psi + V \psi
$$

Chart and Diagram

Chart (Chart.js)

Chart.js is used to create interactive charts in articles. Refer to the documentation of Chart.js for the methods of creating charts.

Example：

{
    "type": "bar",
    "data": {
        "labels": ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
        "datasets": [{
            "label": "# of Votes",
            "data": [12, 19, 3, 5, 2, 3],
            "backgroundColor": [
                "rgba(255, 99, 132, 0.2)",
                "rgba(54, 162, 235, 0.2)",
                "rgba(255, 206, 86, 0.2)",
                "rgba(75, 192, 192, 0.2)",
                "rgba(153, 102, 255, 0.2)",
                "rgba(255, 159, 64, 0.2)"
            ],
            "borderColor": [
                "rgba(255, 99, 132, 1)",
                "rgba(54, 162, 235, 1)",
                "rgba(255, 206, 86, 1)",
                "rgba(75, 192, 192, 1)",
                "rgba(153, 102, 255, 1)",
                "rgba(255, 159, 64, 1)"
            ],
            "borderWidth": 1
        }]
    },
    "options": {
        "scales": {
            "yAxes": [{
                "ticks": {
                    "beginAtZero": true
                }
            }]
        }
    }
}

```chart
{
    "type": "bar",
    "data": {
        "labels": ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
        "datasets": [{
            "label": "# of Votes",
            "data": [12, 19, 3, 5, 2, 3],
            "backgroundColor": [
                "rgba(255, 99, 132, 0.2)",
                "rgba(54, 162, 235, 0.2)",
                "rgba(255, 206, 86, 0.2)",
                "rgba(75, 192, 192, 0.2)",
                "rgba(153, 102, 255, 0.2)",
                "rgba(255, 159, 64, 0.2)"
            ],
            "borderColor": [
                "rgba(255, 99, 132, 1)",
                "rgba(54, 162, 235, 1)",
                "rgba(255, 206, 86, 1)",
                "rgba(75, 192, 192, 1)",
                "rgba(153, 102, 255, 1)",
                "rgba(255, 159, 64, 1)"
            ],
            "borderWidth": 1
        }]
    },
    "options": {
        "scales": {
            "yAxes": [{
                "ticks": {
                    "beginAtZero": true
                }
            }]
        }
    }
}
```

Note：the key in json should be with quotes, or there will be some unexpected errors…

Diagram (mermaid)

mermaid is used to create diagrams in articles. Refer to the documentation of mermaid for the methods of creating diagrams.

Example：

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!

```mermaid
sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
```

Tag

info

`info`{:.info}

success

`success`{:.success}

warning

`warning`{:.warning}

error

`error`{:.error}

Alert

A info alert.

A info alert.
{:.info}

A success alert.

A success alert.
{:.success}

A warning alert.

A warning alert.
{:.warning}

An error alert.

An error alert.
{:.error}

Emoji

jemoji is used to generate emojis. This plugin should be installed manually:

gem install jemoji

Here we can know that jemoji has already been installed on Github Pages. Code of all emojis can be found here.

Example:

:smile: :smirk: :racehorse: :wolf:

Image Annotation

This is an image.

![](../img/theme.jpg)

    This is an image.
    {:.desc}

Libraries

Here are all open source libraries used by this theme.

CSS

• Bootstrap
• Font Awesome
• Font Awesome Animation (animation of icons)

JavaScript

• jQuery
• ScrollReveal (enter animation of the post list (home page) and timeline (about page))
• Tocbot (catalog of articles)
• AnchorJS (anchors of articles)
• Gitalk
• Valine
• Chart.js (charts)
• mermaid (diagrams)
• MathJax (math rendering)
• Katex (math rendering)
• Hightlight.js (syntax highlighting)
• hightlight-line-number.js (Highlight.js line numbers plugin)
• Simple-Jekyll-Search (search)
• fastclick (remove click delays on mobile browsers)