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

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.

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.

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