Hello, Blog!

Hi there, I’m Yu!

Update Ongoing

This list will be updated.

I finally set this website up - for this very first blog, I posted some common syntax useful for my future blogging. Note that many of the features below do not apply to generic Markdown document and are specific to this blog system only.

Organization

Heading

## Heading H2

The above syntax gives an H2 level heading. For lower-level headings, simply add more #s at the front.
Remember to leave an empty line both before and after the heading.
Do not use H1-level heading in the main text as one post should have only one H1-level heading, and that should be the post title.

List

* Element 1
* Element 2
    * Sub-element 1
    * Sub-element 2
* Element 3

1. Element 1
2. Element 2
    1. Sub-element 1
    2. Sub-element 2
3. Element 3

* [x] Task 1
* [ ] Task 2
* [ ] Task 3

This renders as:

Element 1
Element 2
- Sub-element 1
- Sub-element 2
Element 3

Element 1
Element 2
1. Sub-element 1
2. Sub-element 2
Element 3

Task 1
Task 2
Task 3

The actual numbers you use to mark the list have no effect on the HTML output Markdown produces. You can use 1. 5. 8.,1. 1. 1. or even 3. 1. 8.. They will be rendered in the same way as 1. 2. 3..
Leave a line before and after the list to avoid incorrect indentation.
We can use + or - instead of * in leading a list element as well, but do not mix them.
Escape: You can display a number character in an ordered list by using its HTML character code (|).

Table

| Syntax       | Description | Test Text     |
| ----------- | :---------: |   ---: |
| Header | Title  |    Here's this   |
| Paragraph   | Text         | And more      |

This renders as:

Syntax	Description	Test Text
Header	Title	Here’s this
Paragraph	Text	And more

Leave a line before and after the table.
Number of dashes and spaces in between pipes are not important.
If alignment is not set, by default the column texts align to the left.
Links, in-line codes, Katex expressions can be nested in table content, but many styles cannot.
Escape
- You can display a pipe (|) character in a table by using its HTML character code (|).
- You can add multiple lines in one cell using the <br> tag.
By default, a MarkDown table will have the first row as the horizontal header; You cannot do a table that has vertical header or without header. For those you need to use HTML tables. A work-around for tables without header is to leave the header row blank:

|   |   |
|---|---|
|__Bold Key__| Value1 |
| Normal Key | Value2 |

Which renders as:


Bold Key	Value1
Normal Key	Value2

Use a GUI like this, this or this for faster table generation.

Tab

{% tabs Overall-name %}

<!-- tab -->

**This is Tab 1.**

<!-- endtab -->

<!-- tab -->

This is Tab 2.

<!-- endtab -->

<!-- tab -->

*This is Tab 3.*

<!-- endtab -->

{% endtabs %}

This renders as:

This is Tab 1.

This is Tab 2.

This is Tab 3.

This feature is powered by hexo-tag-common.
More tests are needed for compatibility of this feature with other syntax.

Paragraph

Paragraph break: Add an empty line between paragraphs.
Line break: Add two trailing spaces after a sentence to make line break.
Read about their difference here.

Formatting

Bold, Italicized, Deleted, Underscored

*Italicized* _Italicized_ 
**Bold** __Bold__
***BnI*** ___BnI___  __*BnI*__ _**BnI**_ **_BnI_**   //Bold and Italicized
~~Deleted text~~

Do not use the _ notation without space (like a very_expensive_car). In such case, use *.
Markdown has no native supports for underscore, superscript or subscript. Use HTML tags to for them. Als0, when formatting multiple lines, use HTML tags:

<em>Italicized</em>
<strong>Bold</strong>
<em><strong>BnI</strong></em>
<s>Deleted text</s>      // strikethough
<del>Deleted text</del>  // deleted line
<u>Underlined Text</u>   // underscore
<ins>Underlined text</ins>  // inserted line
Normal<sup>Superscript</sup>
Normal<sub>Subscript</sub>

These render as:

Italicized
Bold
BnI
~~Deleted text~~
~~Deleted text~~
Underlined Text
Underlined text
Normal^Superscript
Normal_Subscript

For difference between the <ins> and <u> tag, see here.
For difference between the <del> and <s> tag, see here.

Color, Size, Font

Markdown does not have native syntax to support font type, size or color. We use HTML CSS (Do not just use the <font> tag. It is no longer supported in HTML5):

All the CSS below are shown with in-line style, which is:

<text-type style="attribute:value;">Text Content</text-type>

text-type can be <p>(main text),<h2>(H2 Heading) and etc. The example codes below uses <p>.

For advanced use of CSS, I found w3school as a good starting point.

To format font type, size or color, use:

<p style="color: #FF0000;">Text in color</p>
<p style="font-size:30px">Text in 30 px.</p>
<p style="font-family:monospace">Text in monospace font family.</p>

These render as:

Text in color

Text in 30 px.

Text in monospace font family.

Color:
- Pick a color using Hex code. To achieve the desired color, use an online color picker like this.
- Some colors have aliases. Check here.
Font Family: Only serif, sans_serif, monospace are currently in this blog system. It is possible to import more.

Alignment

Markdown does not support alignment natively; so, again, we use HTML CSS to achieve the result (Do not just use the <center> tag. It is no longer supported in HTML5):

<p style="text-align: left;">Left-aligned text</p>
<p style="text-align: center;">Centered text</p>
<p style="text-align: right;">Right-aligned text</p>

These render as:

Left-aligned text

Centered text

Right-aligned text

All the above CSS can be used in conjunction with each other (One CSS could have multiple attribute specified).

Separation line

***
---
_________________

They render as:

All look the same.

Empty Line

Compare:

Line 1
&NewLine;
Line 2
&nbsp;
Line 3<br />
Line 4
<p></p>
Line 5
                    //Nothing here
Line 6
                    //One Space here
Line 7
                    //Two Space here                
Line 8              //No trailing space here
Line 9              //1 trailing space here
Line 10             //2 trailing space2 here
Line 11

This will be rendered as:
Line 1

Line 2

Line 3

Line 4

Line 5

Line 6

Line 7

Line 8
Line 9
Line 10
Line 11

Note that although at the first glance some of them look the same, they are different.
- Some of the “empty lines” are selectable and some are not. I am not fully sure about their difference.
- They have different width.
-   is actually an space character (Called “non-breaking space”. For the difference between this and the normal space, refer here), adding a space character to a new line will make the line look like empty.

Line Continuity

The raw tag is meant to avoid Markdown interpretation, but it can be used to mark line continuity.

The first line in editor {% raw %}
{% endraw %} The second line in editor

These two lines will be rendered as one line:
The first line in editor The second line in editor

Stylized Text

Snippet

!!! [type] [title]
    Snippet Content Line 1 
    Line 2

Normal text.

type field could be:
- (blue) note
- (green) info, todo
- (yellow) warning, attention, caution
- (red) error, failure, missing, fail
title field is optional - if left blank, the type field would be used as Title; to completely remove Title, set title to "".
Put 4 spaces (1 tab) in front of each line of snippet content. Put one empty line after the snippet to signal an end. Normal texts come after that.
Other Markdown syntax can be nested inside the snippet. For example:

Warning

Home page of this blog.

a nested quote.

error

Error msg!!! Omit the title.

This is a title

Note content

Info without title

This feature is modified from hexo-admonition.

Quote

> This is a quote.

{% blockquote %}
This is a quote.
{% endblockquote %}

{% blockquote [author[, source]] [link] [source_link_title] %}
This is a quote.
{% endblockquote %}

They would be rendered as something like these:

This is a quote.

{% blockquote Seth Godin http://sethgodin.typepad.com/seths_blog/2009/07/welcome-to-island-marketing.html Welcome to Island Marketing %}
Every interaction is both precious and an opportunity to delight.
{% endblockquote %}

The latter syntax are not Markdown native syntax. They rely on Hexo-Tag-Plugins. Instead of blockquote you can also use its alias quote. Using this syntax allows you to define more fields for the quote.
If the quote contains more than one paragraph, use:

> Quote Paragraph 1
>
> Quote Paragraph 2

which renders as:

Quote Paragraph 1

Quote Paragraph 2

The quote block can also be nested or/and used with other markdown syntax:

Some codes here
List Element 1.

hyperlink

List Element 2.

Nested Quote

Blah blah blah.

Code

This blog’s code highlighting feature is powered by Prism.

``` [language name] [title] [url] [link text] [additional options]
code snippet
```

{% codeblock [title] [lang:language] [url] [link text] [additional options] %}
code snippet
{% endcodeblock %}

They all give a code block (which is also how the code block style is implemented everywhere in this blog post).
Note the markdown only supports the language name field - hexo has expanded on that to allow more fields.
Moreover, the latter syntax are not Markdown native syntax. They rely on Hexo-Tag-Plugins. Instead of codeblock you can also use its alias code.
For language name:
- Use csharp OR cs OR dotnet for C#
- Use cpp for C++
- Use c for C
- Use md or markdown for Markdown
- Use py or python for Python
- Use java for Java
- Use json for JSON
  …
- For the full list of support language, see here.
For additional options: I have checked the documentation - it seems none can work in this blog. Ignore this option.

If you want in-line code, use:

...`Some in-line Code`...

This renders something like this.

Hint

{% hint 'body_text' 'hint_text' %}

For multiple-line hint, separate lines to be multiple fields:

{% hint 'body_text' 'hint_text_line_1' 'hint_text_line_2' ... %}

This feature is powered by hexo-tag-hint.

Known Bug

The hint bubble will not be rendered if there are texts in front of the hint tag at the same line. I have raised an issue to the package manager. For now, a work-around is to use the raw tag to surround all texts at the front. See:

{% raw %}This is a {% endraw %}{% hint 'hint title' 'hint text' %}!

This renders as:

This is a hint title!

Footnote

Github Markdown does not support the footnote. We can fake it by:

This is some argument<sup>[1](#myfootnote1)</sup>.

<sup><a name="myfootnote1">1</a></sup> Footnote content goes here...

This renders as:

This is some argument¹.

¹ Footnote content goes here…

This is essentially HTML formatting, modified from suryasankar’s implementation.
The<sup>makes it superscript.
The #myfootnote1 makes it clickable.

Multimedia

Hyperlink

This is a hyperlink that leads to this blog’s Home Page. This uses:

[Link Title Text](link itself "Link Description Text")

[Link Title Text][1]
[1]: <link itself> "Link Description Text"

OR, using hexo-tag-plugins:

{% Link Title Text [link itself] [Link Description Text] %}

Link does not have to be urls. You can link to a local image in the source folder using the same syntax.
You can omit the description text and the surrounding quotation marks.
You can also mix stylized string (bold, italicized, code, etc.) into link title text.
To display links literally, simply put:

<link url>

For example, my blog home page link, if implemented literally, would be rendered as:
https://reimirno.github.io

But even if you do not use <...>, if an address is entered it would be automatically converted into a hyperlink. To avoid this, put the link address as in-line codes.

If you are including links to your other post, simply use:

{% post_link filename [title] [escape] %}

Simply put the post filename you want to link to. This syntax would find the correct .md file, ignoring its permalink, directory etc.
Special characters set in the title texts would be escaped by default. Set the escape field to false to avoid this.

Image

The native Markdown syntax is:

![image tooltip](image link)

Or, using HTML tag:

<img src = "image link" alt = "image description" title = "image tooltip" width = "" height = "">

Or, using hexo-tag-plugin:

{% img [class names] /path/to/image [width] [height] '"title text" "alt text"' %}

Or, since the asset folder option is turned on in this blog system, we can also use:

{% asset_img [class names] slug [width] [height] [title text [alt text]] %}

In posts, use relative path for links (as the asset folder option is turned on). Relative paths is with respect to two parent folders:
- The Global Asset Folder: The themes/yun/source/images folder.
- The Post Asset Folder: the folder which has the same name as the blog post, placed in the same directory as the .md file.
.gif images are also supported.
Leaving the width and height field empty means using default value. Their values are in pixel or percentage.

Known Bug

There is a bug in Hexo 5.4.0. When post_asset_folder is set to true, due to an internal bug in hexo-asset-image the images cannot be rendered. See here for the solution.

Music

There are numerous ways of importing audios… The method I go with is to use hexo-tag-aplayer.

For the APlayer to take effect in a post, include aplayer: true in the front matter of that post.

For general song:

{% aplayer "title" "author" "url" [picture_url, narrow, autoplay, width:xxx, lrc:xxx] %}

For generic playlist:

{% aplayerlist %}
{
    "narrow": false,                           // Optional: mini-styled playlist
    "autoplay": true,                          // Optional; not supported on mobile devices
    "mode": "circulation",                     // 'random', 'single', 'circulation', 'order'
    "showlrc": 1,                              // The style to show lyrics：1,2,3
    "mutex": true,                             // When this is true, this player would pause when another aplayer starts at the same page
    "theme": "#b7daff",	                       // Color theme
    "preload": "auto",                         // 'none' 'metadata' 'auto'
    "listmaxheight": "513px",                  
    "music": [
        {
            "title": "CoCo",
            "author": "Jeff Williams",
            "url": "caffeine.mp3",
            "pic": "caffeine.jpeg",
            "lrc": "caffeine.txt"
        },
        {
            "title": "アイロニ",
            "author": "鹿乃",
            "url": "irony.mp3",
            "pic": "irony.jpg"
        }
    ]
}
{% endaplayerlist %}

For China’s music platform (NetEase, Tencent, Kugou, Baidu etc.), use meting syntax (this is an extension from Aplayer):

{% meting "id" "server" "type" [various configurations] %}

The compulsory parameters:
- id: song/playlist id, search keyword
- server: netease,tencent,kugou,baidu etc.
- type: song, playlist, album, artist, search
The optional parameters (show only the useful ones, for the full list, refer to the documentation):
- put "fixed" to dock the player, "mini" to minimize the player
- put "listfolded:true" to fold the playlist (by default it is false)
- "loop = ...": all(by default),one,none
- "order = ...": list(by default),random
- autoplay, mutex, listmaxheight, preload, theme: refer above

To unify layout style, I put a fine-tuned code snippet for Netease music here (for copy-pasting later):
A song:

{% meting "id" "netease" "song" "mutex:true" "theme:#C20C0C" %}

A(n) playlist/album/artist/search (change type accordingly):

//10 songs shown: (about 33px per song, tested on my screen)
{% meting "id" "netease" "playlist" "mutex:true" "listmaxheight:330px" "theme:#C20C0C"%} 
//5 songs shown:
{% meting "id" "netease" "playlist" "mutex:true" "listmaxheight:165px" "theme:#C20C0C"%}
//folded:
{% meting "id" "netease" "playlist" "mutex:true" "listfolded:true" "theme:#C20C0C"%}
//docked:
{% meting "id" "netease" "playlist" "mutex:true" "fixed" "theme:#C20C0C"%}

I am feeling like exemplifying this by putting this piece here:

Video

Again, there are really numerous ways of inserting videos:

Using iframe - and iframe has both an HTML and a Hexo version.
Using video tag.
Using third-party plugins designed for videos uploaded onto a specific site ({% youtube video_id [type] [cookie] %} for YouTube, for example; by the way, this syntax has a very strange layout).
And more…

But they all have some layout issues, even on desktop computers. As I am not a Front-End Engineer (thus far), the best (or so I think) solution I found is to use a fine-tunes iframe importing method for videos from all platform in general (so, the layout is unified, at least):

<div style="position: relative; padding: 30% 45%;">
<iframe style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;" 
src="..." 
frameborder="no" scrolling="no" loading="lazy" allow="fullscreen">
</iframe>
</div>

This snippet of code is modified from here.
You cannot copy the url link in the address bar for the src field, in general. You need to find the share button on the video site and get the embed iframe code.
- For YouTube, there are some customizable options when exporting the embed code (like privacy options).
- For Bilibili, add “&as_wide=1&high_quality=1&danmaku=0” to the end of the src field obtained.

Here is a Bilibili video:

If the thing you want to include is not a video player but simply a “video card”, there is a plugin for bilibili video card to implement (I do not see the need currently).

Document

The best practice is to convert everything to .pdf format first and then distribute. To set up a Pdf viewport in the post, use:

{% pdf pdf-link %}

For example:

This feature is powered by hexo-pdf. As usual, the pdf-link can be local or online. You can also use a Google Drive Pdf Preview link or Slideshare Embed Link - check the documentation page.

More Multimedia

Emoji

:happy: :sparkles:
This renders as: :happy: :sparkles: * This feature is powered by [hexo-filter-github-emojis](https://github.com/crimx/hexo-filter-github-emojis). * Simply surrounds the emoji name with two colons. * For a reference list of emoji, refer to [emojipedia](https://emojipedia.org/) or [Emoji Cheatsheet](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md).

Feature Not Working

The above feature does not work. I'm working on it.

Icon

I have imported the CSS file for Remix Icons into this site. To insert an icon, simply use this syntax:

<div style="font-size: 24px;">
  <i class="ri-admin-line ri-fw"></i> <!-- fixed width -->
  <i class="ri-admin-line ri-xxs"></i> <!-- 0.5em -->
  <i class="ri-admin-line ri-xs"></i> <!-- 0.75em -->
  <i class="ri-admin-line ri-sm"></i> <!-- 0.875em -->
  <i class="ri-admin-line ri-1x"></i> <!-- 1em -->
  <i class="ri-admin-line ri-lg"></i> <!-- 1.3333em -->
  <i class="ri-admin-line ri-xl"></i> <!-- 1.5em -->
  <i class="ri-admin-line ri-2x"></i> <!-- 2em -->
  <i class="ri-admin-line ri-3x"></i> <!-- 3em -->
  ...
  <i class="ri-admin-line ri-10x"></i> <!-- 10em -->
</div>

The above renders as:

...

For the complete list of icon names, visit Remix Icon’s website.
Size will be automatically adjusted to match to text size. To adjust its relative size with respect to text, see the above code.
Color can be changed by adding style="color:...;" after the class field - these icons are really just another font. For example:

<i class="ri-article-line" style="color:#7ccbab;"></i>

This renders:

Mathematics

This site uses KaTex for displaying mathematical expressions. If a post needs it, the front matter should have a line katex: true, because I did not enable KaTex globally to avoid loading it for no reason.
A mathematical expression can be implemented by:

$$ \frac{\partial}{\partial t} $$
\\[ E = mc^2 \\]

This renders as:
$$ \frac{\partial}{\partial t} $$
\[ E = mc^2 \]
In-line expressions use this syntax:

$\frac{\partial}{\partial t}$
\\( E = mc^2 \\)

These two expressions are rendered as $\frac{\partial}{\partial t}$ and $ E = mc^2 $ respectively.

Note that we use two \s since we need to escape the symbol \ in Markdown. To avoid this, use <div></div> HTML tag to surround the expression so that it will not be read as Markdown. Like this:

<div>\( E = mc^2 \)</div>

KaTex syntax cannot be placed in quote or code block.
For the full list of supported expressions in KaTex, check the official documentation.
Use an online LaTex editor like this to speed up the process.

Chart

There are various solutions for charts: hexo-tag-chart which uses ChartJS support, hexo-tag-goolgecharts which uses Google Chart support, hexo-tag-echarts3 which uses ECharts support, and hexo-tag-easy-charts etc. I will implement one of them when I need to include charts in posts.

Location

Use Google Map (For addresses outside China) or Gaode Map (in-China address) to export iframe. Use the same iframe syntax as the video viewer:

<div style="position: relative; padding: 30% 45%;">
<iframe style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;" 
src="..." 
frameborder="no" scrolling="no" loading="lazy" allow="fullscreen">
</iframe>
</div>

An example, using Google Map, is:

Wikipedia

{% wikipedia title:... [wikiButton:true] [lang:en] [sentence] %}

This displays a excerpt card for a wikipedia page, powered by hexo-tag-wikipedia.

The title field and the lang field must be formatted with the wiki url. For example, the title would be Touhou_Project and lang be en for the wikipage https://en.wikipedia.org/wiki/Touhou_Project. lang is optional - if omitted, it would be en by default.

The sentence field limits the number of sentences to show if specified. It only accepts value ranging from 1 to 10. It is optional - if omitted, the full excerpt would be shown.

The wikiButton controls whether to show a wikipedia link at the button.

Feature Not Working

The above feature does not work. I have raised an issue to the package manager.

Steam Game

This is important to my blog as I will also publish my steam game projects here.

For a single game:

{% steamgame appid description %}

For a list of games:

{% steamgames %}
appid
appid
appid
appid
{% endsteamgames %}

The description field is optional; if filled, it will substitue game’s original Steam Page description.
This feature is powered by hexo-tag-steamgame.

The game will be rendered like this (this is my first large game projects):

Downloadable Content

For now, use a hyperlink to a Dropbox / BaiduYun resource file.

I will try to make a wrapper style for these kind of special links, later.

Buy me a cup of coffee?

Post author: Long Yu
Post link: https://reimirno.github.io/2021/08/01/Hello-Blog/
Copyright Notice: All articles in this blog are licensed under unless otherwise stated.