Skip to content

Latest commit

 

History

History
342 lines (221 loc) · 12.2 KB

Manual.md

File metadata and controls

342 lines (221 loc) · 12.2 KB
Raw

Hux Blog User Manual

Getting Started

  1. You will need Ruby and Bundler to use Jekyll. Following Using Jekyll with Bundler to fullfill the enviromental requirement.

  2. Installed dependencies in the Gemfile:

$ bundle install
  1. Serve the website (localhost:4000 by default):
$ bundle exec jekyll serve  # alternatively, npm start

Development

To modify the theme, you will need Grunt. There are numbers of tasks you can find in the Gruntfile.js, includes minifing JavaScript, compiling .less to .css, adding banners to keep the Apache 2.0 license intact, watching for changes, etc.

Yes, they were inherited and are extremely old-fashioned. There is no modularization and transpilation, etc.

Critical Jekyll-related code are located in _include/ and _layouts/. Most of them are Liquid templates.

This theme uses the default code syntax highlighter of jekyll, Rouge, which is compatible with Pygments theme so just pick any pygments theme css (e.g. from here and replace the content of highlight.less.

Configs

You can easily customize the blog by modifying _config.yml:

# Site settings
title: Hux Blog             # title of your website
SEOTitle: Hux Blog          # check out docs for more detail
description: "Cool Blog"    # ...

# SNS settings      
github_username: huxpro     # modify this account to yours
weibo_username: huxpro      # the footer woule be auto-updated.

# Build settings
paginate: 10                # nums of posts in one page

For more options, please check out Jekyll - Official Site. Most of them are very descriptive so feel brave to dive into code directly as well.

Posts

Posts are simply just Markdown files in the _posts/. Metadata of posts are listed in a YAML style front-matter.

For instance, [Hello 2015])(https://huangxuan.me/2015/01/29/hello-2015/) has the front-matter of this:

---
layout:     post
title:      "Hello 2015"
subtitle:   " \"Hello World, Hello Blog\""
date:       2015-01-29 12:00:00
author:     "Hux"
header-img: "img/post-bg-2015.jpg"
catalog: true
tags:
    - Life
    - Meta
---

Note: tags section can also be written as tags: [Life, Meta].

After Rake is introduced, we can use the command below to simplify the post creation:

rake post title="Hello 2015" subtitle="Hello World, Hello Blog"

This command will automatially generate a sample post similar as above under the _posts/ folder.

There are a bunch of advanced configs:

  1. a text style header like this with
header-style: text
  1. Turning on Latex support:
mathjax: true
  1. Adding a mask to the header picture:
header-mask: 0.3

Etc.

SideBar

SideBar provides possible modules to show off more personal information.

# Sidebar settings
sidebar: true   # default true
sidebar-about-description: "your description here"
sidebar-avatar: /img/avatar-hux.jpg     # use absolute URL.

Modules Featured Tags, Mini About Me and Friends are turned on by default and you can add your own. The sidebar is naturally responsive, i.e. be pushed to bottom in a smaller screen (<= 992px, according to Bootstarp Grid System)

Mini About Me

Mini-About-Me displays your avatar, description and all SNS buttons if sidebar-avatar and sidebar-about-description variables are set.

It would be hidden in a smaller screen when the entire sidebar are pushed to bottom. Since there is already SNS portion there in the footer.

Featured Tags

Featured-Tags is similar to any cool tag features in website like Medium. Started from V1.4, this module can be used even when sidebar is off and displayed always in the bottom.

# Featured Tags
featured-tags: true  
featured-condition-size: 1     # A tag will be featured if the size of it is more than this condition value

The only thing need to be paid attention to is featured-condition-size, which indicate a criteria that tags need to have to be able to "featured". Internally, a condition {% if tag[1].size > {{site.featured-condition-size}} %} are made.

Friends

Friends is a common feature of any blog. It helps with SEO if you have a bi-directional hyperlinks with your friends sites. This module can live when sidebar is off as well.

Friends information is configured as a JSON string in _config.yml

# Friends
friends: [
    {
        title: "Foo Blog",
        href: "http://foo.github.io/"
    },
    {
        title: "Bar Blog",
        href: "http://bar.github.io"
    }
]

Keynote Layout

There is a increased trend to use Open Web technology for keynotes and presentations via Reveal.js, Impress.js, Slides, Prezi etc. I consider a modern blog should have first-class support to embed these HTML based presentation so Keynote layout are made.

To use, in the front-matter:

---
layout:     keynote
iframe:     "http://huangxuan.me/js-module-7day/"
---

The iframe element will be automatically resized to adapt different form factors and device orientation. Because most of the keynote framework prevent the browser default scroll behavior. A bottom-padding is set to help user and imply user that more content could be presented below.

Comment

Help Wanted: Moving to a Github-based solution.

Currently, Disqus and Duoshuo are supported as third party discussion system.

First of all, you need to sign up and get your own account. Repeat, DO NOT use mine! (I have set Trusted Domains) It is deathly simple to sign up and you will get the full power of management system. Please give it a try!

Second, from V1.5, you can easily complete your comment configuration by just adding your short name into _config.yml:

duoshuo_username: _your_duoshuo_short_name_
# OR
disqus_username: _your_disqus_short_name_

To the old version user, it's better that you pull the new version, otherwise you have to replace code in post.html, keynote.html and about.html on your own.

Furthermore, Duoshuo support Sharing. if you only wanna use Duoshuo comment without sharing, you can set duoshuo_share: false.

Analytics

From V1.5, Google Analytics and Baidu Tongji are supported with a simple config away:

# Baidu Analytics
ba_track_id: 4cc1f2d8f3067386cc5cdb626a202900

# Google Analytics
ga_track_id: 'UA-49627206-1'            # Format: UA-xxxxxx-xx
ga_domain: huangxuan.me

Just checkout the code offered by Google/Baidu, and copy paste here, all the rest is already done for you.

(Google might ask for meta tag google-site-verification)

SEO Title

Before V1.4, site setting title is not only used for displayed in Home Page and Navbar, but also used to generate the <title> in HTML. It's possible that you want the two things different. For me, my site-title is “Hux Blog” but I want the title shows in search engine is “黄玄的博客 | Hux Blog” which is multi-language.

So, the SEO Title is introduced to solve this problem, you can set SEOTitle different from title, and it would be only used to generate HTML <title> and setting DuoShuo Sharing.

FAQ

cannot load such file -- jekyll-paginate

This blog started in Jekyll 2 time when jekyll-paginate is standard. With Jekyll 3, it's a plugin we included in _config.yml.

Make sure you installed it via plain gem CLI or Bundler.

Releases

V1.8.2

  • Merged #333, #336 from @JinsYin.
  • Add Gemfile due to increasing Bundler using.
  • TODO: multilingual could be more automative via configurations and convention.
  • Drop the entire portfolio page until a big rewrite of a better project page.

V1.8.1

  • Improve multi-lingual implementation, see about.html or _posts/2017-07-12-upgrading-eleme-to-pwa.markdown for a example of uses.

V1.8

  • Brand new Archive page! It combines previous Archive and Tag page and it's backward-cmpatible. Shout out to @kitian616/jekyll-TeXt-theme of bringing this idea.
  • Improve engineering by extracting duplicated liquid templates into reuseable includes. This was proposed in #74 by @Kaijun but postponed for entirely 2.5 years! I wasn't able to merge his PR directly because of long-time divegence but the credit is belonging to @Kaijun.
  • Improved code block. Long-wanted line number are supported out of the box (thanks for @SmilingParadise's help from Sina Weibo), the default theme is updated to Atom One Dark as well (checkout FQA for how to change to your farovite theme)
  • MathJax support by @Voleking in #80. I choose to use the SVG renderer though. See Mathjax, kramdown and Octopress for writing and escaping details.
  • Open Graph Protocol support by @Android-KitKat in #253
  • header-img-credit and header-img-credit-href
  • nav-style: invert and header-style: text

V1.7

  • PWA / Service Worker support.

v1.6

  • Change cdn to cdnjs for better HTTPS support

V1.5.2

  • Feeling annoyed to delete my blog post after clone or pull? Try Boilerplate (Beta) to help you get started quickly and easily merge update.
  • -apple-system is added in font rule, which display beautiful new font San Francisco in iOS 9 by default.
  • Fixed issue#15 about code wrap.

V1.5.1

V1.5

  • Comment and Analytics is configurable now! We also add Google Analytics support and drop tencents. Both documents is updated.

V1.4

V1.3.1

  • Support PingFang (苹方), the new Chinese font presented by OS X El Capitan

V1.3

V1.2

  • Brand new Keynote Layout is provided for easily posting beautiful HTML presentations you have created with this blog

V1.1

  • We now support a clean and gorgeous SideBar for displaying more info
  • Friends is also added as a common feature of blog help you do SEO

V1.0

  • Full-feature Tag support
  • Mobile first user experience optimization
  • Typographic optimization for Chinese Fonts
  • Network optimizaition for China, dropping Google webfont, using local CDN
  • Using Github Flavored Markdown
  • Using Baidu, Tencent/QQ analytics
  • Using DuoShuo as the Disqus-like third party discussion system