Blog

This blog is based on Github page and jekyll.

Installation

It requires Ruby, RubyGems, and bundler.

The following command can install the prerequisites

sudo apt install ruby-full build-essential zlib1g-dev

Sometimes gem is hard to access in some regions. It is recommended to change the source link. As an example,

sudo gem source --add <https://mirror.com> --remove https://rubygems.org/

where <https://mirror.com> is the host of a mirror. The follow installs jekyll and bundler

sudo gem install jekyll bundler

Jekyll Themes

The blog is based on mediator theme. Download the theme and copy it into my own git directory by

git clone https://github.com/dirkfabisch/mediator

Usage

The blog can be used from source with bundle

bundle exec jekyll server

Upgrade

Bundler and Jekyll requires the correct version of Ruby. If Ruby is updated within the system upgrade, bundler and Jekyll both need to reinstall from gem. For example, when Ubuntu 22.04 is upgraded from Ubuntu 20.04, Ruby 3.0 would be installed, but bundler and Jekyll both requires Ruby 2.7. So the two programs would not processing correctly anymore.

To fix this problem, the direct approach is to reinstall bundle with gem.

sudo gem install bundler

Then, bundle can install all required packages by bundle install except webrick because webrick is no longer in the standard library of bundle. However, I have a network issue when run bundle add webrick. It shows “Could not reach host index.rubygems.org. Check your network connection and try again.” The straightforward method is to set a mirror by

bundle config mirror.https://rubygems.org <https://mirror.com>

where <https://mirror.com> is the host of a mirror. However, it still does not work for me, while the mirror still can be reached by ping, curl, and the browser with ipv4. So the problem is strange, but I fix it with root command.

sudo bundle config mirror.https://rubygems.org <https://mirror.com> sudo bundle install sudo bundle add webrick

The ipv6 is also cloased because it seems that bundle only supports ipv4, but it is not sure if this process works.

Jekyll Syntax

This page introduces Markdown syntax used in Jekyll websites. These syntax examples are based on common usage in the Just the Docs theme.

1. Front Matter (YAML Header)

Front Matter is a YAML-formatted configuration block at the top of Jekyll pages, used to set page properties.

---
title: Page Title
layout: Layout Name
nav_order: Navigation Order
description: "Page Description"
permalink: /custom-url-path
---

Parameter Explanation:

2. Headings

Markdown uses # symbols to indicate heading levels, from # (level 1) to ###### (level 6).

# Level 1 Heading
{: .fs-9 }

## Level 2 Heading
{: .fs-8 }

### Level 3 Heading
{: .fs-7 }

Note: The Just the Docs theme supports adding attribute blocks after headings to set CSS classes, such as {: .fs-9 } for setting font size.

3. Attribute Blocks

Attribute blocks are used to add CSS classes or other attributes to the preceding element.

This is a text paragraph.
{: .fs-6 .fw-300 .text-red }

This is a paragraph.
{: .note }

Common CSS Classes:

4. Horizontal Rules

Create horizontal rules using three or more hyphens, asterisks, or underscores.

---

***

___

5. Blockquotes

Use > symbol to create blockquotes.

> This is a blockquote.
> It can span multiple lines.
>
> Empty lines separate quote paragraphs.

[Link Text](https://example.com)

[Link Text](https://example.com "Link Title")

This is a reference-style [example link][1].

[1]: https://example.com "Example Website"

7. Emphasis

Italic

*Italic Text*
_Italic Text_

Bold

**Bold Text**
__Bold Text__

Bold and Italic

***Bold and Italic Text***
___Bold and Italic Text___

8. Footnotes

Footnotes are used to add notes at the bottom of the page.

This is text containing a footnote[^1].

[^1]: This is the footnote content, displayed at the bottom of the page.

9. Code

Inline Code

Use `code` to mark inline code.

Code Blocks

Use three backticks to create code blocks, optionally specifying a language for syntax highlighting.

```python
def hello_world():
    print("Hello, World!")
```

10. Lists

Unordered Lists

- Item One
- Item Two
  - Subitem One
  - Subitem Two
- Item Three

Ordered Lists

1. First Item
2. Second Item
   1. Subitem One
   2. Subitem Two
3. Third Item

11. Liquid Template Syntax

Jekyll supports the Liquid templating language, which can be used within Markdown.

Current Year: 2026

Site Title: Your awesome title

Page URL: /2026/09/05/blog.html

Common Liquid Filters:

12. Callouts

The Just the Docs theme provides special callout syntax.

{: .note }
This is a note callout.

{: .warning }
> This is a warning callout, often combined with blockquotes.

Available Callout Types:

13. Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

14. Task Lists

- [x] Completed Task
- [ ] Incomplete Task
- [ ] Another Incomplete Task

15. Definition Lists

Term One
: Definition One

Term Two
: Definition Two
: Second Definition

Best Practices

  1. Maintain Consistency: Use the same Markdown style throughout the website
  2. Use Front Matter Appropriately: Set appropriate title, description, and navigation order for each page
  3. Use Attribute Blocks Reasonably: Utilize CSS classes provided by the theme to enhance visual effects
  4. Semantic Markup: Use correct heading levels (don’t skip levels)
  5. Accessibility: Add alt text for images, provide meaningful text for links

References