mincong.io

Hi, welcome to my blog! I'm a software engineer at Composable. I write blog posts in my free time. My blogs are bits and pieces of my tech journey. Most of them are related to Java. Hope you enjoy them! My opionions are my own, not Composable's. This blog is powered by Jekyll, a simple, blog-aware, static sites solution. It is also powered by TeXt Theme, a super customizable Jekyll theme written by Tian Qi (kitian616).

• Install and Run
• Generators
• Blog Post
  • Types of Blog Post
  • Configuration
• Collections
• Search
  • Indexing Documents
  • Querying Documents
• Assets
• Social Network Sharing
• WeChat
• Useful References

Install and Run

Install required Jekyll plugins, then run Jekyll:

# if `bundle` command is not available
# install bundler first
gem install bundler

# install Jekyll plugins (gems) required
# by this blog using bundler
bundle install

# run Jekyll
jekyll serve

Or run via Docker:

# full generation
./docker-jekyll.sh serve

# incremental generation
./docker-jekyll.sh serve --incremental

Generators

Create new blog post (article). By default, only English post is created:

$ ./newpost.sh My New Post
Blog post created!
  EN: /Users/minconghuang/github/mincong-h.github.io/_posts/2021-11-14-my-new-post.md
  CN: (disabled)

Print help:

$ ./newpost.sh -h
Usage:

       newpost.sh [OPTIONS] TITLE


Options:

       -d,--debug   Print debug logs
       -h,--help    Show help
       -e,--en      Generate English post
       -c,--cn      Generate Chinese post
       -a,--all     Generate post in all languages (English and Chinese)
          --qna     Generate post using a Q&A (Question and Answer) template


Examples:

       newpost.sh My Post Title

       newpost.sh --all My Post Title
       newpost.sh -a My Post Title

       newpost.sh --en My Post Title
       newpost.sh --cn My Post Title

       newpost.sh -h

Create new tag page:

$ ./newtag.sh Java EE
Tag page created: /Users/mincong/github/mincong-h.github.io/tags/java-ee.md

Blog Post

Types Of Blog Post

There are two types of blog post: classic and Q&A.

Classic blog post is a blog post that describes a language feature, a framework, an architecture; translates a meaningful article; project review; or anything that is rather long and insightful. It is rich in content, i.e. going deep in a topic or showing the big picture. This should be interesting for the audience to follow. A classic blog post typically requires several hours of writing and contains 3000+ words. It consists of an introduction, 3 to 4 sections, notes for going further, conclusion, and references. Generating a classic blog post can be done using the following command:

$ ./newpost.sh My Regular Post Title

Q&A blog post is a blog post that answers a specific question. It consists one question and one answer. Compared to classic blog post, it's much shorter and means less work (done in less than 2 hours with less than 1000 words). Usually it means the question is specific to a language and a framework. You can consider it as questions you see on https://stackoverflow.com. It consists of one question, one answer, notes for going further, and references. But why creating Q&As? For readers, it aims to provide them useful information without the needs to understand the underlying implementation. For author, it means having faster delivery speed, providing more arguments for the classic blog posts, and having more page views (classic blog posts are not SEO friendly). Generating a Q&A blog post can be done using the following command:

$ ./newpost.sh --qna My Question

Configuration

Property	Type	Description
article_num	Integer	The number of the article (post). This is a positive decimal value which represents the number of the article starting from 1. Don't confuse with article id (post id) is the URL of the article, e.g. "elasticsearch-corrupted-index". One article number can correspond to multiple pages, one per language. For example, article Nº 182 is Elasticsearch corrupted index, which has two versions, respectively written in English and Chinese. When using the generator script (newpost.sh), the number will be incremented automatically under file .article_num.
type	String	The type of the blog post: "classic", "Q&A".
image	URL	Related path to image resource, such as /assets/my-image.jpg. Jekyll will complete it as an absolute path. Used by Jekyll Feed plugin, Jekyll SEO tag and Twitter cards.
cover	URL	Related path to image resource, such as /assets/my-image.jpg. Used for Jekyll TeXt Theme.
lang	String	The language tag of the post: en or zh.
date	Date	A humain readable date string (ISO-8601 like) for the creation date time of the blog post, e.g. "2018-08-22 21:57:07 +0200"
date_modified	Date	A humain readable date string (ISO-8601 like) for the latest modification date time of the blog post, e.g. "2021-03-07 16:47:00 +0200"
series	String	A meaningful name for the series. The value will be slugify for generating the URL. For example, giving value "Maven Plugins" will generate maven-plugins for the URL.
comments	Boolean	Whether the comments section will be enabled. Default to true.
subtitle	String	The subtitle of the blog post in one sentence.
wechat	Boolean	Whether WeChat QR code should be shown. Default to false.

Collections

Collection Directory	Description
_posts	Blog posts written in English.
_cn	Blog posts written in Chinese.
_displayed_en_categories	Categories displayed for users, written in English.
_displayed_cn_categories	Categories displayed for users, written in Chinese.

Search

Indexing Documents

Indexing documents are done during the build process of the website, usually in the CI. This is powered by the custom BlogSearch plugin (_plugins/hooks/site/post_write/blogsearch.rb). To debug it, you can set environment variable BS_ENABLED and then build/serve the Jekyll website. Username (BS_USERNAME) and password (BS_PASSWORD) are required.

Querying Documents

The search feature is powered by Nanosearch (nanosearch), a custom search solution that I created based on Java, OpenAPI and Elasticsearch.

Assets

When adding a new image to the website, you need to register its metadata in _data/images.yml.

• https://unsplash.com Beasutiful free images & pictures
• https://pixabay.com 2.6 million+ strunning free images to use anywhere

Social Network Sharing

Website	Preview Tool
Facebook	https://developers.facebook.com/tools/debug/sharing/
LinkedIn	https://www.linkedin.com/post-inspector/
Twitter	https://cards-dev.twitter.com/validator

WeChat

Edit using 墨滴 https://www.mdnice.com/ which converts markdown into WeChat article.

格式：

• 格式化文档，让英文单词和中文字符之间加空格
• 微信外链转脚注，优雅处理微信中外部链接无法点击的问题。有些时候代码监测不出来，需要手动修改。
• 取消衬线字体

主题：

• 橙蓝风（axuebin）

代码主题：

• 选择 atom-one-dark
• 取消 Mac 风格

内容：

• “参考资料”改成“外部链接”

Useful Resources

• Jekyll cheatsheet (https://devhints.io/jekyll)